Selective API Javadocs

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 ...)

Answer 2

In addition to Stephen C's answer and using the javadoc tool, you can specify exactly which packages appear in the javadoc (hence Stephen C's comment about 'pain' if they aren't organised logically) using something like this:

Say you have 5 classes and you want only the classes in the org.notprivate package to appear in the Javadoc:

org.notprivate.Foo
org.notprivate.Bar
org.notprivate.Stuff
org.notpublic.Things
org.notpublic.More

You can use something like:

javadoc -d target/api -source 1.6 -sourcepath src/main/java org.notprivate

That's just a quick example, if you need to specify each class you'll need to look at the link Stephen C provided in more detail

Posted here for clarity: Javadoc Documentation

Answer 3

You can use some extra arguments when invoking the javadoc tool :

• -public : Shows only public classes and members.
• -protected : Shows only protected and public classes and members. This is the default.
• -package : Shows only package, protected, and public classes and members.
• -private : Shows all classes and members.

So, with these options you can generate a full documentation for internal usage, and give a 'light' documentation with only the public interface to your customers.

If you're using Eclipse, the Javadoc wizard shows radio buttons to help you choose the documentation level - which is "public fields only" by default.

Answer 4

I would like to have ... 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.

Given this desire, perhaps Javadoc isn't the best method of documenting the overall system view or for giving a "here's what you need to know"-type info to new developers?

I would recommend supplementing your Javadoc files with a separate guide/document/wiki/something to give the meta-view.