harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Ellison <t.p.elli...@gmail.com>
Subject Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Fri, 24 Nov 2006 16:14:28 GMT
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
> 

-- 

Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.

Mime
View raw message