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:[EMAIL PROTECTED] >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 <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> 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:[EMAIL PROTECTED] >> > >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 <[EMAIL PROTECTED]> >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:[EMAIL PROTECTED] >> > >> > >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:[EMAIL PROTECTED] 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 >>
