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: Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Fri, 03 Nov 2006 16:41:36 GMT
Alexei,
I think we're talking about different things here :) I fully support
your idea and I know about the Doxygen config options you have
mentioned. 
I was just curious to know: is there interest to produce/evaluate
produce Doxygen-style comments. 
My case was that, say, a function can have a line of text, we consider
it documented, etc. however, the function comment is only a draft that
does not produce meaningful documentation. A sign of better comment is
@param and/or @return tag included in the function comment. 
Never mind, I think this type of info is not necessary at this stage:)

Thank you, 
Nadya Morozova
 

-----Original Message-----
From: Fedotov, Alexei A [mailto:alexei.a.fedotov@intel.com] 
Sent: Friday, November 03, 2006 7:36 PM
To: harmony-dev@incubator.apache.org
Subject: RE: Re: [doc] What should be improved in DRLVM Doxygen
documentation?

Nadya wrote,
> we could check for required Doxygen tags in certain elements.

I wasn't asked, but cannot resist, sorry. You may achieve this right now
without additional coding. Doxygen warns about many problems you
describe, when you have the following option set.

# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate
warnings
# for undocumented members. If EXTRACT_ALL is set to YES then this flag
will
# automatically be disabled.
WARN_IF_UNDOCUMENTED   = YES

The resulting log consists of warning messages about different problems.
My DoxygenDrlvmLog.txt, for example, contains the following one:

drlvm/trunk/vm/MMTk/ext/vm/HarmonyDRLVM/org/apache/HarmonyDRLVM/mm/mmtk/
Scanning.java:47: Warning: The following parameters of
org::apache::HarmonyDRLVM::mm::mmtk::Scanning::precopyChildren(TraceLoca
l trace, ObjectReference object) are not documented:
  parameter trace

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

>-----Original Message-----
>From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
>Sent: Friday, November 03, 2006 6:26 PM
>To: harmony-dev@incubator.apache.org
>Subject: RE: Re: [doc] What should be improved in DRLVM Doxygen
>documentation?
>
>Egor,
>I agree with you on the idea of simplicity: documented vs.
>non-documented.
>An additional point: do you think we need/want to evaluate quality of
>comments? we could check for required Doxygen tags in certain elements.
>For example, a function is almost certain to include @param and
@return.
>Surely, this is heuristics and does not solve all our problems. But the
>Doxygen quality check sometimes shows that the file does have comments,
>but they are not processed properly by Doxygen - which results in a low
>rating for an html file. Maybe this is a crazy idea - I'd be glad to
>know your opinion.
>
>Thank you,
>Nadya Morozova
>
>
>-----Original Message-----
>From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
>Sent: Friday, November 03, 2006 12:18 PM
>To: harmony-dev@incubator.apache.org
>Subject: Re: [doc] What should be improved in DRLVM Doxygen
>documentation?
>
>On the 0x216 day of Apache Harmony Alexei Fedotov wrote:
>> Egor,
>>
>> Thank you for your interest.
>
>We definitely need to improve our documentation. Necessity is not a
>real interest :)
>
>> Here is an algorithm:
>>
>> 1. Create a list of words from HTML files.
>> 2. Merge a dictionary of all words used in documentation.
>> 3. Remove a half of the most frequently used words from the
dictionary
>> - I believe they do not add much sense.
>> 4. Remove misspelled words (including identifiers) from the
>dictionary.
>> 5. Give a page +1 for each rare, correctly spelled word according to
>> the dictionary.
>> 6. Divide to the total number of words on the page.
>
>hm, strange heuristic. More unique correctly spelled words is
>beneficial. It does not give a clue on the overall quality of
>documentation, which is rather confusing..
>
>I thought of something more natural. Number of documented items
>vs. number of non-documented. Plus a penalty to the relative number of
>misspelled words.
>
>> I've collected nice RFEs from your letter. Most of them make me think
>> and I like them.
>> a. Update an ASF block comment
>> b. Improve readability. Some things are really easy - like removing
>> awk and rewriting most things in perl. Others are a bit more complex
-
>> I targeted script performance when created auto-generated perl
script.
>> Also, initial algorithm was a bit more complex - different words had
a
>> different cost based on their popularity.
>> c. Use junit test output format to integrate with
>> http://harmonytest.org. I believe I need a feature request for that
>> site as well - we need some way to import performance-like rankings
to
>> the site.
>
>Yes, I thought of the RFE to harmonytest. At least, put the doc items
>on a separate page from the build items.
>
>> d. I will think of parsing sources. But I don't think we need to
>> maintain both scripts. The generic rule is simple - improve your .h
>> and .java files - .cpp files don't count. I suggest better to link
>> .html files to contributors.
>
>can you calculate a list of relevant filenames from a doc page? give
>filename +1 for each documented item, give a -1 for each undocumented,
>divide on the number of items. Is it easy to implement?  Maybe doxygen
>has some features to assist this?
>
>> Thank you for ideas. I will certainly update the script. I just want
>> to wait a bit - many scripts die just because people are not
>> interested to run them a second time. Also, if anyone suggest any
>> changes in algorithm or any other RFEs, I want to implement them all
>> at once.
>>
>> Nadya, could you please point us a good documentation file so we can
>> use it as a pattern?
>
>--
>Egor Pasko

Mime
View raw message