英文:
JavaDoc for Method with Multiple Signatures
问题
假设我有一个具有多个签名的方法（只是一个愚蠢的例子）。带有所有参数的方法是真正的工作马和所有其他方法都是方便的快捷方式。
我已经使用JavaDoc记录了工作马方法。
由于所有其他方法都是相同的，我不想重复文档。
在JavaDoc中是否有一种方式可以链接到完整的文档 - 或者其他一些不必一遍又一遍地重写文档的方式？
/**
* 用于格式化字符串的函数
*
* @param s 要格式化的字符串
* @param bold 字符串是否应为粗体？
* @param cursive 字符串是否应为斜体？
*
* @return 格式化后的字符串
*/
public static String formatMe(String s, Boolean bold, Boolean cursive){
String res = s;
// 处理粗体选项
if (bold) {
res = "BOLD" + res + "BOLD";
}
// 处理斜体选项
if (cursive) {
res = "KURSIVE" + res + "KURSIVE";
}
// 返回结果
return res;
}
public static String formatMe(){
return formatMe("", false, false);
}
public static String formatMe(String s){
return formatMe(s, false, false);
}
英文:
Suppose I have a method with multiple signatures (just a silly example). The method with all parameters is the actuall workhorse and all other methods are convenience shortcuts.
I have documented the workhorse method using JavaDoc.
Since all other methods work the same I do not want to duplicate the documentation.
Is there a way in JavaDoc to link to the full documentation - or some other way to not have to re-write the documentation over and over again?
/**
* Function to format a string
*
* @param s string to be formatted
* @param bold string should be bold?
* @param cursive string should be cursive?
*
* @return a formatted string
*/
public static String formatMe(String s, Boolean bold, Boolean cursive){
String res = s;
// handle bold option
if (bold) {
res = "BOLD" + res + "BOLD";
}
// handle cursive option
if (cursive) {
res = "KURSIVE" + res + "KURSIVE";
}
// return
return res;
}
public static String formatMe(){
return formatMe("", false, false);
}
public static String formatMe(String s){
return formatMe(s, false, false);
}```
</details>
# 答案1
**得分**: 3
是的...不...
OOTB JavaDoc不提供一种在一组方法（或其他元素）上具有相同文档的功能。但是，您可以引用已经存在的文档，就像这样：
```Java
/**
* 用于格式化字符串的函数。
*
* @param s 要格式化的字符串。
* @param bold 如果字符串应该是粗体，则为{@code true}，否则为{@code false}。
* @param cursive 如果字符串应该是斜体，则为{@code true}，否则为{@code false}。
* @return 格式化后的字符串。
*/
public static String formatMe( final String s, final boolean bold, final boolean cursive )
{
var retValue = s;
// 处理粗体选项
if( bold ) retValue = "BOLD" + retValue + "BOLD";
// 处理斜体选项
if( cursive ) retValue = "KURSIVE" + retValue + "KURSIVE";
// 完成！
return retValue;
}
/**
* 用于格式化字符串的函数。
*
* 调用
* {@link #formatMe(String,boolean,boolean)}
* 使用参数{@code &quot;&quot;,false,false}。
*
* @return 格式化后的字符串。
*
*/
public static String formatMe()
{
return formatMe( "", false, false );
}
/**
* 用于格式化字符串的函数。
*
* 调用
* {@link #formatMe(String,boolean,boolean)}
* 使用参数{@code s,false,false}。
*
* @param s 要格式化的字符串。
* @return 格式化后的字符串。
*/
public static String formatMe( String s )
{
return formatMe( s, false, false );
}
或者，您可以实现自己的JavaDoc标签，类似于{@inheritDoc}：
/**
* 用于格式化字符串的函数。
*
* @param s 要格式化的字符串。
* @param bold 如果字符串应该是粗体，则为{@code true}，否则为{@code false}。
* @param cursive 如果字符串应该是斜体，则为{@code true}，否则为{@code false}。
* @return 格式化后的字符串。
*/
public static String formatMe( final String s, final boolean bold, final boolean cursive )
{
var retValue = s;
// 处理粗体选项
if( bold ) retValue = "BOLD" + retValue + "BOLD";
// 处理斜体选项
if( cursive ) retValue = "KURSIVE" + retValue + "KURSIVE";
// 完成！
return retValue;
}
/**
* {@copyDoc #formatMe(String,boolean,boolean)}
*/
public static String formatMe()
{
return formatMe( "", false, false );
}
/**
* {@copyDoc #formatMe(String,boolean,boolean)}
*/
public static String formatMe( String s )
{
return formatMe( s, false, false );
}
您的新标签可以复制@return标签和与当前签名匹配的那些@param标签，以及一般描述。
但就我个人而言，我只是复制、粘贴和编辑而已。
英文:
Yes … no …
The OOTB JavaDoc does not provide a functionality to have the same documentation for a group of methods (or other elements). But you can refer to an already existing documentation, like this:
/**
* Function to format a string.
*
* @param s The string to be formatted.
* @param bold {@code true} if the string should be bold, {@code false}
* otherwise.
* @param cursive {@code true} if the string should be cursive, {@code false}
* otherwise.
* @return A formatted string.
*/
public static String formatMe( final String s, final boolean bold, final boolean cursive )
{
var retValue = s;
// handle bold option
if( bold ) retValue = "BOLD" + retValue + "BOLD";
// handle cursive option
if( cursive ) retValue = "KURSIVE" + retValue + "KURSIVE";
// Done!
return retValue;
}
/**
* Function to format a string.
*
* Calls
* {@link #formatMe(String,boolean,boolean)}
* with the arguments {@code &quot;&quot;,false,false}.
*
* @return A formatted string.
*
*/
public static String formatMe()
{
return formatMe( "", false, false );
}
/**
* Function to format a string.
*
* Calls
* {@link #formatMe(String,boolean,boolean)}
* with the arguments {@code s,false,false}.
*
* @param s The string to be formatted.
* @return A formatted string.
*/
public static String formatMe( String s )
{
return formatMe( s, false, false );
}
Alternatively, you can implement your own JavaDoc tag that works along the lines of {@inheritDoc}:
/**
* Function to format a string.
*
* @param s The string to be formatted.
* @param bold {@code true} if the string should be bold, {@code false}
* otherwise.
* @param cursive {@code true} if the string should be cursive, {@code false}
* otherwise.
* @return A formatted string.
*/
public static String formatMe( final String s, final boolean bold, final boolean cursive )
{
var retValue = s;
// handle bold option
if( bold ) retValue = "BOLD" + retValue + "BOLD";
// handle cursive option
if( cursive ) retValue = "KURSIVE" + retValue + "KURSIVE";
// Done!
return retValue;
}
/**
* {@copyDoc #formatMe(String,boolean,boolean)}
*/
public static String formatMe()
{
return formatMe( "", false, false );
}
/**
* {@copyDoc #formatMe(String,boolean,boolean)}
*/
public static String formatMe( String s )
{
return formatMe( s, false, false );
}
Your new tag can copy the @return tag and those @param tags that match the current signature plus the general description.
But me personally, I just use copy, paste and edit instead.
答案2
得分: 1
"More details here" 可翻译为 "更多详情请查看"，链接部分不需要翻译。
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论