混合（Scala/Java）项目的单一文档？

Posted 2023-03-24

【中文标题】混合（Scala/Java）项目的单一文档？

【英文标题】：Single documentation for mixed (Scala/Java) project?

【发布时间】：2011-01-04 00:46:16

【问题描述】：

对于包含 Scala 和 Java 模块（并排）的项目，如何将 scaladoc 与 javadoc 结合起来以提供项目文档的单一视图？

（这可能是使用 maven、ant 或 sbt，更一般的问题）。

任何想法和经验表示赞赏。

【问题讨论】：

+1 即使 ScalaDoc 和 JavaDoc 保持分离，能够交叉链接引用也很棒。

【参考方案1】：

Scala 2.8 的新 scaladoc 将取代 Scala 2.7 中使用的那个，差异将更加显着。但是，有人要求提供将 scaladoc 转换为 javadoc 格式的函数，以供 IDE 在显示帮助时使用。

如果这个函数可用，那么从 scaladocs 生成 javadocs 的东西在理论上是可行的。

但要使这一切成为现实，对此类事情感兴趣的人必须在适当的论坛上发表意见。当然，如果他们的团队太小，除非他们自己动手，否则很可能什么都不会发生。

【讨论】：

我的想法更像是人们在 scala 中创建库，而这些库曾经是在 java 中创建的。所以两个 java lang 用户都可能想要使用它们——这个库是用 scala 编写的这一事实不必过多地关注消费者。为此，scaladoc 就足够了，但我想如果你真的想隐藏它是 scala 的事实，它不会削减它 - 我会进一步研究它，谢谢你的回答！

【参考方案2】：

Scaladoc Javadoc 有什么好处？有大量的 Javadoc 工具和 Scaladoc 的几乎所有工具。主流 IDE（Eclipse、Netbeans、Idea——现实世界的企业开发——不是学术研究）对 Scaladoc 一无所知。仿佛置身于西伯利亚：与世隔绝。

【讨论】：

我想这就是我的观点。如果您正在编写一个用于一般消费的库，并且您希望消费者不关心它是用 scala 编写的，那么 javadoc 会很好（当然，无论如何您必须注意如何为公共接口编写 scala）。

【参考方案3】：

Scaladocs 和 javadoc 非常不同，具有不同的格式。它们只是两种不同的动物，我认为将它们结合起来没有意义。因此，AFAIK，Maven 对此不提供任何支持（这并不奇怪），只需分别生成它们。