如何为 Java 中的构造函数编写 API 文档
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/34482472/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How to write API documentation for constructors in Java
提问by user1454994
Do I have to write param and return tags for constructors in Java for API documentation?
我是否必须为 API 文档的 Java 中的构造函数编写参数和返回标签？
This is the code I have:
这是我的代码：
/**
* Another constructor for class Time1
*/
public Time1 (Time1 other)
{
_hour = other._hour; _minute = other._minute; _second = other._second;
}
回答by esteban rincon
The whole purpose of creating a Documentationis for its implementorsto be able to understand what you intended to do in your code.
创建 a 的全部目的Documentation是让其实现者能够理解您打算在代码中做什么。
- Should you create
documentationfor everything ? yesThe programmers who plan to use yourAPImight not understand the "obvious" purpose of amethod,property,constructor,classso, yes, do it even if it is obvious (It might be obvious just to you).
- 你应该
documentation为一切创造吗？ 是的 计划使用您的程序员API可能不理解 a 的“明显”目的，method,property,constructor,class所以，是的，即使它很明显，也要这样做（这对您来说可能很明显）。
Using @param, @returnannotationsshould be used only when this isthe case, in your question code example you have:
使用@param, @returnannotations应只当这是的情况下，你的问题的代码示例您有：
/**
* Another constructor for class Time1
*/ public Time1 (Time1 other)
{
_hour = other._hour; _minute = other._minute; _second = other._second;
}
So, does your constructor return something ? no, so why use the @returnannotation.
But what your constructordoeshave is a parameter, so the correct thing to do here would be:
那么，你的构造函数是否返回了一些东西？不，那为什么要使用@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;
}
回答by sisyphus
It doesn't make sense to include a return tag for a constructor but other than that, the constructor Javadoc is like any method's Javadoc. You don't haveto include a particular tag but you mightchoose to for various reasons - possibly to elucidate a point about the particular parameter, to highlight under what conditions a particular exception might be thrown, or even just to comply with some in-house coding guidelines.
为构造函数包含返回标记没有意义，但除此之外，构造函数 Javadoc 就像任何方法的 Javadoc。你不必有包括特定的标签，但你可以选择各种原因-可能是为了阐明一个关于具体的参数来看，要突出在什么条件下特定的异常可能会被抛出，甚至只是为了满足一些IN-房屋编码指南。
It's generally a good idea only to include useful information in Javadoc. Something like Another constructor for class Time1isn't particularly helpful - it doesn't describe why that constructor might be used over another constructor or why this constructor exists.
通常只在 Javadoc 中包含有用的信息是一个好主意。类似的东西Another constructor for class Time1并不是特别有用 - 它没有描述为什么可以在另一个构造函数上使用该构造函数或为什么这个构造函数存在。
