Mailing-List: contact harmony-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: harmony-dev@incubator.apache.org
Received-SPF: pass (herse.apache.org: local policy)
Content-class: urn:content-classes:message
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Subject: RE:  Re: [doc] What should be improved in DRLVM Doxygen
 documentation?
Date: Tue, 7 Nov 2006 15:42:36 +0300
Message-ID: 
 <523F3D8D8C97554AA47E53DF1A05466A5D2E5C@nnsmsx411.ccr.corp.intel.com>
Thread-Topic: Re: [doc] What should be improved in DRLVM Doxygen
 documentation?
Thread-Index: AccCRfeeTOrWiDUOR8qwojfQSORhoAAIN1GA
From: "Morozova, Nadezhda" <nadezhda.morozova@intel.com>
To: <harmony-dev@incubator.apache.org>

+1

Thank you,=20
Nadya Morozova
=20

-----Original Message-----
From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
Sent: Tuesday, November 07, 2006 11:23 AM
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 A. Fedotov wrote:
> Nadya wrote,
> > we could check for required Doxygen tags in certain elements.
>=20
> 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.
>=20
> # 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   =3D YES
>=20
> The resulting log consists of warning messages about different
problems.
> My DoxygenDrlvmLog.txt, for example, contains the following one:
>=20
>
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

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
>=20
> >-----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
>=20

--=20
Egor Pasko