JavaDoc,整个项目的顶级文档

xvw2m8pv  于 2023-04-19  发布在  Java
关注(0)|答案(1)|浏览(157)

我认为提供顶级(项目级)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
jbose2ul

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.javamodule-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,如果有人能证实我想知道的话。

相关问题