Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

1 Answer 1

up vote 2 down vote accepted

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>
share|improve this answer
    
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

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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