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 Fri, 17 Nov 2006 10:29:08 GMT
Do you think we can add RED ALERT to the files that have only one
warning - not documented? I'd say such files should be addressed in the
first place


>-----Original Message-----
>From: Andrey Yakushev [mailto:andrey.yakushev@gmail.com]
>Sent: Friday, November 17, 2006 1:23 PM
>To: harmony-dev@incubator.apache.org
>Subject: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
>
>Alexei,
>
>Metric is simply the number of Doxygen warnings for file. Sorry for
>not mentioning this in my letter.
>If some file doesn't have Doxygen comments at all then metric can show
>only one problem, like in your examples:
>
>vm/gc_cc/src/timer.h:27: Warning: Compound Timer is not documented.
>vm/include/slot.h:48: Warning: Compound Slot is not documented.
>
>All warning need attention I think. If doc is generated without
>warning, then file is not presented in this list. So this metric
>separates bad documented files. Yours estimates quality of good
>documented files.
>
>I consider this as some king of QA for documentation. The more tests -
>the better. :)
>
>Thanks
>Andrey
>
>On 11/16/06, Alexei Fedotov <alexei.fedotov@gmail.com> wrote:
>> 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_War
n
>> > 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/mmt
k
>> > /
>> > >> > Scanning.java:47: Warning: The following parameters of
>> > >> >
>> >
>>org::apache::HarmonyDRLVM::mm::mmtk::Scanning::precopyChildren(TraceLo
c
>> > 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