Mailing-List: contact dev-help@harmony.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@harmony.apache.org
Received-SPF: pass (herse.apache.org: domain of gcjhd-harmony-dev@m.gmane.org
 designates 80.91.229.2 as permitted sender)
To: dev@harmony.apache.org
From: Egor Pasko <egor.pasko@gmail.com>
Subject: Re: [doc] No Doxygen reference for code :(
Date: 29 Nov 2006 15:29:51 +0600
Lines: 61
Message-ID: <uirgylhww.fsf@gmail.com>
References: 
 <523F3D8D8C97554AA47E53DF1A05466A587B5B@nnsmsx411.ccr.corp.intel.com>
 <ekhv3h$145$1@sea.gmane.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3
Sender: news <news@sea.gmane.org>

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