0

There are two types of documentation.

One type, the Implementation Documentation, contains information about specific implementation of a construct (eg. Class, Method, etc.). It is targeted to the future me, maintainer, debugger and so on.

And there is Usage Documentation, containing information how to use a provided api. It does not contain information about specific implementation and is targeted to users of the api.

How do I include both of them in one file? (Or do I include both of them in one file? And if not, what type belongs into the source file?)

Are there special techniques, using java-doc and/or best practices?

1

Both can be tied to the source files.

Implementation Documentation is tied to the code, reflecting development decisions, and goes inside the source file along with code it is related to.

Usage Documentation in Java can be provided in javadoc format, from which the API documentation (e.g. HTML files) can be extracted. It is ideally neutral with regards to implementation but is still tied to the code so it can be looked into while using the API classes when developing using an IDE and you pass the mouse over the class/method.

/** <b>Usage Documentation</b> in javadoc format providing class description and usage. */
public class PublicClass {

    /** <b>Usage Documentation</b> in javadoc format providing method description and usage.
      * @param aParameter parameter description.
      * @return either the operation succeeded or not.
      * @throws SomeException if an exception occurred.
      */
    public boolean publicMethodThatBelongsToTheAPI(int aParameter) throws SomeException {

        /* Implementation Documentation (non-javadoc) */
        doSomething();

        (...)
    }

    private void doSomething() {
        // More implementation documentation
        (...)
    }
}
  • So you are saying, that I should not use javadoc for Implementation Documentation? – Angelo.Hannes Oct 11 '13 at 14:16
  • 1
    You can, but it is not mandatory. The JDK source often doesn't use it. – Piovezan Oct 11 '13 at 14:25

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.