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: Fri, 24 Nov 2006 18:57:34 +0300
Message-ID: 
 <523F3D8D8C97554AA47E53DF1A05466A69AAA1@nnsmsx411.ccr.corp.intel.com>
Thread-Topic: Re: [doc] What should be improved in DRLVM Doxygen
 documentation?
Thread-Index: AccPaI853tFS00bXQbik9nBvtQudqgAdiB/g
From: "Morozova, Nadezhda" <nadezhda.morozova@intel.com>
To: <dev@harmony.apache.org>

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

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,=20
Nadya
=20

>-----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_Classific
>> >> 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
>>