简单的get方法javadoc

Posted 2023-02-21

【中文标题】简单的get方法javadoc

【英文标题】：Simple get method javadoc

【发布时间】：2018-07-06 00:10:47

【问题描述】：

我是 Java 新手，我想问一个关于 Javadoc cmets 的简单问题。假设我有一个简单的方法：

public int getNumber()

Javadoc 注释应该是 @return A number OR @return int A number ?

【问题讨论】：

如果您的问题是是否需要在@return 信息中包含返回类型，那么不需要。返回类型是方法签名的一部分。不需要重新指定。

@khelwood 那么，方法的类型并不重要？即使方法是 public float getNumber() ，javadoc 仍然会保持 @return A number 正确吗？

“一个数字”是一个非常无用的描述。但正如我所说，您不需要重新指定返回类型。即使它是一个浮点数。

@khelwood 是的，我知道！我将此描述用于更通用的示例。非常感谢

【参考方案1】：

参考：

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

关于编写 javadocs 的好技巧。

您不需要在 @return 注释中指定“int”。因为这是方法签名的一部分，可以从那里推断出来。更准确的做法是描述您返回的数字类型，即：解释该数字是什么。

这是一个您可以使用的示例：

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute @link URL. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */
 public Image getImage(URL url, String name) 
        try 
            return getImage(new URL(url, name));
         catch (MalformedURLException e) 
            return null;
        
 

【讨论】：

非常感谢@arocketman！正是我想要的！答案已接受

【参考方案2】：

您不必特别说明方法的返回类型，因为它是方法签名的一部分。所以 Javadoc 注释就是 @return A Number。但是，如果返回类型为 void，则不需要包含 @return 注释。

如果您有兴趣了解更多，这里有一篇关于 Javadoc cmets 的好文章：http://www.oracle.com/technetwork/articles/java/index-137868.html

编辑：刚刚意识到其他人早些时候发布了这个 ^ 链接，但它仍然是一个很好的来源:)

【讨论】：

非常感谢@btc1322 的评论！ :)