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

Are there some good and modern alternatives to Javadoc?

提问by ivan_ivanovich_ivanoff

Let's face it: You don't need to be a designer to see that default Javadoc looks ugly.

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

There are some resources on the web which offer re-styled Javadoc. But the default behaviour represents the product and should be as reasonably good-looking.

网络上有一些资源提供重新设计的 Javadoc。但是默认行为代表产品并且应该看起来相当漂亮。

Another problem is the fact that the usability of Javadoc is not up-to-date compared to other similar resources.

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

Especially huge projects are hard to navigate using Firefox's quick search.

尤其是大型项目，使用 Firefox 的快速搜索很难导航。

Practical question:
Are there any standalone (desktop) applications which are able to browse existing Javadoc in a more usable way than a browser would?
I'm thinking about something like Mono's documentation browser.

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

Theoretical question:
Does anyone know, if there some plans to evolve Javadoc, in a somehow-standardized way?
EDIT:A useful link to Sun' wiki on this topic.

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

回答by Richard Nichols

I have created a Markdown (java) Docletwhich will take source comments in Markdown formatted text and create the same HTML Javadocs.

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

The new doclet also does some restyling on the text, but the HTML generated is not changed at this stage.

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

That goes some way to address the HTML-in-java-commenting issues which is probably the biggest usability problem with current Javadoc.

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

回答by Ralf Edmund

I don't think that the concepts of Javadoc are outdated. As far as i can see, these concepts are rooted years ago in a product named doxygen, which is still available for other languages (i.e. Objective-C where it is heavily used). Even this has it's predecessors - have a look at the programming environment used by Donald Knuth to create TeX (Literate programming).

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

Nevertheless it is a intriguing idea to have a single source for program code and documentation.

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

Besides of that, the presentation of the documentation can be customized to your special needs using a plug-in system supported by the JavaDoc tool. You might provide a plug-in (as we do) that publishes directly into a database which is directly accessible via web. Using collaborations anyone can provide additional comments or clarifications to the documentation that might find their way back into the original source.

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

回答by Esko

Javadoc is the best source code auto-documentation generation system I've ever seen. Large part of that is that it's so simple - I can browse javadocs even with my 5 year old cell phone if I want to! While I agree that a bit of a facelift could be in order and especially JDK is a pain to browse through, I wouldn't dare reinventing the wheel entirely because what we currently have is a RESTful, easy to use solution for its purpose which works just about anywhere.

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

回答by Joey

I recently got a mail forwarded that Sun is working on modernizing the Javadoc HTML output. From said mail:

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

We are proposing improvements to javadoc/doclet for JDK7. The project wiki page is located at http://wikis.sun.com/display/Javadoc/Home. As a part of the proposed improvements, the UI of the javadoc output will be revamped. The new design screenshots are uploaded to the project wiki. The javadoc output markup will be modified to be valid HTML and WCAG 2.0 compliant.

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

So there is definitely still work going on there, even if somewhat late. However, in my eyes one of the biggest drawbacks of Javadoc is its very close coupling with HTML. Many classes have Javadoc which includes literal HTML and relies on the output being HTML, too. Unfortunate, but this won't change anytime, I think. Still, this means that developers are free to include whatever they want in HTML there which might as well be invalid, non-well-formed, etc. So adapting the output from the javadoc tool is only one part of this, the other won't and can't change and thus remains.

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

As for browsing documentation I also find the HTML documentation a little unwieldy. I usually use the Javadoc view in Eclipse. It has drawbacks as well (slow and you can't really search) but it's Good Enough? for most things.

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

回答by Joachim Sauer

Personally I still find Javadoc to be very useful. Especially since it is standardized. I don't know of any major documentation style that I find easier to navigate (that might very well be subjective, but I personally find MSDN horrible to use, for example).

我个人仍然认为 Javadoc 非常有用。特别是因为它是标准化的。我不知道有什么主要的文档风格让我觉得更容易浏览（这很可能是主观的，但我个人认为 MSDN 使用起来很糟糕，例如）。

For the search: Use the Javadoc Search Frame, it makes using Javadoc of all kinds a lot easier. It's available as a Userscript for Firefoxand as a Google Chrome Extension.

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

回答by Gerrie

To answer your Practical Question, I googled and asked friends and came up with these. Forrestdoc,doclet and doxygen.

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

The second question, I would say that yes, its not very "Web-oh-twoeye" but At least your guaranteed to work in an offline environment, and its small enough to ship along with your API. i dispise the use of frames, but then it works rather well for javadoc. I have not seen any plans to change it. Eclipse has some support for javadoc as far as reading, interpreting and generating it goes.

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

回答by Michael Borgwardt

You might want to phrase that in a less agressive and overbearing manner. Most people don't care what a technical resource looks like, and "It's not Web 2.0 enough!" sounds like vapid marketroidspeak.

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

And what exactly would you consider "more usable"? Personally, I would definitely like a full text search and a better useage browser, and AJAX could probable help with those.

你认为“更有用”究竟是什么？就个人而言，我肯定想要全文搜索和更好的使用浏览器，而 AJAX 可能会对此有所帮助。

Well, the nice thing about JavaDoc is that it's the opposite of outdated - it's arbitrarily extensible. Why don't you go ahead and write a docletthat produces the kind of API doc you want?

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

Why nobody else has done that so far (which apparently is the case) is anyone's guess - maybe nobody else feels as strongly about it as you.

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

回答by Nat

There's a DocBook doclet. DocBook is a richer document type than (X)HTML and is better for describing technical content. From DocBook source you can generate all sorts of different output formats.

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

回答by JeeBee

I personally would like a more readable "comment documentation" standard than the HTML (and hence tag-wieldy) JavaDoc.

我个人希望有一个比 HTML（因此具有标签使用性）JavaDoc 更具可读性的“评论文档”标准。

For example, MarkDown, as used here, would be excellent, human readable in the source, nicely formatted external to the source.

例如，此处使用的 MarkDown 将是出色的、可读的源代码，并且在源代码外部格式良好。

With the current JavaDoc, I imagine many people use JavaDoc comments, but don't actually document to the extent they could. I'm sure everyone has browsed an API's online JavaDoc that has been non-documented or barely-documented, and thus far harder to use than it should be.

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

This isn't helped by code-reformatters (e.g., within Eclipse, or maybe upon source commit) that totally destroy any readable structure you might have put within a JavaDoc comment (e.g., a list of items) into one big blob of text, unless you literally use two carriage returns where you wish to use one).

代码重新格式化程序（例如，在 Eclipse 中，或者可能在源代码提交时）完全破坏了您可能在 JavaDoc 注释（例如，项目列表）中放入一大块文本的任何可读结构，对此没有帮助，除非你真的在你想使用一个的地方使用两个回车）。

回答by pmf

Does anyone know, if there some plans to evolve Javadoc, in a somehow-standardized way?

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

The corresponding JSR (JSR 260), which specifies enhancements to Javadoc, has been voted out of JDK 7 (for now). An overview of what was planned (from this site):

相应的 JSR (JSR 260)，它指定了对 Javadoc 的增强，已经被 JDK 7（目前）投票排除在外。计划内容的概述（来自本网站）：

Upgrade Javadoc to provide a richer set of tags to allow more structured presentation of Javadoc documentation. This JSR covers: categorization of methods and fields, semantical index of classes and packages, distinction of static, factory, deprecated methods from ordinary methods, distinction of property accessors, combining and splitting information into views, embedding of examples and common use-cases, and more.

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

The overall outlook for JDK 7 is pretty grim.

JDK 7 的总体前景非常严峻。