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 <[EMAIL PROTECTED]> 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:[EMAIL PROTECTED] >Sent: Thursday, November 16, 2006 8:48 PM >To: [email protected] >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 <[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: [email protected] >> >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 <[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/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:[EMAIL PROTECTED] >> >> > >Sent: Friday, November 03, 2006 6:26 PM >> >> > >To: [email protected] >> >> > >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: [email protected] >> >> > >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
