harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Fedotov, Alexei A" <alexei.a.fedo...@intel.com>
Subject RE: [doc] What should be improved in DRLVM Doxygen documentation?
Date Fri, 03 Nov 2006 22:01:18 GMT
Nadya,

I missed this letter, sorry.

I believe a majority of users leave a web site after first two clicks.
That is why the Wiki page says that we have to fix these mostly used
pages first. Ok, it was I who wrote that text.

I believe it is yet possible to link this task to the source files. Let
me give an example. If we want to improve files.html, one should create
a list of header files which do not have the following comment. 
/**
 * @file
 * [@brief] Brief description goes here.
 */

The following command does a good part of the job:
$ grep -rL --include '*.h' '@file' drlvm/trunk

I believe it worth to start from the first pages any user visits, and
then extend the documentation quality further.

After my recent prompt reply to the letter from May 13, 2005 I believe I
shouldn't look as if I'm trying to attract your attention to a name in
your letter. BTW, May 13, 2005 was a Friday.

With best regards,
Alexei Fedotov,
Intel Java & XML Engineering

>-----Original Message-----
>From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
>Sent: Friday, November 03, 2006 7:14 PM
>To: harmony-dev@incubator.apache.org
>Subject: RE: [doc] What should be improved in DRLVM Doxygen
documentation?
>
>Alexei,
>Thanks for your answers. A couple of comments below, and a generic
>concern:
>I still cannot understand why we should evaluate pages, not code
>comments in source files.
>
>Example: the Wiki page now suggests that we improve the auto-generated
>pages: modules.html (list of groups), annotated.html (list of classes),
>files.html (list of files), etc.
>Now, these do not map to any specific header(s) - they are
>auto-generated by analyzing all headers. For instance, modules.html is
>about modules; any module maps to a @devgroup tag in code, and you can
>use "@devgroup optional" to separate all optional functions in your
>interface. Now, these modules are optional; creating them is not always
>needed/good/easy. How exactly can you improve the page that is an
>assembly of all modules? I'd say, we can have a recommendation for the
>community to group any related functionality - but we cannot improve
the
>page or oblige authors to use groups :)
>The same is for files, structures, etc. You can ask the whole authoring
>lot to write definitions of headers using @file; @struct, etc in their
>files. However, I don't see a way for 1-2 people volunteering and doing
>an improvement to the files.html page, etc.
>
>I guess a more realistic approach would be to measure amount of
>documentation in headers. This way, we can have people volunteer to fix
>things - like David L. did for bytecode.h! see - my way is working
>already :0
>
>Thank you,
>Nadya Morozova
>
>
>-----Original Message-----
>From: Alexei Fedotov [mailto:alexei.fedotov@gmail.com]
>Sent: Friday, November 03, 2006 1:56 AM
>To: harmony-dev@incubator.apache.org
>Subject: Re: [doc] What should be improved in DRLVM Doxygen
>documentation?
>
>Nadya,
>
>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.
>[NM] yeah, good idea!
>
>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?
>[NM] I always say - the more docs the better. If you still feel you can
>write a description of component manager, do so. My idea is that the
>higher-level conceptual info does not have to be part of Doxygen. You
>can write it on the website - with more HTML and XML presentation
>opportunities. Doxygen is so tightly bound with code that you don't
>really have to fit generics into it. You can place links back and fro
>but write the stabler stuff on the website. Surely, @page, @section,
>@devgroup, and @file tags are needed sometimes to tie definitions of
>methods and classes into interfaces and components. Please don't think
>that I am totally against them. I just think we can differentiate :)
>
>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.
>[NM] I doubt that a really well-documented source can produce a poor
>html :)
>
>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.
>[NM] :(
>
>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.
>[NM] yeah, I read the news :)
>
>Thank you for nice catches,
>Alexei
>
>
>
>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
>>

Mime
View raw message