如何_使用_ javadoc答案

【问题标题】：How to _use_ a javadoc如何_使用_ javadoc
【发布时间】：2015-08-09 13:54:02
【问题描述】：

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

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

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

事实证明，这种语法称为javadoc (?)。我的问题是：我如何使用这个 javadoc 东西？我应该将项目导入一个单独的项目，还是编辑给定的代码？如果是这样 - 例如，我该如何修改 @param 语法？

【问题讨论】：

您并没有真正以您认为的方式使用 javadoc。它只是代码文档，没有什么可以阻止它完全错误或与代码无关。它可以帮助您理解您希望使用的代码，仅此而已。
你的问题没有多大意义。如果您下载了一个库，您通常不会修改它的 javadoc（除非您做出贡献）。而且 - 除非您编写自己的 doclet - javadoc 语法也是给定的：您无需更改它。
另见：stackoverflow.com/questions/29815636/and-in-java-comments

标签： java eclipse javadoc

【解决方案1】：

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

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

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

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

以 Eclipse 为例：

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

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

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

您还可以在您的 javadoc cmets 中使用原始 HTML，并且您可以在向导中和作为命令行参数使用许多 javadoc 生成参数。

【讨论】：

嘿@Mena，感谢您的回答。我要问的不是如何使用 javadoc 功能（HTML 站点等），而是 - 鉴于我下载了使用 javadoc 的代码，我如何使用代码本身？例如：如何更改参数？
@Cheshie 我会阅读 javadoc 并找出代码的用途。如果文档很少或没有，则必须调查源代码或在运行时对其进行调试。
@Cheshie “如何更改参数”是什么意思？
@Cheshie 如果您需要更改方法的参数（再次，我建议通过 IDE 进行重构以确保安全），您可能希望将这些参数反映在您的 javadoc 中。您还可以为几乎任何您需要的东西自动生成草稿 javadoc。

【解决方案2】：

语法如下：

@param      value    the explanation of the value.

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

这是All the ways to generate javadoc in Eclipse

【讨论】：

【解决方案3】：

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

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

【讨论】：

【解决方案4】：

由于已经有很好的答案已经描述了 JavaDoc 的使用，我将不再重复它们并简短说明：JavaDoc 用于代码文档。这意味着它对其描述的代码没有任何功能影响。它只是描述了方法、类、常量等的作用。这样做的好处是您不必通过代码来找出方法的用途以及它返回的确切内容。恕我直言，它节省了很多时间。

至于更改方法的参数：您只需像没有 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的参数描述，然后是方法返回的描述。

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

    /**
     * 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);
     }

【讨论】：