harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrey Yakushev" <andrey.yakus...@gmail.com>
Subject Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Fri, 17 Nov 2006 10:28:02 GMT
Alexei already mentioned this peculiarities:

# 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.

Thanks,
Andrey

On 11/16/06, Morozova, Nadezhda <nadezhda.morozova@intel.com> wrote:
> 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