如何_使用_javadoc

Question

我有一个关于 javadocs 的非常基本的问题 - 提前致歉，我完全不熟悉这个话题，无法在 google 上找到答案。

我在java中下载了某个implementation，并将下载的项目导入到Eclipse中。在我需要的文件中，我发现了我不熟悉的语法，例如以下出现在函数之前：

/**
 * Default implementation of the MarkovDecisionProcess<S, A> interface.
 * 
 * @param <S>
 *            the state type.
 */

原来这种语法叫做javadoc（？）。我的问题是：如何使用这个 javadoc 东西？我应该将项目导入一个单独的项目，还是编辑给定的代码？如果是这样 - 我如何修改 @param 语法，例如？

Answer 1

Javadoc 是一种元语言，允许自动 HTML 生成来记录您的项目。

您可以在 java.lang.Object here 上找到示例页面。

有关如何使用 javadoc 工具的官方文档和指南是 here。

如果您使用的是 IDE，您可以预览您的 javadoc。

例如在 Eclipse 中：

项目
生成 javadoc...
这将打开一个向导。按 Finish 后，您会在您选择的位置获得一个包含您的文档的迷你站点。

首先，您可以通过 /** ... */ 语法（或 Eclipse 中的 Alt-Shift-J 自动生成 javadoc 注释）对您的方法、变量和 class 声明进行 javadoc 注释。

@param 和其他选项允许您指定文档的各个方面。

您还可以在 javadoc 注释中使用原始 HTML，并且您有许多 javadoc 生成参数可用于向导和命令行参数。

Answer 2

语法如下：

@param      value    the explanation of the value.

这意味着您的 class 有一个参数值。当您试图了解 class 的作用时，您并没有真正使用此代码 expect。它们就像评论一样，但您可以使用该代码在 Eclipse 中自动生成文档。 Eclipse 将读取这些注释并将其格式化为 html 文件。

这是All the ways to generate javadoc in Eclipse

Answer 3

Javadocs 提供有关您的代码的信息。 Eclipse（可能还有所有其他 IDE）使用它来为您提供有关您当前正在编写的代码的信息。

这只是我开始输入 System.cu... 时打开的小 window 的图片。唯一匹配它的函数是 currentTimeMillis，因此选择了该函数。右边是另一个包含 javadoc 的 window。它可以向您展示很多关于函数功能的信息，有时甚至是它是如何工作的。它还可以为您提供有关每个参数的信息（这就是 @param 的用途）、return 值、可能抛出的任何异常以及相关的 functions/classes 等

Answer 4

既然已经有很好的答案已经描述了JavaDoc的使用，我就不再重复它们并简而言之：JavaDoc用于代码文档。这意味着它对其描述的代码没有任何功能影响。它只是描述方法、class、常量等的作用。这样做的好处是您不必通过代码来找出方法的用途和确切的用途 returns。恕我直言，它节省了很多时间。

至于更改方法的参数：您只需像通常没有 javaDoc 的情况一样更改代码。为了防止文档说的不是代码实际做的事情，您可以根据您对方法的更改来更改 javaDoc。 JavaDoc 通常如下所示：

    /**
     * Creates an instance of foo.
     * 
     * @param bar
     *            the size of bar
     * @return the created foo
     */
     public Foo createFoo(Bar bar)
     {
        //do something
        return new Foo(bar);
     }

如您所见，方法描述后面是 bar 的参数描述，然后是方法的描述 returns。

要添加新参数，您只需向 javaDoc 添加新的@param：

    /**
     * Creates an instance of foo.
     * 
     * @param bar
     *            the size of bar
     * @param foobar
     *            <describe here what foobar is>
     * @return the created foo
     */
     public Foo createFoo(Bar bar, Foobar foobar)
     {
        //do something
        return new Foo(bar);
     }

如何_使用_javadoc

How to _use_ a javadoc

java

eclipse

javadoc