如果实现方法具有JavaDoc评论，如果它们实现的接口具有JavaDoc评论

假设我有一个接口，如下所示。如果实现方法具有JavaDoc评论，如果它们实现的接口具有JavaDoc评论

public interface MyInterface{ 

/** 
* This method prints hello 
*/ 
    void sayHello(); 

    /** 
    * This method prints goodbye 
    */ 
    void sayGoodBye(); 
}

一个具体类实现了这些方法。现在，具体类中的方法是否还需要在其方法定义之上定义javadoc？我看到有些人只是将相同的javadoc定义复制到具体类的实现方法中。我不认为这是一个好的做法，因为如果我们要改变文档定义，我们需要在多个地方进行更改。

这是什么标准做法？

来源

2016-11-20 DesirePRG

在声明方法的接口中可以有方法所做的概述。在实施过程中，如果需要，您可以在方法中详细说明该方法的确切功能。理想情况下，如果您使用正确的编码标准，则不需要提供如此详细的解释。 – Raghuveer

你的意思是说接口方法javadocs应该是简短的吗？ – DesirePRG

是的，但也足以描述性的让读者理解API应该做什么。 – Raghuveer

您可以使用{@inheritDoc}来继承接口的文档，并且只需添加额外的注释，如果您认为它们是特定实现的重要且相关的额外信息。

如果您打算添加到原始超类/接口文档，则只能使用@inheritDoc。如果你只需要一个副本，Javadoc会照顾到这一点。它会看到超类文档适用于子类的重写方法，因为子类没有提供额外的文档。

{@inheritDoc} - 继承（副本）这个标签的位置从“最近的”继承类或实现的接口插入当前文档注释文档。这允许你在继承树上写更多的一般注释，并写出复制的文本。

http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc

来源

2016-11-20 07:21:24

你不需要那样做。除非您想添加特定于实现的材质，并且将同一个文本块中的继承材料和添加材料同时添加，否则没有什么意义。 –

现在做的具体类的方法也需要定义它的方法定义的顶部的Javadoc？

不，已经指定。具体的方法应该做到Javadoc所说的界面，而不是别的。

我看到一些人只是将相同的javadoc定义复制到具体类的实现方法。我不认为这是一个好的做法，因为如果我们要改变文档定义，我们需要在多个地方进行更改。

你是对的。他们不应该这样做。

您不应该使用@inheritDoc，除非极少数情况下，具体方法需要更多描述而不是已经存在于接口Javadoc中。大多数时候，你不应该提供任何的Javadoc可言，甚至没有：

/** 
* 
*/

来源

2016-11-20 07:28:28 EJP

您的具体实施应提供评论，如果

该接口的评论是很通用它没有充分指定具体实施
具体实施放宽了接口的任何先决条件
具体实施更严格（更窄）后公司nditions比界面。

来源

2016-11-20 09:05:49 Raedwald

如果实现方法具有JavaDoc评论，如果它们实现的接口具有JavaDoc评论

回答

相关问题