harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Egor Pasko <egor.pa...@gmail.com>
Subject Re: [doc] No Doxygen reference for code :(
Date Wed, 29 Nov 2006 09:29:51 GMT
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