>Never mind, I think this type of info is not necessary at this stage:) +1
>-----Original Message----- >From: Morozova, Nadezhda [mailto:[EMAIL PROTECTED] >Sent: Friday, November 03, 2006 7:42 PM >To: harmony-dev@incubator.apache.org >Subject: RE: Re: [doc] What should be improved in DRLVM Doxygen >documentation? > >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: harmony-dev@incubator.apache.org >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(TraceLoc a >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: 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
