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

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

这是我的代码:

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

最佳答案

创建 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;
    }

关于java - 如何为 Java 中的构造函数编写 API 文档，我们在Stack Overflow上找到一个类似的问题：https://stackoverflow.com/questions/34482472/