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

Question

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

这是我的代码:

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

Answer 1

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

• 是否应该为所有内容创建文档？ 是计划使用您的 API 的程序员可能不理解 method,property,constructor,class 的“明显”目的，所以，是的，即使很明显也要这样做(这对你来说可能是显而易见的)。

使用 @param, @return annotations 应该只在这种情况下使用，在你的问题代码示例中你有:

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

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

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