Mailing-List: contact dev-help@harmony.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@harmony.apache.org
Received-SPF: pass (herse.apache.org: local policy)
Content-class: urn:content-classes:message
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Subject: RE: [doc] What should be improved in DRLVM Doxygen documentation?
Date: Thu, 30 Nov 2006 09:51:27 +0300
Message-ID: 
 <523F3D8D8C97554AA47E53DF1A05466A6D9285@nnsmsx411.ccr.corp.intel.com>
Thread-Topic: [doc] What should be improved in DRLVM Doxygen documentation?
Thread-Index: AccT3kUvaqKkDcbUQ9qKNZg0PK92rQAbNluQ
From: "Morozova, Nadezhda" <nadezhda.morozova@intel.com>
To: <dev@harmony.apache.org>,
	<geir@pobox.com>

>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?=20

Suggested compromise:=20
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=20

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.=20

Cheers,=20
Nadya
=20

>-----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 (=3Das 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