如何为 Java 中的构造函数编写 API 文档

Question

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

这是我的代码：

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

Answer 1

创建 Documentation 的全部目的是让其 实现者 能够理解您打算在代码中做什么。

是否应该为所有内容创建 documentation？是计划使用你的 API 的程序员可能不理解 method,property,constructor,class 的 "obvious" 目的，所以，是的，即使它很明显（它可能对你来说很明显）也要这样做。

仅当是时才应使用 @param, @return annotations，在您的问题代码示例中，您有：

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

那么，您的构造函数 return 有什么用吗？不，那么为什么要使用 @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

为构造函数包含 return 标记没有意义，但除此之外，构造函数 Javadoc 就像任何方法的 Javadoc。您没有包含特定标签，但您可能出于各种原因选择包含 - 可能是为了阐明有关特定参数的观点，以突出显示在什么情况下可能会抛出特定异常，或者甚至只是为了遵守一些内部编码准则。

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

如何为 Java 中的构造函数编写 API 文档

How to write API documentation for constructors in Java

java

api

class-constructors