Question

I have what must surely be a fairly common documentation need…

I’m implementing a rather sizable Java library code base that has, among other things, various classes intended to be exposed to a caller/implementor at the appropriate level of abstraction. At the same time, the code base contains, of course, various internal classes, interfaces, and other abstractions that the user of the library doesn’t need to know about in order to use the API.

Lots of other API libraries out there make the mistake of simply throwing everything into the Javadocs, and leaving it up to the user to figure out which objects and entities they actually need to deal with as a caller through some combination of guesswork, inference, and, if you’re lucky, example code.

I don’t want to be in that same position. I would like to have an “internal” set of Javadocs that expose the entire extent of the codebase, and an “external” set of Javadocs intended to clearly communicate to the developers the characteristics of the classes that they actually need to use to get their work done. I don’t need or want to muddy the waters with various internal abstractions that they don’t need to see or know about – there’s no need for them to know how it all works under the hood, and it would just confuse and misdirect them, making for a very inefficient API learning process.

How can I accomplish this? Is there a well-known combination of arguments to ‘javadoc’ and perhaps some annotations that can make this happen?

Thanks very much for your consideration!

Answer 1

Assuming that you have followed best-practice and put your internal classes in different packages to your public APIs, you can run javadoc with the public API package names as command line arguments.

Refer to the javadoc command line synopsis for more details.

(If you haven’t organized your packages to keep internal classes out of API packages, you may be in for a bit of pain …)