Javadoc有一些好的和现代的替代品吗？

Question

让我们面对现实：您不需要成为设计师就能看到它 默认 Javadoc看起来很丑陋。

网上有一些资源可以提供重新设计的Javadoc样式。但默认行为代表产品，应该看起来相当好看。

另一个问题是，与其他类似资源相比，Javadoc的可用性并不是最新的。

使用Firefox的快速搜索特别难以浏览大型项目。

实用问题：
是否有任何能够浏览的独立（桌面）应用程序 现有的Javadoc比浏览器更有用吗？ 我正在考虑使用Mono的文档浏览器。

理论问题：
有谁知道，如果有一些计划进化Javadoc，在一个 以某种方式标准化的方式？
编辑： A useful link to Sun' wiki on this topic。

Answer 1

我创建了一个Markdown (java) Doclet，它将在Markdown格式的文本中获取源注释并创建相同的HTML Javadoc。

新doclet还对文本进行了一些重新设置，但生成的HTML在此阶段不会更改。

这可以解决HTML-in-java-commenting问题，这可能是当前Javadoc最大的可用性问题。

Answer 2

我不认为Javadoc的概念已经过时了。据我所知，这些概念多年前在一个名为doxygen的产品中扎根，该产品仍可用于其他语言（即大量使用的Objective-C）。即使这有它的前辈 - 看看Donald Knuth用来创建TeX（Literate programming）的编程环境。

然而，为程序代码和文档提供单一来源是一个有趣的想法。

除此之外，可以使用JavaDoc工具支持的插件系统根据您的特殊需求定制文档的演示文稿。您可以提供一个插件（我们这样做）直接发布到可以通过Web直接访问的数据库中。使用协作，任何人都可以对文档提供额外的评论或说明，这些文档可能会重新回到原始来源。

Answer 3

Javadoc是我见过的最好的源代码自动文档生成系统。很大一部分就是它如此简单 - 如果我愿意的话，我甚至可以用我5岁的手机浏览javadoc！虽然我同意有点整容可能是有序的，特别是JDK是一个很难浏览，我不敢完全重新发明轮子，因为我们现在拥有的是一个RESTful，易于使用的解决方案，其目的是有效的几乎在任何地方。

Answer 4

我最近收到一封邮件，称Sun正在努力使Javadoc HTML输出现代化。从上述邮件：

  

我们建议对JDK7的javadoc / doclet进行改进。该   项目维基页面位于   http://wikis.sun.com/display/Javadoc/Home。作为提议的一部分   改进后，将改进javadoc输出的UI。新的   设计截图上传到项目维基。 javadoc输出   标记将被修改为有效的HTML和WCAG 2.0兼容。

所以那里肯定还有工作，即使有点迟了。然而，在我看来，Javadoc最大的缺点之一就是它与HTML的紧密结合。许多类都有Javadoc，它包含文字HTML，并且依赖于输出也是HTML。不幸的是，我认为这不会随时改变。尽管如此，这意味着开发人员可以自由地在HTML中包含任何他们想要的内容，这些内容可能也是无效的，非格式良好等等。因此，调整javadoc工具的输出只是其中的一部分，另一部分赢了t并且不能改变因此仍然存在。

至于浏览文档，我也发现HTML文档有点笨拙。我通常在Eclipse中使用Javadoc视图。它也有缺点（速度慢，你无法真正搜索），但对于大多数事情来说它都是Good Enough™。

Answer 5

为了回答你的实际问题，我用Google搜索并问朋友并提出了这些问题。 Forrestdoc，doclet和doxygen。

第二个问题，我会说是的，它不是非常“Web-oh-twoeye”，但至少你保证在离线环境中工作，并且它足够小，可以与你的API一起发布。我决定使用框架，但它对javadoc工作得相当好。我没有看到任何改变它的计划。 Eclipse对javadoc有一些支持，只要阅读，解释和生成它就可以了。

Answer 6

就我个人而言，我仍然认为Javadoc非常有用。特别是因为它是标准化的。我不知道有哪些主要的文档样式我觉得更容易导航（这可能非常主观，但我个人觉得MSDN使用起来很糟糕）。

对于搜索：使用Javadoc Search Frame，它使得使用各种Javadoc变得更加容易。它以Userscript for Firefox和Google Chrome Extension提供。

Answer 7

您可能希望以不那么激进和霸道的方式表达这一点。大多数人并不关心技术资源是什么样的，而且“它不够Web 2.0！”听起来像vapid marketroidspeak。

你认为“更有用”到底是什么？就个人而言，我肯定会喜欢全文搜索和更好的用户浏览器，而AJAX可能会对这些浏览器提供帮助。

嗯，关于JavaDoc的好处在于它与过时的相反 - 它是任意可扩展的。你为什么不继续写一个doclet来产生你想要的那种API文档？

为什么到目前为止没有其他人这样做（显然是这种情况）是任何人的猜测 - 也许没有其他人像你一样对此感到强烈。

Answer 8

有一个DocBook doclet。 DocBook是一种比（X）HTML更丰富的文档类型，更适合描述技术内容。从DocBook源代码，您可以生成各种不同的输出格式。

Answer 9

我个人希望获得比HTML（因此标记为wieldy）JavaDoc更易读的“评论文档”标准。

例如，这里使用的MarkDown非常出色，在源代码中是人类可读的，在源代码外部格式很好。

使用当前的JavaDoc，我想很多人都使用JavaDoc注释，但实际上并没有尽可能地记录。我确信每个人都浏览过API的在线JavaDoc，这些JavaDoc没有记录或几乎没有记录，因此使用起来比它应该更难。

代码重新格式化程序（例如，在Eclipse中，或者可能在源代码提交时）没有帮助完全破坏您可能在JavaDoc注释（例如，项目列表）中放入任何可读结构到一个大blob中除非你真的使用两个回车，否则你希望使用一个回车符。）

Answer 10

  

有没有人知道，是否有计划以某种方式标准化的方式发展Javadoc？

相应的JSR（JSR 260），它指定了对Javadoc的增强，已经从JDK 7中退出（目前为止）。计划内容概述（来自this site）：

  

升级Javadoc以提供更丰富的标记集，以允许更加结构化地呈现Javadoc文档。这个JSR包括：方法和字段的分类，类和包的语义索引，静态，工厂，已弃用方法与普通方法的区别，属性访问器的区别，组合和将信息拆分为视图，嵌入示例和常见用例，等等。

JDK 7的整体展望为pretty grim。

Answer 11

JavaDoc本身非常灵活，因为您可以使用自定义doclet替换标准doclet，以提供满足项目特定需求的内容。

在我一直致力于的项目中，我们为完全集成JavaDoc的产品创建了一个基于HTML / XML的文档系统（在JS上使用客户端XSLT 2.0）。为此，使用自定义doclet以XML格式生成JavaDoc数据，这使用了tagoup来确保代码注释中的HTML标记形成良好。

有了这个，我们能够使用单页应用程序（类似于桌面工具）提供交互式用户体验，但所有这些都来自浏览器 - 没有任何服务器端代码/基础设施。观众包括标准功能，如搜索，树导航等。

以下是相当庞大的文档中的示例入口点的链接： JavaDoc viewer sample

这是一张图片：

Answer 12

智能可访问的javadoc查看器：

很多时候，我遇到了浏览JavaDoc的问题。我正在寻找像Adnroid doc搜索选项一样的东西。最后我得到了类似的东西。如果您使用firefox，解决方案就在这里。

1. 以我们看到的方式安装插件GreaseMonkey，它有点像自定义网页。 （我们需要自定义任何java doc页面，所以我们可以搜索类名）  https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

2. 要使greasemonkey工作，我们需要一些用户脚本进行自定义。这可以通过greasemonkey自动下载。从JavaDoc search frame或JavaDoc incremental search安装用户脚本。

这对我很有用。