83

让我们面对现实吧：您不需要成为设计人员就可以看到默认的Javadoc 看起来很丑。

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

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

特别是大型项目很难使用 Firefox 的快速搜索来导航。

实际问题：
是否有任何独立（桌面）应用程序能够以比浏览器更有用的方式浏览现有 Javadoc？
我正在考虑诸如 Mono 的文档浏览器之类的东西。

理论问题：
有谁知道，如果有一些计划以某种标准化的方式发展 Javadoc？
编辑： Sun' wiki 关于这个主题的有用链接。

4

12 回答 12

42

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

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

这在某种程度上解决了 HTML-in-java-commenting 问题，这可能是当前 Javadoc 最大的可用性问题。

于 2009-06-25T12:50:19.540 回答
21

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

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

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

于 2009-06-22T11:07:37.097 回答
13

Javadoc 是我见过的最好的源代码自动文档生成系统。很大一部分原因是它非常简单——如果我愿意的话，即使用我 5 年的手机，我也可以浏览 javadocs！虽然我同意可能需要进行一些改造，尤其是 JDK 浏览起来很痛苦，但我不敢完全重新发明轮子，因为我们目前拥有的是一个 RESTful、易于使用的解决方案，其目的是有效的几乎在任何地方。

于 2009-06-22T11:32:11.557 回答
11

我最近收到了一封转发的邮件，说 Sun 正在对 Javadoc HTML 输出进行现代化改造。从上述邮件中：

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

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

至于浏览文档，我也发现 HTML 文档有点笨拙。我通常在 Eclipse 中使用 Javadoc 视图。它也有缺点（速度慢而且你不能真正搜索），但它对于大多数事情来说已经足够了。

于 2009-06-23T09:11:28.073 回答
5

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

对于搜索：使用Javadoc Search Frame，它使使用各种 Javadoc 变得更加容易。它可用作 Firefox的用户脚本和Google Chrome 扩展程序。

于 2009-06-22T11:19:29.680 回答
4

为了回答你的实际问题，我在谷歌上搜索并询问了朋友并想出了这些。Forrestdoc、doclet 和 doxygen。

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

于 2009-06-22T11:11:40.863 回答
3

您可能想以一种不那么激进和霸道的方式来表达这一点。大多数人并不关心技术资源长什么样，“这还不够 Web 2.0！” 听起来像乏味的marketroidspeak。

您认为“更有用”的具体内容是什么？就个人而言，我肯定想要一个全文搜索和一个更好用的浏览器，而 AJAX 可能会在这些方面提供帮助。

嗯，JavaDoc 的好处在于它与过时相反——它可以任意扩展。您为什么不继续编写一个doclet来生成您想要的那种 API 文档呢？

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

于 2009-06-22T11:12:09.413 回答
2

我个人想要一个比 HTML（因此更易于标记）JavaDoc 更具可读性的“注释文档”标准。

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

对于当前的 JavaDoc，我想很多人使用 JavaDoc 注释，但实际上并没有尽其所能记录文档。我敢肯定，每个人都浏览过 API 的在线 JavaDoc，它没有记录或几乎没有记录，因此使用起来比应有的要困难得多。

代码重新格式化程序（例如，在 Eclipse 中，或者可能在提交源代码时）无济于事，它们完全破坏了您可能在 JavaDoc 注释（例如，项目列表）中放入一大块文本的任何可读结构，除非您从字面上使用两个回车符，否则您希望使用一个回车符）。

于 2009-06-23T09:19:24.093 回答
2

有谁知道，如果有一些计划以某种标准化的方式发展 Javadoc？

相应的 JSR (JSR 260)，它指定了对 Javadoc 的增强，已被 JDK 7（目前）否决。计划的概述（来自此站点）：

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

JDK 7 的整体前景相当严峻。

于 2009-06-23T09:52:50.063 回答
2

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

于 2009-06-22T11:03:12.787 回答
1

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

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

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

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

这里还有一张图片： 在此处输入图像描述

于 2012-09-29T07:05:58.650 回答
0

一个智能可搜索的 javadoc 查看器：

很多时候，我都面临浏览 JavaDoc 的问题。我正在寻找类似 Adnroid 文档搜索选项的东西。最后我得到了类似的东西。如果您使用 Firefox，解决方案就在这里。

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

  2. 为了让greasemonkey 工作，我们需要一些用户脚本进行定制。这可以通过greasemonkey自动下载。从JavaDoc 搜索框架或JavaDoc 增量搜索安装用户脚本。

这对我很有用。

于 2011-02-27T13:24:45.900 回答