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
