在典型的Maven项目中，项目文档应该存储在哪里？

Question

在典型的Maven项目中，项目文档（需求等）应存储在哪里？标准目录布局介绍页面列出的目录都不是显而易见的选择。

- user63904

---

我会投票支持'/docs'。'/src'下的所有内容都处于Maven环境中，最好不要对其进行更改。我认为该项目本身并不适合用于保存文档，请考虑安装维基百科。 - dma_k

在Maven中，所有的源文件都放在/src目录下。你编辑的文档也是源文件，应该放在/src目录的某个位置。如果你随意添加新的顶级目录，那么你的项目就不遵循Maven的约定，其他人将很难理解。 - dan carter

Answer 1

很遗憾，没有一种公约。如果你想让文档成为生成网站的一部分，那么 /src/site 显然是个不错的地方。也许你甚至可以用APT格式写文档?

但更有可能的是，你有一组文档、pdf和xls文件、图形、电子邮件等。你可以将它们放在 /src/site 下，并在网站中放置超链接，或者......定义自己的公约，可惜了。通常我看到过 /src/main/doc(s)，/src/doc(s)，甚至是 /doc(s)。

你不想将文档放在 /src/main/resources 或者 src/main/webapp，因为这些文件将成为构建产物（JAR/WAR）的一部分，这是很少需要的。

- Tomasz Nurkiewicz

---

src不是代表source的意思吗？ - Line

如果您的文档格式被处理成其他格式，它就是文档的源，因此将其放在 src 下是有意义的（/src/main/doc 用于代码文档，/src/doc 用于项目文档）。如果文档文件要按原样使用，则与 /src 平行的 /doc 更为合理。 - foo

Answer 2

http://www.sonatype.com/books/mvnref-book/reference/site-generation-sect-dir-struct.html 推荐以下结构：

sample-project
+- src/
[..]
+- resources/
|  +- images/
|  |  +- banner-left.png
|  |  +- banner-right.png
|  |
|  +- architecture.html
|  +- jira-roadmap-export-2007-03-26.html
[..]

- rob2universe

---

我不知道为什么Joao编辑了这篇文章，而不是发布一个替代建议。他将资源文件夹放在站点文件夹下面，这当然也是一个有效的选择。我发布/引用的建议使用了一个位于src和site文件夹旁边的顶级资源文件夹（请参见帖子中的链接）。并不是所有文档都必须包含在站点中。 - rob2universe

抱歉 @RobE，是我的错。 - Joao Piccinini

Answer 3

根据 maven-javadoc-plugin：

可以使用 <javadocDirectory/> 参数在生成的 javadoc 中包含其他资源，如 HTML 或图像。然后您可以在 javadoc 注释中链接到这些资源。默认情况下，所有 javadoc 资源都在 ${basedir}/src/main/javadoc 目录中。请注意，您需要设置 docfilessubdirs 参数以复制这些文件。

- Alun

---

你能看出一般文档和JavaDoc之间的区别吗？ :) - Line

有点。如果您将JavaDoc视为格式/文档生成器，则问题不在于仅记录API，而在于编写围绕它们解释其用途的文档。在JavaDocs/代码中包含这些内容，并链接到API似乎总是一个好主意。如果您要记录的是*API以外的内容，则我认为可以使用其他工具（例如markdown）。 - Alun