Javadocing Nested Classes
Javadoc seems to include static nested classes in the package-level Javadocs but not inner classes (classes which can't stand alone and require an instance of their enclosing class). Keep this in mind if you must expose a class but you also want to semi-hide it within another class's documentation so as not to clutter up the package-level documentation.
I recently used this trick for a mini-DSL. I have various inner classes which I return depending on the context; doing so ensures we only expose relevent commands to the client. Making these classes inner instead of static nested prevents them from distracting from the single entry point class in the package level Javadocs.
2 Comments:
Why don't you just make these inner classes private or package protected? Non-static inner class carry on the link to its outer class, so it is not nice.
Notice I said, "if you must expose a class." These classes are part of the public API. Like I said, they make up my domain-specific language. They also need to reference their enclosing class, so inner is appropriate. I was initially worried about the classes cluttering up the package-level Javadocs but was pleased when Javadoc did what I want by default.
Post a Comment
<< Home