zh-google-styleguide/google-java-styleguide/javadoc.rst

.. _javadoc:

7. Javadoc
----------------

7.1. 格式
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

7.1.1. 一般形式
""""""""""""""""""""""""""""""""""""""""""""""""""

Javadoc块的基本格式如下例所示：

.. code-block:: java

    /**
     * 这里写了多行Javadoc文本,
     * 像通常一样包裹起来...
     */
    public int method(String p1) { ... }

或者如以下的单行示例所示：

.. code-block:: java

    /** 一段特别短的Javadoc文本。 */


基本格式始终是可以接受的。当整个Javadoc块（包括注释标记）可以放在一行时，可以使用单行格式。注意，这只适用于没有块标签（如 ``@return`` ）的情况。

7.1.2. 段落
""""""""""""""""""""""""""""""""""""""""""""""""""

在段落之间，以及在存在的块标签组之前，有一个空白行————也就是说，一个只包含对齐的前导星号（ ``*`` ）的行。除了第一个段落，每个段落在第一个单词之前都有 ``<p>`` ，其后没有空格。其他块级元素的HTML标签，如 ``<ul>`` 或 ``<table>``，前面不加 ``<p>`` 。

7.1.3. 块标签
""""""""""""""""""""""""""""""""""""""""""""""""""

使用的任何标准“块标签”都按照 ``@param`` 、 ``@return`` 、 ``@throws`` 、 ``@deprecated`` 的顺序出现，这四种类型的标签的描述永远不会为空。当一个块标签不能放在一行上时，续行缩进4个（或更多）空格从 ``@`` 的位置开始。

7.2. 摘要片段
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

每个Javadoc块都以一个简短的摘要片段开始。这个片段非常重要：它是在某些上下文中出现的唯一部分，如类和方法索引。

这应该是一个片段—————一个名词短语或动词短语，而不是一个完整的句子。它不是以 ``A {@code Foo} is a...`` 或 ``This method returns...`` 开头的，也不形成像 ``Save the record.`` 这样的完整祈使句。然而，这个片段就像是一个完整的句子一样需要首字母大写和相应的标点符号。

.. tip::

    **提示：** 一个常见的错误是以这种形式编写简单的Javadoc： ``/** @return the customer ID */`` 。这是不正确的，应该改为 ``/** Returns the customer ID. */`` 。

7.3. Javadoc的使用位置
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

至少每一个 ``public`` 类以及这样的类中的每一个 ``public`` 或 ``protected`` 的成员都有Javadoc，除了下文中提到的一些例外。

如第7.3.4节 :ref:`非必需的Javadoc <non-required-javadoc>` 所述，还可能存在其他的Javadoc内容。

7.3.1. 例外：不言自明的成员
""""""""""""""""""""""""""""""""""""""""""""""""""

对于简单且一目了然的成员，如 ``getFoo()`` ，在确实没有其他值得一提的内容的情况下，Javadoc是可选的，只需说明"Returns the foo"即可。

.. tip::

    **重要：** 如果某些典型的读者需要知道的相关信息被省略了，那么不适合用这个例外来为省略文档的错误做法辩护。例如，对于一个名为 ``getCanonicalName`` 的方法，如果读者很可能不知道"canonical name"是什么意思，那么不要省略其文档（以这里只需要说明 ``/** Returns the canonical name. */`` 为借口，但实际这里的成员名并非一目了然）！

7.3.2. 例外：重写
""""""""""""""""""""""""""""""""""""""""""""""""""

当一个方法重写超类型的方法时，不必总是在该方法上附带Javadoc。

.. _non-required-javadoc:

7.3.4. 非必需的Javadoc（译者注：原文中并没有7.3.3节）
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

其他类和成员可根据需要或作者意愿添加Javadoc。

每当需要使用实现注释来定义类或成员的总体目的或行为时，该注释应以Javadoc的形式编写（使用 ``/**`` ）。

非必需的Javadoc并不严格要求遵循第7.1.1、7.1.2、7.1.3和7.2节的格式规则，尽管这样做当然是推荐的。