javadocumentationjavadoc

JavaDoc, Top Level Documentation for the Project as a whole

I thought providing top level (Project level) Java Doc would be a straight forward thing to do, but I look around and I see an abundance of information on how to document packages, but nothing on how to document whole Java projects, so that the index page of the documentation contains a title and a project description, as well as all the packages in the project.

Lets say I have a project, in its src directory I have three packages each with various Java classes. Each class has JavaDoc and each Package alpha, beta, and delta has internally package-info.java to document each package: As follows. When I do this the index of the documentation has no title and just lists the packages. I would like a place to include a title and a project description, version information etc.

src:
======================
alpha
  package-info.Java
  Theta.Java
  Omega.Java

beta
  package-info.Java
  Gamma.java
  Epsilon.Java

delta
   package-info.java
   Kappa.java
   Iota.java

Is there a way to have top level Java Documentation for all three packages without placing all three packages inside an outermost package? Or is the outer most package the only way to do this and how Java expects project to be structured? For example:

src:
======================
my_proj:
  package-info.Java

  my_proj.alpha
    package-info.Java
    Theta.Java
    Omega.Java

  my_proj.beta
    package-info.Java
    Gamma.java
    Epsilon.Java

  my_proj.delta
    package-info.java
    Kappa.java
    Iota.java
Solution

  • Its been a couple of days since I posted the question and I have worked out what I think is the proper way to do it in Java 1.9 and above. For Java versions <= 1.8 and below, I still do not have an answer and will welcome suggestions.

    Firstly, it is the convention that projects themselves should be in a named package. By convention this looks like a URL in reverse, starting with the least specific thing and drilling down to the most specific project name. For example:

    edu.myuni.mycourse.myname.my_proj2000

    or for a business organization.

    com.mycompany.myproj2000

    What you would see in your project directory, if you created such a package name is a folder hierarchy such as the following. This is what an IDE would generate, but if you are doing this manually (without and IDE), you would have to create this yourself.

    src/com/mycompany/myproj200/

    Your project packages would then be created inside the myproj2000 directory as shown above. If we take a Java class such as Theta and wanted this in the package Alpha, then it would be. com.mycompany.myproj2000/alpha/Theta.java. This is what is known as a fully qualified name. This has the benefit of uniquely identifying your class in a large project where classes in different packages may have the same name.

    So the directory structure is therefore as follows with each package getting a package-info.java for documentation purposes, and the project as a whole getting module-info.java Below is the structure of the project, and below this is example of what the package-info.java and module-info.java would look like.

    src:
======================
com.mycompany.myproj2000:
  module-info.java

  com.mycompany.myproj2000.alpha
    package-info.Java
    Theta.Java
    Omega.Java

  com.mycompany.myproj2000.beta
    package-info.Java
    Gamma.java
    Epsilon.Java

  com.mycompany.myproj2000.delta
    package-info.java
    Kappa.java
    Iota.java

    Then within this project the package-info looks as follows where the documentation comes above the package documentation.

    /**
*My documentation for my lovely alpha package, blah blah blah. It does blah blah.
* @Author Joe Bloggs
* @Version 1.02 Spring 2023
**/
package com.mucompany.myproj2000.apha;

    The module-info.java looks similar.

    /**
* This project does blah blah blah it was created for blah blah so that blah blah
* @Author Joe Bloggs
* @Version 1.02 Spring 2023
**/
module com.mycompany.myproj2000{
}

    I suspect that before Java 1.9 when modules were introduced that the outer most package com.mycompany.myproj2000 would also get a package-info.java, if anyone would confirm that I'd like to know.