如何在Java

Question

我是否必须在Java中为API文档编写param并为构造函数返回标记？

这是我的代码：

/**
* 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的“明显”目的，所以，是的，即使它很明显也是如此（对您来说可能很明显）。

只有在 的情况下才能使用@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;
    } 

Answer 2

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

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