java - 如何在 Java 中为构造函数编写 API 文档

Question

我是否必须在 Java 中为 API 文档中的构造函数编写参数和返回标签？

这是我的代码：

/**
* Another constructor for class Time1
*/
public Time1 (Time1 other) 
    {
        _hour = other._hour; _minute = other._minute; _second = other._second;
    }   

Answer 1

创建 a 的全部目的Documentation是让其实现者能够理解您打算在代码中执行的操作。

• documentation你应该为一切 创造吗？是 的，计划使用你的程序员API可能不理解“显而易见”的目的，method,property,constructor,class所以，是的，即使它很明显（这可能对你来说很明显）。

仅在这种情况@param, @return annotations下才应使用using ，在您的问题代码示例中，您有：

/**
* Another constructor for class Time1
*/ public Time1 (Time1 other) 
    {
        _hour = other._hour; _minute = other._minute; _second = other._second;
    }

那么，您的构造函数是否返回了一些东西？不，那为什么要使用@return注释。constructor 但是你 所拥有的是一个参数，所以在这里做的正确的事情是：

/**
* Another constructor for class Time1
* @param other  <and explain its purpose>
*/
public Time1 (Time1 other) 
    {
        _hour = other._hour; _minute = other._minute; _second = other._second;
    } 

Answer 2

为构造函数包含返回标记是没有意义的，但除此之外，构造函数 Javadoc 就像任何方法的 Javadoc。您不必包含特定标签，但您可能出于各种原因选择包含 - 可能是为了阐明有关特定参数的一点，突出在什么条件下可能会引发特定异常，或者甚至只是为了遵守某些规定-房屋编码指南。

在 Javadoc 中只包含有用的信息通常是个好主意。类似的东西Another constructor for class Time1并不是特别有用 - 它没有描述为什么该构造函数可能用于另一个构造函数或为什么该构造函数存在。