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.
source share