harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Geir Magnusson Jr." <g...@pobox.com>
Subject Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Thu, 30 Nov 2006 06:54:23 GMT
I think that they can go on the site in some way, but I just still don't 
think we should check them in there.

If we are checking the stuff into SVN, we should probably do so local to 
where generated (DRLVM docs in drlvm part of svn...) and just use svn 
externals from the web site...

geir

Morozova, Nadezhda wrote:
>> So, do we want to actually commit the generated content into the
> website
>> tree?  I am kinda resistant to do so for reasons I can't defend very
> well.
> 
> Well, the whole docset for drlvm only is ~5MB, with *many* pages empty
> now. We can dream of times when all of them are in an ideal shape, but I
> don't think it's realistic at this stage. If not, why have them? 
> 
> Suggested compromise: 
> Have only the top-level interfaces documentation for DRLVM + classlib on
> site with ability to generate all the rest locally.
> For classlib, that could be kernels and vmi, for drlvm that could be
> intercomponent - mostly located in the vm/include folder (see accurate
> listing at
> http://wiki.apache.org/harmony/DRLVM_Documentation_Interfaces_Classifica
> tion 
> 
> For a clearer view, I'd post the drlvm docs on my home. If we agree
> these can go on site, would be great. Having a starting page for
> interfaces code on the site would be marvelous too. 
> 
> Cheers, 
> Nadya
>  
> 
>> -----Original Message-----
>> From: Geir Magnusson Jr. [mailto:geir@pobox.com]
>> Sent: Wednesday, November 29, 2006 8:16 PM
>> To: dev@harmony.apache.org
>> Subject: Re: [doc] What should be improved in DRLVM Doxygen
> documentation?
>>
>> Morozova, Nadezhda wrote:
>>>> So, the answer is "No" because it is not committed. Thanks, I know
> the
>>>> JIRA. Aren't we ready to commit these?
>>> Well,
>>> Largely, yes, though the config file does not allow for class
> hierarchy,
>>> file lists and graphics. I hope Alexei can adjust the scripts to
> check
>>> for the graphviz dot tool required for class diagrams.
>>> Anyway, the scripts will be in the svn soon; I was also planning to
>>> generate the whole bundle and deposit on my home - just as Paulex did
>>> yesterday.
>> So, do we want to actually commit the generated content into the
> website
>> tree?  I am kinda resistant to do so for reasons I can't defend very
> well.
>> Certainly the scripts should be there...
>>
>> geir
>>
>>
>>> Cheers,
>>> Nadya
>>>
>>>> -----Original Message-----
>>>> From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
>>>> Sent: Wednesday, November 29, 2006 10:39 AM
>>>> To: dev@harmony.apache.org
>>>> Subject: Re: [doc] What should be improved in DRLVM Doxygen
>>> documentation?
>>>> On the 0x22F day of Apache Harmony Nadezhda Morozova wrote:
>>>>>> BTW, do we have vm.cfg committed as well as all other stuff
>>> necessary
>>>>>> to generate Doxygen docs?
>>>>> Yes, see JIRA 2024 and download the doc.scripts.zip bundle. It has
>>> the
>>>>> build file, the vm.cfg for Doxygen and the doc.properties to feed
> as
>>> the
>>>>> build targets.
>>>>> Unload the files into the vm/doc/ directory and run ant. Should
> work.
>>>> So, the answer is "No" because it is not committed. Thanks, I know
> the
>>>> JIRA. Aren't we ready to commit these?
>>>>
>>>>> Cheers,
>>>>> Nadya
>>>>>
>>>>>
>>>>>> -----Original Message-----
>>>>>> From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
>>>>>> Sent: Tuesday, November 28, 2006 2:20 PM
>>>>>> To: dev@harmony.apache.org
>>>>>> Subject: Re: [doc] What should be improved in DRLVM Doxygen
>>>>> documentation?
>>>>>> On the 0x22E day of Apache Harmony Nadezhda Morozova wrote:
>>>>>>> Thanks for valuable feedback! We've got so many things to do.
>>>>>> u r welcome :)
>>>>>>
>>>>>>> I've used the key JIRA for Doxygen docs that we have now:
>>>>>>> http://issues.apache.org/jira/browse/HARMONY-2024 submitted by
>>> Alexei
>>>>> F.
>>>>>> yes, I am looking in it too
>>>>>>
>>>>>>> There, we actually have two different doc sets:
>>>>>>> Drlvm_intf_doc is for the whole bundle, and vm_doc.scripts.zip
>>>>> enables
>>>>>>> you to build component-wise documentation. Which one do we want?
>>>>>> I prefer *full docs* for all source files so I could travel
> through
>>>>>> the docs where I want. So, drlvm_intf_doc..
>>>>>>
>>>>>>> I've been thinking of how to best add Doxygen docs to the
> website,
>>>>>>> suggest the following:
>>>>>>>
>>>>>>> standard/site/xdocs/subcomponents/classlib/doxygen/index.html
-
>>> for
>>>>>>> classlib bundle(s).
>>>>>>> standard/site/xdocs/subcomponents/drlvm/doxygen/index.html -
for
>>>>> drlvm
>>>>>>> bundle(s).
>>>>>>> standard/site/xdocs/stylesheets/* - for the config files and
>>> scripts
>>>>> to
>>>>>>> build Doxygen documentation.
>>>>>>> Any objections?
>>>>>> Nadya, you have more expertise in this field :)
>>>>>>
>>>>>> BTW, do we have vm.cfg committed as well as all other stuff
>>> necessary
>>>>>> to generate Doxygen docs?
>>>>>>
>>>>>>> Cheers,
>>>>>>> Nadya
>>>>>>>
>>>>>>>
>>>>>>>> -----Original Message-----
>>>>>>>> From: news [mailto:news@sea.gmane.org] On Behalf Of Egor
Pasko
>>>>>>>> Sent: Monday, November 27, 2006 1:04 PM
>>>>>>>> To: dev@harmony.apache.org
>>>>>>>> Subject: Re: [doc] What should be improved in DRLVM Doxygen
>>>>>>> documentation?
>>>>>>>> On the 0x22B day of Apache Harmony Alexei Fedotov wrote:
>>>>>>>>> Ooops.... Sorry for incorrect word usage. I was intended
to ask
>>>>> who
>>>>>>>>> will read Doxygen on our site and for which purpose.
This would
>>>>> help
>>>>>>>>> us to understand what we should put there.
>>>>>>> >From other projects I found Class hierarchy most useful in
>>> Doxygen.
>>>>> It
>>>>>>>> is also useful for beginners to see the top-level structure
of
>>> the
>>>>>>>> code in a comprehensive manner. See [1] as a live example
of
>>> on-site
>>>>>>>> doxygen in an opensource project.
>>>>>>>>
>>>>>>>> I love to travel through the code in vim+ctags, but it is
not
> the
>>>>> best
>>>>>>>> for all. So, I would vote for putting the Doxygen docs on
the
>>> site
>>>>> as
>>>>>>>> it should be useful. The sooner the better because it should
> help
>>>>>>>> people express their opinions on _what should be improved_.
> Today
>>> it
>>>>>>>> is not easy to say $subj if you do not see the docs out there..
>>> have
>>>>>>>> to download 10MB, etc. etc.
>>>>>>>>
>>>>>>>> I should have said that long ago.. but.. too busy, sorry
:(
>>>>>>>>
>>>>>>>> Today I downloaded th 10MB drlvm_intf_doc.zip and looking
at it.
>>>>>>>> Some comments:
>>>>>>>> * header page is too brief
>>>>>>>> * no class hierarchy & class inheritance sexy pictures
>>>>>>>> * no source code browsing
>>>>>>>> * per-file view wastes a lot of space
>>>>>>>>
>>>>>>>> Let's have the next step forward: put doxygen docs on the
site!
>>> And
>>>>>>>> regenerate them regularly (=as snapshots appear, for
>>>>>>>> example). How-to-improve opinions will come.
>>>>>>>>
>>>>>>>> [1]
>>>>> http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/index.html
>>>>>>>>> On 11/24/06, Alexei Fedotov <alexei.fedotov@gmail.com>
wrote:
>>>>>>>>>> All,
>>>>>>>>>>
>>>>>>>>>> Let me support Nadya's request. The first thing we
need to do
>>> is
>>>>> to
>>>>>>>>>> define what we are trying to achieve. Who is our
target
>>>>> auditory?
>>>>>>>>>> 1. Egor said that he liked browsing object dependencies
using
>>>>>>> Doxygen.
>>>>>>>>>> 2. Salikh said that he personally found browsing
source files
>>>>> much
>>>>>>> more
>>>>>>>> useful.
>>>>>>>>>> 3. All my cases are about situations when one programmer
used
>>>>>>>>>> interfaces developed by another programmer.
>>>>>>>>>>
>>>>>>>>>> Could you please share your experience with wonderful
>>>>>>> Doxygen/javadooc
>>>>>>>> browsing?
>>>>>>>>>> --
>>>>>>>>>> Thank you,
>>>>>>>>>> Alexei
>>>>>>>>>>
>>>>>>>>>> On 11/24/06, Morozova, Nadezhda <nadezhda.morozova@intel.com>
>>>>>>> wrote:
>>>>>>>>>>> Hi,
>>>>>>>>>>>
>>>>>>>>>>> I've tried out the scripts that build Doxygen
docs for
>>> DRLVM.
>>>>> I
>>>>>>> like
>>>>>>>> the
>>>>>>>>>>> resulting input immensely, though further improvements
>>> might
>>>>> be
>>>>>>>> required
>>>>>>>>>>> - will write specific suggestions later.
>>>>>>>>>>>
>>>>>>>>>>> At this point, my key question is the following:
How do we
>>>>> want
>>>>>>> to
>>>>>>>>>>> organize our docs? Possible solutions:
>>>>>>>>>>> - harmony_intf_doc: classlib + drlvm docs, one
huge bundle.
>>>>>>>>>>>        Not sure it can work ok or be easy to
maintain,
>>> but...
>>>>>>>>>>> - drlvm_intf_doc + classlib_intf_doc: two bundles;
>>>>>>>>>>>        drlvm_intf was submitted by Alexei to
the same JIRA
>>> -
>>>>> can
>>>>>>> use
>>>>>>>> as
>>>>>>>>>>> a       starting point.
>>>>>>>>>>> - separate bundles for each big component/module
inside
>>>>>>>> drlvm/classlib.
>>>>>>>>>>>        This is how Alexei's scripts work now.
>>>>>>>>>>>
>>>>>>>>>>> To me, structuring into subdirs is fine. It helps
browsing,
>>>>>>>> localizing
>>>>>>>>>>> specific files, works marvelously for the wiki
metrics
>>>>> pages...
>>>>>>>>>>> BUT!
>>>>>>>>>>> With subdirs, you never get a full list of
>>>>>>> files/funcs/structs/etc
>>>>>>>> for
>>>>>>>>>>> the whole drlvm and if you search for a specific
item,
>>> you'll
>>>>>>> have to
>>>>>>>> go
>>>>>>>>>>> from bundle to bundle.
>>>>>>>>>>> This can be partially fixed by an opening page
with links
>>> to
>>>>>>> specific
>>>>>>>>>>> component bundles. However, indexing and search
would still
>>> be
>>>>>>>>>>> component-wise only.
>>>>>>>>>>>
>>>>>>>>>>> There might be more arguments pro and contra.
Everyone -
>>>>> please
>>>>>>>> express
>>>>>>>>>>> your preference!
>>>>>>>>>>>
>>>>>>>>>>> PS: Alexei, thanks for a warm welcome, I'll work
hard to
>>> meet
>>>>>>> your
>>>>>>>>>>> expectations.
>>>>>>>>>>>
>>>>>>>>>>> Cheers,
>>>>>>>>>>> Nadya
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>> -----Original Message-----
>>>>>>>>>>>> From: Alexei Fedotov [mailto:alexei.fedotov@gmail.com]
>>>>>>>>>>>> Sent: Friday, November 24, 2006 4:33 AM
>>>>>>>>>>>> To: dev@harmony.apache.org
>>>>>>>>>>>> Subject: Re: Re: [doc] What should be improved
in DRLVM
>>>>> Doxygen
>>>>>>>>>>>> documentation?
>>>>>>>>>>>>
>>>>>>>>>>>> Nadya,
>>>>>>>>>>>>
>>>>>>>>>>>> My congratulations with your new role. Now
I believe
>>> nothing
>>>>>>> will
>>>>>>>>>>>> prevent Harmony web site and documentation
from being the
>>>>> best
>>>>>>> and
>>>>>>>> the
>>>>>>>>>>>> coolest one. :-)
>>>>>>>>>>>>
>>>>>>>>>>>> I have prepared a documentation update according
Andrey's
>>>>> Wiki
>>>>>>> page
>>>>>>>>>>>> (with Egor's and Pavel's comments), see the
last comment
>>> to
>>>>>>>>>>>> http://issues.apache.org/jira/browse/HARMONY-2024.
The
>>>>>>> documentation
>>>>>>>>>>>> contains component bundles and inter-component
interface
>>>>> bundle.
>>>>>>> If
>>>>>>>>>>>> you find results useful, please don't hesitate
to ask
>>>>> questions
>>>>>>>> about
>>>>>>>>>>>> how it works.
>>>>>>>>>>>>
>>>>>>>>>>>> I also updated documentation metrics per
bundle at the
>>> Wiki
>>>>>>> page:
>>>>>>>>>>>> http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
>>>>>>>>>>>>
>>>>>>>>>>>> Many of .html files contain "The documentation
for this
>>>>> struct
>>>>>>> was
>>>>>>>>>>>> generated from the following file:" footer,
so it
>>> shouldn't
>>>>> be a
>>>>>>>>>>>> problem to understand which source file should
be editied
>>> to
>>>>>>> improve
>>>>>>>>>>>> the metrics.
>>>>>>>>>>>> --
>>>>>>>>>>>> Thank you,
>>>>>>>>>>>> Alexei
>>>>>>>>>>>>
>>>>>>>>>>>> On 11/21/06, Morozova, Nadezhda
>>> <nadezhda.morozova@intel.com>
>>>>>>> wrote:
>>>>>>>>>>>>>> -----Original Message-----
>>>>>>>>>>>>>> From: news [mailto:news@sea.gmane.org]
On Behalf Of
>>> Egor
>>>>>>> Pasko
>>>>>>>>>>>>>> Sent: Tuesday, November 21, 2006
7:42 AM
>>>>>>>>>>>>>> To: dev@harmony.apache.org
>>>>>>>>>>>>>> Subject: Re: [doc] What should be
improved in DRLVM
>>>>> Doxygen
>>>>>>>>>>>>> documentation?
>>>>>>>>>>>>>> On the 0x227 day of Apache Harmony
Nadezhda Morozova
>>>>> wrote:
>>>>>>>>>>>>>>> That's a great start. Yes, if
we have such a table as
>>>>> the
>>>>>>> front
>>>>>>>>>>> page
>>>>>>>>>>>>> for
>>>>>>>>>>>>>>> Doxygen interfaces, it would
be great. If you wish, I
>>>>> can
>>>>>>>> prepare
>>>>>>>>>>> the
>>>>>>>>>>>>>>> patch with the nice-looking version
of it all.
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> Questions:
>>>>>>>>>>>>>>> - When building Doxygen, can
we have a target for
>>> inter-
>>>>>>>> component
>>>>>>>>>>>>>>> interfaces and for each component?
>>>>>>>>>>>>>>> - if yes, should the files inside
the include/
>>> subfolder
>>>>> be
>>>>>>>> built
>>>>>>>>>>>>> with
>>>>>>>>>>>>>>> the component they belong to?
>>>>>>>>>>>>>>> - For VM core and jit: any ideas
on how to group
>>> files
>>>>>>> further?
>>>>>>>>>>> The
>>>>>>>>>>>>>>> current list of files belonging
to vm core interfaces
>>> is
>>>>>>> *so*
>>>>>>>>>>> long...
>>>>>>>>>>>>>>> - Should we prepare docs for
gcv4?
>>>>>>>>>>>>>> IMO, the list of headers for Jitrino
is too verbose.
>>> For
>>>>>>>>>>>>>> inter-component picture I suggest
the following subset:
>>>>>>>>>>>>>> vm/jitrino/src/dynopt/EdgeProfiler.h
>>>>>>>>>>>>>> vm/jitrino/src/dynopt/StaticProfiler.h
>>>>>>>>>>>>>> vm/jitrino/src/jet/jet.h
>>>>>>>>>>>>>> vm/jitrino/src/main/Jitrino.h
>>>>>>>>>>>>>> vm/jitrino/src/vm/drl/DrlEMInterface.h
>>>>>>>>>>>>>> vm/jitrino/src/vm/drl/DrlVMInterface.h
>>>>>>>>>>>>>> vm/jitrino/src/vm/EMInterface.h
>>>>>>>>>>>>>> vm/jitrino/src/vm/VMInterface.h
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> other headers are internal for Jitrino.
So, the
>>> suggestion
>>>>>>> is: to
>>>>>>>>>>>>>> document the mapping between *relevant*
h-files and the
>>>>>>> structure
>>>>>>>> in
>>>>>>>>>>>>>> the DevGuide
>>>>>>>>>>>>> [Nadya]
>>>>>>>>>>>>> I think we're mixing two different header
groups. The
>>> first
>>>>>>> type
>>>>>>>> is
>>>>>>>>>>>>> *inter-component*, listed at the top
of page on wiki.
>>> The
>>>>>>> devguide
>>>>>>>>>>> shows
>>>>>>>>>>>>> these interfaces in VM arch figure. As
I understand,
>>> these
>>>>> are
>>>>>>> the
>>>>>>>>>>>>> interfaces that any jit must export:
>>>>>>>>>>>>>
>>>>>>>>>>>>>   Execution engine
>>>>>>>>>>>>>   JIT_VM
>>>>>>>>>>>>>      vm/include/internal_jit_intf.h
>>>>>>>>>>>>>       vm/include/open/ee_em_intf.h
>>>>>>>>>>>>> Not sure how these are related to files
>>>>>>>> jitrino/src/vm/*Interface.h.
>>>>>>>>>>>>> The other group is *Interfaces inside
the components*.
>>> Here
>>>>> I
>>>>>>>> think
>>>>>>>>>>> all
>>>>>>>>>>>>> interfaces between internal parts of
a component can go.
>>> I
>>>>>>> agree
>>>>>>>> JIT
>>>>>>>>>>> and
>>>>>>>>>>>>> VM core seem to have too many headers,
but they are all
>>> in
>>>>> the
>>>>>>> dir
>>>>>>>>>>> tree.
>>>>>>>>>>>>> Don't you think we need to document them?
>>>>>>>>>>>>>
>>>>>>>>>>>>> My suggestion would be to add subgrouping
for jit header
>>>>> files
>>>>>>> -
>>>>>>>> and
>>>>>>>>>>>>> possibly assign priorities to different
groups. What do
>>> you
>>>>>>> say?
>>>>>>>>>>>>>>> Thank you,
>>>>>>>>>>>>>>> Nadya Morozova
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>> -----Original Message-----
>>>>>>>>>>>>>>>> From: Andrey Yakushev
>>>>> [mailto:andrey.yakushev@gmail.com]
>>>>>>>>>>>>>>>> Sent: Monday, November 20,
2006 3:47 PM
>>>>>>>>>>>>>>>> To: harmony-dev@incubator.apache.org
>>>>>>>>>>>>>>>> Subject: Re: [doc] What should
be improved in DRLVM
>>>>>>> Doxygen
>>>>>>>>>>>>>>> documentation?
>>>>>>>>>>>>>>>> In order to understand the
mapping between h-files
>>> and
>>>>>>>> structure
>>>>>>>>>>>>>>>> described in the Developers
guide I have tried to
>>>>> prepare
>>>>>>> some
>>>>>>>>>>>>> initial
>>>>>>>>>>>>>>>> classification. I put draft
at
> http://wiki.apache.org/harmony/DRLVM_Documentation_Interfaces_Classifi
>>>>>>> c
>>>>>>>>>>>>>>> atio
>>>>>>>>>>>>>>>> n.
>>>>>>>>>>>>>>>> Probably such tables could
be added to Doxygen doc;
>>> of
>>>>>>> course
>>>>>>>>>>> after
>>>>>>>>>>>>>>>> verification and rewriting
it in more user friendly
>>>>>>> manner.
>>>>>>>>>>>>>>>> Is this helpful?
>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>> Thanks,
>>>>>>>>>>>>>>>> Andrey
>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>> On 11/7/06, Mikhail Fursov
<mike.fursov@gmail.com>
>>>>> wrote:
>>>>>>>>>>>>>>>>> On 07 Nov 2006 21:17:45
+0600, Egor Pasko
>>>>>>>>>>> <egor.pasko@gmail.com>
>>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>>>>>> Do we feel that it
is time to set
>>> responsibilities
>>>>> on
>>>>>>>>>>>>> documenting
>>>>>>>>>>>>>>>>>> vm/include/* ?
>>>>>>>>>>>>>>>>> +1 To start working on
intercomponent interfaces.
>>>>> Going
>>>>>>> to
>>>>>>>>>>> commit
>>>>>>>>>>>>> a
>>>>>>>>>>>>>>>> couple
>>>>>>>>>>>>>>>>> of EM interface files
with documentation tomorrow.
>>> I
>>>>> do
>>>>>>> not
>>>>>>>>>>>>> believe
>>>>>>>>>>>>>>> that
>>>>>>>>>>>>>>>>> someday we will have
all component's local code
>>>>>>> documented
>>>>>>>> (-1
>>>>>>>>>>> to
>>>>>>>>>>>>>>> make
>>>>>>>>>>>>>>>> such
>>>>>>>>>>>>>>>>> policy for patches),
but intercomponent
>>> documentation
>>>>> is
>>>>>>>>>>> something
>>>>>>>>>>>>> we
>>>>>>>>>>>>>>>> must
>>>>>>>>>>>>>>>>> have (actually we must
not only document but clean
>>>>> the
>>>>>>> code
>>>>>>>>>>> too)
>>>>>>>>>>>>>>>>> --
>>>>>>>>>>>>>>>>> Mikhail Fursov
>>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>> --
>>>>>>>>>>>>>> Egor Pasko
>>>>>>>>> --
>>>>>>>>> Thank you,
>>>>>>>>> Alexei
>>>>>>>>>
>>>>>>>> --
>>>>>>>> Egor Pasko
>>>>>> --
>>>>>> Egor Pasko
>>>> --
>>>> Egor Pasko

Mime
View raw message