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, 16 Nov 2006 17:54:08 GMT
He-he.
There's truth in what you say. But I ran the same metric with
EXTRACT_ALL option enabled, and class.h had ~10 warnings instead of 126
:) that's why I think the warning about undocumented members that
directly relies on EXTRALL_ALL setting should be considered with care.

Thank you, 
Nadya Morozova
 

>-----Original Message-----
>From: Alexei Fedotov [mailto:alexei.fedotov@gmail.com]
>Sent: Thursday, November 16, 2006 8:48 PM
>To: harmony-dev@incubator.apache.org
>Subject: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
>
>Andrey,
>
>I'm trying to understand your metric and have got a question about
>your it. Conssider the following file:
>drlvm/trunk/vm/vmcore/include/Class.h. It has metric of 126. Does it
>mean that this file has worse documentation than one of the folloiwng
>files?
>
>vm/gc_cc/src/timer.h (1) or vm/gc_cc/src/slot.h (1)
>
>> Seems like this metric likes big narrative text.
>So do I :-)
>
>Thanks!
>
>
>On 11/16/06, Morozova, Nadezhda <nadezhda.morozova@intel.com> wrote:
>> Andrey,
>> I personally like the metric. It does not always reflect the
>> proportional amount of documentation, but the files at the top of the
>> list (the worst files) indeed require attention :)
>> I guess the metric shows both undocumented files and those that are
>> pretty verbose but require more attention.
>>
>> Suggestion: in addition to the big metric, have a more refined
listing -
>> which ignores some warnings of minor importance. For example, a
metric
>> that only reports undocumented members. What do you say?
>>
>>
>> Thank you,
>> Nadya Morozova
>>
>> >-----Original Message-----
>> >From: Andrey Yakushev [mailto:andrey.yakushev@gmail.com]
>> >Sent: Thursday, November 16, 2006 7:46 PM
>> >To: harmony-dev@incubator.apache.org
>> >Subject: Re: [doc] What should be improved in DRLVM Doxygen
>> documentation?
>> >
>> >Alexei's metric is interesting, but sometimes shows strange results
>> >for pretty good docs, like for quite commented files:
>> >
>> >0 verifier_8h.html
>> >0 structVerifier_1_1vf__Graph.html
>> >
>> >Seems like this metric likes big narrative text.
>> >
>> >
>> >I also agree that comments quality could be estimated through
Doxygen
>> >warnings. I attempted to use such a metric for DRLVM.
>> >
>> >I used generated DoxygenDrlvmLog.txt file and parser string:
>> >
>> >---8<------------------------------------------------------
>> >cat DoxygenDrlvmLog.txt | grep Warning | awk -F ":" '{print $1}' >
>> >~/tmp/r ; for f in `cat ~/tmp/r | sort | uniq` ; do ( echo `cat
>> >~/tmp/r | grep $f | wc -l` " " $f ) ; done | sort -n -r
>> >---8<------------------------------------------------------
>> >
>> >The result is placed at
>>
>http://wiki.apache.org/harmony/DRLVM_Documentation_Quality_Doxygen_Warn
>> ing_
>> >Rating
>> >
>> >If it suits our needs we can think about regular testing.
>> >
>> >Thanks,
>> >Andrey
>> >
>> >
>> >On 07 Nov 2006 14:23:20 +0600, Egor Pasko <egor.pasko@gmail.com>
wrote:
>> >> On the 0x216 day of Apache Harmony Alexei A. Fedotov wrote:
>> >> > 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
>> >>
>> >> does it make sense to convert warnings to quality metrics and put
on
>> >> harmonytest.org (or even Wiki) regularly? It should encourage
people
>> >> (like me) to document sources better. Or it is too much effort?
>> >>
>> >> > 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
>> >> >
>> >>
>> >> --
>> >> Egor Pasko
>> >>
>> >>
>>
>
>
>--
>Thank you,
>Alexei

Mime
View raw message