harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Morozova, Nadezhda" <nadezhda.moroz...@intel.com>
Subject RE: [doc] What should be improved in DRLVM Doxygen documentation?
Date Thu, 02 Nov 2006 21:39:39 GMT
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: 


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