How can I provide documentation in Java code?

What options are there to enforce this document? I want something that will be executed as part of the build process, for example. a maven target that will verify that the code is documented (class level and method level), and report if any code is missing from the documentation.

We looked at FindBugs, PMD, and CheckStyle, but they don't seem to offer this feature.

+4
source share
4 answers

Well, I don’t want to tell you this, but useful documentation cannot be used with tools.

Checkstyle can check if Javadoc is present , but it cannot verify that Javadoc contains something other than @param pMyParam the myParam and other meaningless junk. Even if you allow some tool to check the contents of documents, this will create a lot of false positives and lead to the fact that simple but useful comments will be inflated only for the convenience of checking. After some time, developers will learn how to filter Javadocs when reading code, how we filter ads when reading a web page. Thus, all tools will not gain anything if the developers do not want to write good and useful documents.

To say this in the words of Antoine de Saint-Exupery: if you want to build a ship, do not bring people together to collect wood and not assign tasks to them and work, but rather teach them a long time for the endless vastness of the sea.

My recommendation: use checkstyle to check the very basics, for example, the fact that each class has at least a type comment, and this interface also documents their methods. Then, educate the developers, when necessary, about what makes a meaningful and useful documentation, and make it clear that in the eyes of the development guide, good quality code has good quality documents. Javadocs can be very good, even if certain methods are not documented at all. Then, verification can only be performed by manual verification, for example. expert assessments or some formalized step in the quality control process.

Only my two cents.

+2
source

This may not be exactly what you are looking for, but you can use Sonar and name it when compiling the code. Sonar will provide a lot of information, including checkstyle

Sonar is very easy to use and integrates with the maven project.

Doc: http://docs.sonarqube.org/display/SONAR/Installing+and+Configuring+Maven

+1
source

Teamscale can check for any comments. It can also evaluate the quality of comments and identify trivial as well as unrelated comments.

Disclaimer: I'm a Teamscale developer.

+1
source

Some time ago this doclet from Sun appeared called DocCheck. Generates a report from javadoc. I don’t know if it is still available.

Do a search on Google.

Ok, google search ... works with versions 1.2, 1.3 and 1.4. Its experimental and seems to be inactive. Is it worth it to use now? I dont know. This is something for you to decide.

javadoc doccheck download http://192.9.162.55/j2se/javadoc/doccheck/index.html

0
source

All Articles