harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Morozova, Nadezhda" <nadezhda.moroz...@intel.com>
Subject Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Fri, 24 Nov 2006 15:57:34 GMT
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_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
>>

Mime
View raw message