One more question: Many warnings are produced for 'undocumented members' which do not require documentation. What to do with these?
For example, you add a comment to a struct and insert a reference to spec. you do not want to document struct members - everything is in the spec, but Doxygen produces warnings. Another example would be enums. Often, a definition of the enum is enough because the names of enum's members are quite transparent. One suggestion would be to add the reference to spec to every member or add ///some-text-that-is-parsed-as-comment to elements that, in your opinion, are self-explanatory. Another way out is to ignore these errors or exclude specific elements/files from the metric. 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_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: 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 >> >>
