3

When building an API for a customer, the public javadoc has to contain just what you want to show the customer. Which is a shame, as it the javadoc is also, in some ways, the obvious target for some kinds of internal design documentation. One might imagine a custom doclet or some other trickery to allow the two types of information to coexist in the source. Anybody been there?

2

You could document internals in javadoc comments for private and package private attributes and methods. This allows you to generate 2 versions of javadoc, one for the public interface and one including all information.

Edit:

Without some kind of preprocessing your options are limited. If you need to add internal class level information you either have to add an unused private member to hang the apidoc comment onto, like:

/**
 * Internal secrets.
 */
private Object documentation;

Or if you would allow some preprocessing via an ant build script, you can do something like:

/**
 * Public class documentation.
 *//*INTERNAL:
 * internal additional documentation.
 */
public MyClass {

and use a replace action from ant:

<replace dir="${source.dir}" includes="**/*.java" summary="yes">
    <replacefilter  token="*//*INTERNAL:" value="*" />
</replace>
  • And just forgo class-level internal remarks? OK, sure. – bmargulies Mar 2 '11 at 15:50
  • Anything to say on the class-level could be annotated on an empty (and unused) private static nested class. – Macneil Mar 2 '11 at 16:17
  • @bmargulies, see update – rsp Mar 2 '11 at 16:17

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.