harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Alexei Fedotov" <alexei.fedo...@gmail.com>
Subject Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Thu, 02 Nov 2006 22:55:46 GMT

You asked good questions. Here are few answers:

1. Grouping of results is implied by documentation grouping. Scripts
can process any documentation bundle, so if one creates a smaller or
specific bundle, the list will be shorter, or more specific.Creating
several documentation bundles in different directories makes their
comparison an easy task - I can do this comparison.

2. Personally I like @page tags and package.html files. I appreciate
Salikh's efforts of creating wonderful technical descriptions - I
referred to them as masterpieces. I also remember that you asked me to
create a narrative section for a component manager few months ago. All
Doxygen documentation will be on the web site. Why these narrative
sections shouldn't be evaluated?

3. I don't think the rating of pages such as a list of functions
should be neglected. Any .html page which can be viewed by a user
should be readable. That is a reason why I parse .html files in the
script, not sources.

4. I believe establishing connection between .html files and source
files can be automated. I don't know how to write a short script for
that, because sometimes .html page depends from several source files,
and vice versa.

5. You can imagine the following pie chart from the data: 2680 pages
of 2922 (91%) are not good and should be revised.

6.  Today the community discussed removing GC V4. This would
immediately decrease GC documentation size. It would also decrease a
number of well documented pages on garbage collection, since new GCs
don't have as much comments in their code as old GC V4.

Thank you for nice catches,

On 11/2/06, Morozova, Nadezhda <nadezhda.morozova@intel.com> wrote:
> Wow! Alexei, great start!
> ... and so many pages marked with 0 rank. I really appreciate your
> effort - it sets me back on earth and to work. I hope this rating would
> also make owners of code more ambitious, and would inspire them to write
> more/better comments to get a better rating :)
> Question on output measurement: can we rate source files or code
> elements (structure, functions, etc) instead of html files?
> My concerns:
> - Many html files are autogenerated, their rating is N/A. examples:
> todo.html, functions_vars_0x68.html (listing of links to functions in
> alphabetical order - there are many pages like that)
> - Some results are duplicated, because each struct/function has an
> individual rating + rating of the file/group reference it belongs to.
> - Some files have a high rating (see the top candidate, for example),
> but it's generated from comments marked with @page. These don't belong
> to specific code, but create a narrative section. Evaluating these is
> complex, and perhaps, should not be done. My personal preference would
> be to move such generic explanations to component docs on the website
> and reserve Doxygen docs to API reference as much as possible (this is a
> subject for further discussion).
> - the listing of files is SO LONG... grouping them by
> file/component/type or otherwise organizing the output would make the
> whole rating more readable. I mean, from the current version, I can only
> make out the leaders (not files even, individual bits of them), and
> understand that the majority have 0 rating. This has its instructional
> impact, but I cannot see the areas where we are the best - bearable -
> worst, or see the approx distribution of powers... missing that info
> leaves me without direction on what to do.
> Question on data presentation: do you think we can have some post
> processing of the raw data that your script produces - to see the big
> picture? We have some metrics: graphics, pie charts, anything. This
> would instantly show the most important conclusions. I could do such
> metrics and post them regularly on Wiki. If anybody says they need such
> kind of info, I'd volunteer to help.
> Thank you,
> Nadya Morozova
> -----Original Message-----
> From: Fedotov, Alexei A [mailto:alexei.a.fedotov@intel.com]
> Sent: Thursday, November 02, 2006 11:33 PM
> To: harmony-dev@incubator.apache.org
> Subject: [doc] What should be improved in DRLVM Doxygen documentation?
> Nadya, All,
> I have ranked the quality of Doxygen-generated DRLVM documentation and
> posted it to the following Wiki page:
>    http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
> All are welcome to check masterpieces of our documentation. All
> volunteers are welcome to improve page ranks by editing comments in
> DRLVM sources.
> With best regards,
> Alexei Fedotov,
> Intel Java & XML Engineering

View raw message