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: Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Fri, 03 Nov 2006 16:49:39 GMT
>Never mind, I think this type of info is not necessary at this stage:)
+1



>-----Original Message-----
>From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
>Sent: Friday, November 03, 2006 7:42 PM
>To: harmony-dev@incubator.apache.org
>Subject: RE: Re: [doc] What should be improved in DRLVM Doxygen
>documentation?
>
>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(TraceLoc
a
>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