9

What would be a good alternative to inline Java documentation, i.e. can one have a separate docs file somehow mapped to a java source file?

I have never liked huge comment sections littered in code.

gnat
  • 21,442
  • 29
  • 112
  • 288
S.D.
  • 957
  • 6
  • 16
  • why would you need this? – gnat Oct 29 '12 at 13:05
  • @gnat just personal preference, for a hobby project. – S.D. Oct 29 '12 at 13:08
  • 3
    @downvotes looks like I've irritated the _religious_ coders :) – S.D. Oct 29 '12 at 13:12
  • "You should only ask practical, answerable questions based on actual problems that you face." ([faq]) – gnat Oct 29 '12 at 13:15
  • 3
    Kindly enlighten me about what in this question makes it impractical, unreal. I'll appreciate that too. – S.D. Oct 29 '12 at 13:23
  • 4
    it would be great if your question explained what kind of problems you're having with standard javadoc. As currently phrased, it's hard to tell whether there is a problem at all, making attempts to answer the question kind of a [guessing game](http://blog.stackoverflow.com/2012/02/lets-play-the-guessing-game/) – gnat Oct 29 '12 at 13:30
  • 3
    The real problem with documenting code in a different file is that it is less likely to get updated. When a function changes, sometimes the documentation is not always updated to exactly match it. If the documentation is moved to a different file, there is now one extra step to making the correct change. It also make it less obvious that the documentation is wrong. You will only see it when you look specifically at the documentation, not when you scroll passed it in the code. – unholysampler Oct 29 '12 at 13:38
  • @unholysampler Thanks. So, its generally not a good Idea. I'just have never (personally) liked huge comment sections littered in code , so was just looking for options. You might like to transfer your comment to an answer. – S.D. Oct 29 '12 at 13:54
  • @wingman: Still curious about your objection. Do you dislike comment sections in general, or the useless comments that litter so many projects. – kevin cline Oct 29 '12 at 15:40
  • @kevincline comments sections may indeed be overwhelming, even when filled with really useful details. See for example [java.util.concurrent.Executor source code](http://grepcode.com/file/repository.grepcode.com/java/root/jdk/openjdk/6-b14/java/util/concurrent/Executor.java) in openjdk 6-b14 – gnat Oct 29 '12 at 17:02
  • @kevincline Small sections are OK, but huge ones throw me off focus when I'm scrolling through the code. By huge ones I mean when I have to include a detailed paragraph, and a mini example. – S.D. Oct 30 '12 at 09:07
  • Possibly related: how to fold/collapse comment blocks in your IDE, such as [Eclipse](http://stackoverflow.com/questions/21968768/how-to-fold-comments-in-eclipse). – h.j.k. Jun 22 '15 at 07:38

1 Answers1

8

I have been using Javadoc feature of package comments to avoid littering source code with verbose documentation comments:

Package-Level Comments

With Javadoc 1.2, package-level doc comments are available. Each package can have its own package-level doc comment source file that The Javadoc tool will merge into the documentation that it produces. This file is named package.html (and is same name for all packages). This file is kept in the source directory along with all the *.java files. (Do not put the packages.html file in the new doc-files source directory, because those files are only copied to the destination and are not processed.)

The file package.html is an example of a package-level source file for java.text and package-summary.html is the file that the Javadoc tool generates.

The Javadoc tool processes package.html by doing three things...

Using above feature, I had detailed verbose documentation for classes and methods in the package stored separately of code, in a dedicated html file. As for Javadoc comments in java files, I just wrote brief explanations there, adding text like

If needed, refer to package documentation for more details.

One thing I particularly liked about this was that although docs were in the separate file and in a format more convenient for large docs (html), it has been stored close enough to related source code and all the updates in it were automatically picked up during the build.

Starting from Java 1.5, you can alternatively put a package-info.java along with the classes of the package. This file should look like this:

/**
 * Javadoc for your package here
 */
package com.yourpackage;

JLS documentation suggests that this is preferred way:

The following scheme is strongly recommended for file-system-based implementations: The sole annotated package declaration, if it exists, is placed in a source file called package-info.java in the directory containing the source files for the package...

It is recommended that package-info.java, if it is present, take the place of package.html for javadoc and other similar documentation generation systems. If this file is present, the documentation generation tool should look for the package documentation comment immediately preceding the (possibly annotated) package declaration in package-info.java. In this way, package-info.java becomes the sole repository for package-level annotations and documentation. If, in future, it becomes desirable to add any other package-level information, this file should prove a convenient home for this information.

gnat
  • 21,442
  • 29
  • 112
  • 288
  • how do you find package-info.java from the perspective of actually writing the text, HTML tags, javadoc keywords etc? Is it clunky or is it not a problem? – Adam Oct 15 '15 at 09:19