JavaDoc，整个项目的顶级文档

xvw2m8pv 于 2023-04-19 发布在 Java

关注(0)|答案(1)|浏览(145)

我认为提供顶级（项目级）Java Doc是一件很简单的事情，但是我环顾四周，我看到了大量关于如何记录包的信息，但是没有关于如何记录整个Java项目的信息，因此文档的索引页包含标题和项目描述，以及项目中的所有包。
假设我有一个项目，在它的src目录中我有三个包，每个包都有不同的Java类。每个类都有JavaDoc，每个包的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

Java

来源：https://stackoverflow.com/questions/76001100/javadoc-top-level-documentation-for-the-project-as-a-whole

1条答案

按热度按时间

jbose2ul1#

自从我发布这个问题已经有几天了，我已经想出了我认为在Java 1.9及以上版本中正确的方法。对于Java〈= 1.8及以下版本，我仍然没有答案，欢迎提出建议。
首先，项目本身应该在一个命名的包中，这是一个约定。根据约定，这看起来像是一个反向的URL，从最不具体的东西开始，向下钻取到最具体的项目名称。例如：

edu.myuni.mycourse.myname.my_proj2000

或用于商业组织。

com.mycompany.myproj2000

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

src/com/mycompany/myproj200/

然后你的项目包然后将在myproj 2000目录中创建，如下所示。如果我们采用一个Java类，如Theta，则它将是. com.mycompany.myproj2000/alpha/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，如果有人能证实我想知道的话。

赞(0）回复(0）举报 2023-04-19

我来回答

JavaDoc，整个项目的顶级文档

1条答案

相关问题

热门标签

最新问答