Generate Javadoc HTML only for public members

By Adrian Smith2 Jul 2007300 words2 mins to read

In Java there are the classic four protection levels which members (fields and methods) can have: private, protected, package-level and public. Any member can have Javadoc (including private members). But when one generates the Javadoc, which protected levels should be included?

Generated Javadoc is used by humans. These humans are probably not you. And thus are probably clients of your classes, either within or outside of your organization. It's possible, although unlikely, that they may be able to access package-level members. It's possible they may need to subclass your class, although in (nearly) all cases I can conceive of, they won't do that without looking at your source code.

Javadoc should be simple to understand. There's simply a lot of potentially documentable stuff going on in a class, which is capable of reducing simplicity. Setters which only Hibernate needs to see (private), or which only your factories in your package need to see (package-level).

Javadoc should therefore only be generated only for public attributes. That's what Sun's JDK docs do as well (for example you don't see any protected or private stuff here). And there's an additional benefit of simplicity is that if this is the only level for which the Javadoc is being generated, it doesn't even state the protection level in the summary, so you see int getX() in the method list as opposed to public int getX().

This can be achieved with the -public option to the Javadoc generation program. In Netbeans 5.5, right-click on the project in the "projects" tab, select the menu item "properties", go to the "documentation" entry under the "build" entry, and enter -public in the "additional javadoc options" field.

This article was written by Adrian Smith on 2 Jul 2007

Follow me: Facebook | Twitter | LinkedIn | Email

More on: Java | Coding