Andrey, Tim, Thanks for sharing your point.
I hope, even source readers also will be happy with improved comments.
I see here a different trend for the discussion. To my understanding improving quality of comments in source files is a different task from completing API reference: 1. Good API comments answer the question "How can I use it?" Answering the question "How it works" is excessive for API comments. For example, API reference for long integer arithmetic is much easier to read without referencing performance optimizations. Such type of documentation targets code customers, who don't read source code, and even a getter should be described for them. 2. The comments which describe algorithms and optimizations are a must for understanding a source code if you want, for example, to perform bug fixes. Such type of documentation targets code owners, who are reading the code. Such comments should be aphoristic and complement the code, not rephrase it. 3. If we take C/C++, interfaces are documented in header files, and algorithms are documented in source files. This is accepted practice in Java design to hide a private implementation behind a public interface. Two types of documentation reside in different files. Doxygen is suited for generating API reference. Doxygen warnings won't help us with *.c and *.cpp files because we don't feed these files to the tool. I found a way to measure quality of in-source comments using CCCC tool http://cccc.sourceforge.net. You can check results for DRLVM at http://issues.apache.org/jira/secure/attachment/12345645/cccc.zip (please, start from .cccc/cccc.html). When a code with high complexity (= has high MVG) is poorly commented (= has low COM) the ratio MVG/COM (M_C column) becomes big and is highlighted with red. Stefano, Please, don't miss another colored table. :-) Do you know better tools to estimate a source metrics to add to Melody? With best regards, Alexei Fedotov On 11/24/06, Tim Ellison <[EMAIL PROTECTED]> wrote:
Andrey Yakushev wrote: > I'd like common Doxygen documentation bundle for all Harmony or at > least for all classlib and all DRLVM code. It suites for #1 and #3 use > cases, and I hope, even source readers also will be happy with > improved comments. Agreed. Of course, we will never prevent people reading the source code! But if reading an API description it is often easier to read the javadoc / Doxygen document. Regards, Tim -- Tim Ellison ([EMAIL PROTECTED]) IBM Java technology centre, UK.
