JavaDoc，项目作为一个整体的顶级文档

Question

我认为提供顶级(项目级)Java文档将是一件直接的事情，但我环顾四周，我看到了大量关于如何记录包的信息，但没有关于如何记录整个Java项目的信息，因此文档的索引页包含标题和项目描述，以及项目中的所有包。

假设我有一个项目，在它的src目录下我有三个包，每个包都有不同的Java类。每个类都有JavaDoc，每个Package alpha、beta和delta都有内部的Package -info.java来记录每个包:如下所示。当我这样做时，文档的索引没有标题，只是列出包。我想一个地方，包括标题和项目说明，版本信息等。

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

是否有一种方法可以为所有三个包提供顶级Java文档，而无需将所有三个包放在最外层的包内?或者最外层的包是实现这一点的唯一方法，以及Java期望的项目结构?例如:

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

Answer 1

自从我发布这个问题以来已经有几天了，我已经找出了我认为在Java 1.9及以上版本中正确的方法。对于Java版本<= 1.8及以下，我仍然没有答案，欢迎大家提出建议。

首先，项目本身应该在一个命名包中是惯例。按照惯例，这看起来像是反向的URL，从最不具体的东西开始，向下钻取到最具体的项目名称。例如:

edu.myuni.mycourse.myname.my_proj2000

或商业组织。

com.mycompany.myproj2000

如果您创建了这样一个包名，您将在项目目录中看到的是如下所示的文件夹层次结构。这是一个IDE将生成的，但是如果您手动执行此操作(没有IDE)，则必须自己创建。

src/com/mycompany/myproj200/

那么你的项目包，就会在myproj2000目录下创建，如下所示。如果我们取一个Java类，比如Theta那就对了。com.mycompany.myproj2000/α/Theta.java． 这就是所谓的全限定名． 这样做的好处是可以在大型项目中唯一地标识您的类，因为不同包中的类可能具有相同的名称。

因此，目录结构如下所示，每个包都有一个package-info.java用于文档目的，以及整个项目获取module-info.java下面是项目的结构，下面是package-info.java的示例。和module-info.java看起来像。

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

那么在这个项目中，package-info看起来如下，其中文档位于包文档之上。

/**
*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;

module-info.java看起来很像。

/**
* 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{
}

我怀疑在Java 1.9引入模块之前，最外层的包com.mycompany.myproj2000我也会得到一个package-info.java，如果有人确认的话，我想知道。