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: Re: [doc] No Doxygen reference for code :(
Date Wed, 29 Nov 2006 10:04:45 GMT
+1 for 
>I think, *all code must be documented* more or less. Some more, some
less.
>
>Making all the project Doxygen docs visible from the website allows:
>* developers to walk through links, view class diagram charts and find
>  what they want (in latest snapshots)
>* beginner developers to see the best-documented top-level docs to
>  understand the basic architectural conscepts
>* all of us to review the documentation *easier*, suggest changes,
>  document more
>
>aren't my arguments convincing? :)

Cheers, 
Nadya
 
>-----Original Message-----
>From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
>Sent: Wednesday, November 29, 2006 12:30 PM
>To: dev@harmony.apache.org
>Subject: Re: [doc] No Doxygen reference for code :(
>
>On the 0x230 day of Apache Harmony Salikh Zakirov wrote:
>> Morozova, Nadezhda wrote:
>> > I've noticed that there's no API reference documentation for
Harmony
>> > code - generated by Doxygen/Javadoc.  I guess many will agree that
>> > having API reference is very useful and convenient.
>>
>> I've tried to build doxygen documentation for the Thread Manager
>> component of the DRLVM (i.e. drlvm/vm/thread/src/*.[ch] +
>> drlvm/vm/include/open/*thr*.h).
>>
>> I needed to have a Doxyfile and fix a couple of warnings along the
way,
>> please see the patch attached to HARMONY-2351.
>>
>> However, the generated documentation was of little use to me,
>> due to the generated documentation treating all structure members
>> as 'typedef's, while in fact they are just regular struct fields.
>>
>> > 1.	Ability to generate docs locally from source code as part of
>> > build - need to change existing build files or write new ones.
>>
>> After adding Doxyfile to drlvm/vm/thread/doc, one can do following:
>>
>>     $ cd drlvm/vm/thread/doc
>>     $ doxygen
>>
>> then browse drlvm/vm/thread/doc/html/index.html
>>
>> > 2.	Ability to see docs on the website - manually copy a local
>> > bundle of docs to the website and add a link. Geir has been
planning to
>> > include the website into the next snapshot; supplying ready
reference
>> > with it seem nice.
>>
>> Judging from the quality of docs generated from thread manager,
>> we should *not* publish it on a web-site.
>
>why? what can make us hide the most part?
>
>we have our sources, ok, not ideally documented, but we will see how
>to improve them if they are on the website.
>
>> The only documentation that may be worth linking is intercomponent
header
>files in:
>>
>>     drlvm/vm/include/open/
>
>Why should we carefully select "clean" parts and then "publish" them
>as if we were writing a book?
>
>I think, *all code must be documented* more or less. Some more, some
less.
>
>Making all the project Doxygen docs visible from the website allows:
>* developers to walk through links, view class diagram charts and find
>  what they want (in latest snapshots)
>* beginner developers to see the best-documented top-level docs to
>  understand the basic architectural conscepts
>* all of us to review the documentation *easier*, suggest changes,
>  document more
>
>aren't my arguments convincing? :)
>
>--
>Egor Pasko

Mime
View raw message