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

Question

是否需要为Java文档中的Java构造函数编写param和返回标记？

这是我的代码：

/**
* 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,classso 的“明显”目的，即使是显而易见的，也要这样做（对您来说可能很明显）。

使用@param, @return annotations应只当这是的情况下，你的问题的代码示例您有：

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