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 Fri, 24 Nov 2006 16:16:23 GMT
+1


Tim Ellison wrote:
> It would be good to see the classlib Doxygen re-appear too (for portlib
> etc).  I was looking for it recently and it has been removed from the
> classlib page.
> 
> Regards,
> Tim
> 
> Morozova, Nadezhda 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_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