Alexei, I think we're talking about different things here :) I fully support your idea and I know about the Doxygen config options you have mentioned. I was just curious to know: is there interest to produce/evaluate produce Doxygen-style comments. My case was that, say, a function can have a line of text, we consider it documented, etc. however, the function comment is only a draft that does not produce meaningful documentation. A sign of better comment is @param and/or @return tag included in the function comment. Never mind, I think this type of info is not necessary at this stage:)
Thank you, Nadya Morozova -----Original Message----- From: Fedotov, Alexei A [mailto:[EMAIL PROTECTED] Sent: Friday, November 03, 2006 7:36 PM To: [email protected] Subject: RE: Re: [doc] What should be improved in DRLVM Doxygen documentation? 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(TraceLoca l trace, ObjectReference object) are not documented: parameter trace 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
