+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:[EMAIL PROTECTED] On Behalf Of Egor Pasko >Sent: Wednesday, November 29, 2006 12:30 PM >To: [email protected] >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
