javadoc 究竟是什么？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/19172015/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
What exactly is javadoc?
提问by
I am currently taking an AP Java class and I can't even begin to understand what "javadoc" is whatsoever, all that I seem to take out so far is that its a "different" way of commenting when creating an API so a programmer can better read the code . . .
我目前正在参加一个 AP Java 课程，我什至无法开始理解“javadoc”是什么，到目前为止我似乎认为它是一种在创建 API 时的“不同”评论方式，因此程序员可以更好地阅读代码。. .
I am new to this and I would appreciate any beginning point so I can at least grab on to the concept.
我对此很陌生，我会很感激任何起点，这样我至少可以抓住这个概念。
回答by tbodt
Javadoc is a program that reads your java files and creates HTML documentation out of them. You use it by adding comments with documentation, then invoking it.
Javadoc 是一个读取您的 Java 文件并从中创建 HTML 文档的程序。您可以通过在文档中添加注释来使用它，然后调用它。
回答by David says Reinstate Monica
Javadoc is a program much like a compiler that reads your codes and plucks out certain parts of it in order to create a (very very very very very) useful documentation in the form of html pages. The APIpages you use for standard java code is made using Javadoc.
Javadoc 是一个很像编译器的程序，它读取您的代码并提取其中的某些部分，以便以 html 页面的形式创建（非常非常非常非常）有用的文档。您用于标准 Java 代码的API页面是使用 Javadoc 制作的。
While parsing your code, Javadocs looks for two things: code structure and Javadoc comments. The code structure is just the code itself. That is used to build up the basic structure of a page (ie class name, fields, methods, etc). Javadoc comments are special comments that start with /**instead of the usual /*As far as the regular java compiler is concerned, it makes no difference though. Once in a Javadoc comment you write about the specific aspect of the code you are referencing and are able to use html tags as well as some other special syntax. You can learn more about it here
在解析您的代码时，Javadocs 寻找两件事：代码结构和 Javadoc 注释。代码结构就是代码本身。这用于构建页面的基本结构（即类名、字段、方法等）。Javadoc 注释是特殊注释，/**不是通常的注释，但就/*常规 Java 编译器而言，它没有区别。一旦在 Javadoc 注释中，您就可以写出所引用代码的特定方面，并且能够使用 html 标签以及其他一些特殊语法。你可以在这里了解更多信息
回答by Aurand
I was thinking about how to describe it, but honestly I think the SO Javadoctag does a very good job:
我正在考虑如何描述它，但老实说，我认为 SOJavadoc标签做得很好：
Javadoc is an extensible documentation generation system which reads specially formatted comments in Java source code and generates compiled documentation. It is typically used to produce API documentation in the form of HTML web pages.
Javadoc 是一个可扩展的文档生成系统，它读取 Java 源代码中特殊格式的注释并生成编译的文档。它通常用于以 HTML 网页的形式生成 API 文档。
Many IDEs also make use of Javadocs to generate contextual API descriptions. Javadocs can make the difference between an extremely obscure library and something that is a delight to use.
许多 IDE 还使用 Javadoc 生成上下文 API 描述。Javadoc 可以区分极其晦涩的库和使用起来令人愉悦的库。
Javadocs, use them!!
Javadocs，使用它们！！
回答by Uri
Sun defines JavaDoc as follows (http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html):
Sun 将 JavaDoc 定义如下（http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html）：
Javadoc is a tool for generating API documentation in HTML format
from doc comments in source code
The comments have a certain format that has become widely known as "Javadoc". You can see more details at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
注释具有某种格式，已被广泛称为“Javadoc”。您可以在http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html查看更多详细信息
回答by Little Child
Whenever you need to look up a Java method, you Google the name of the method and refer to the docs to see what it does. Great !
每当您需要查找 Java 方法时，您都可以在 Google 上搜索该方法的名称并参考文档以了解它的作用。伟大的 ！
But how did these docs come in place ? How was so much documentation generated ? Was someone hired to do that ?
但是这些文档是如何到位的呢？这么多文档是怎么产生的？有人雇来做那件事吗？
Well, whenever you write code you need to properly explain it in the source files using comments. /** */marks a comment block. Now, javadocis responsible for parsing these comments into documentation (It makes HTML files out of these comments). So, nobody was hired just javadocwas executed.
好吧，每当您编写代码时，您都需要使用注释在源文件中正确解释它。/** */标记一个注释块。现在，javadoc负责将这些注释解析为文档（它从这些注释中生成 HTML 文件）。所以，没有人被雇佣只是javadoc被处决。
Here is an example of beginning comment:
以下是开头注释的示例：
/**
* Classname
* Version info
* Copyright notice
*/
But that is not all. javadocis very powerful. It allows you to even write basic HTML inside the comments and then it parses the HTML to come up with a proper output. /** <html> */That is why some JacaDoc pages have tables. These were made using the <td>and <tr>tags in HTML
但这还不是全部。javadoc非常强大。它甚至允许您在注释中编写基本的 HTML，然后解析 HTML 以得出正确的输出。/** <html> */这就是为什么一些 JacaDoc 页面有表格的原因。这些是使用HTML 中的<td>和<tr>标签 制作的
For example,
例如，
/**
* First paragraph.
* <p><ul>
* <li>the first item
* <li>the second item
* <li>the third item
* <ul><p>
* Second paragraph.
*/
If you want javadoc to work properly with your code, follow the Java Code Convention : http://www.oracle.com/technetwork/java/codeconventions-150003.pdfif your code adheres to the convention, it becomes easy for javadoc to make the documentation.
如果您希望 javadoc 与您的代码正常工作，请遵循 Java 代码约定：http: //www.oracle.com/technetwork/java/codeconventions-150003.pdf如果您的代码遵守约定，javadoc 就很容易制作文档。
Here is the official Oracle guide to writing documentation comments: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
这是编写文档注释的 Oracle 官方指南：http: //www.oracle.com/technetwork/java/javase/documentation/index-137868.html
