在抽象方法中编写javadoc的正确方法是什么

Question

public interface ISomething
    /**
     * This method does something!
     */
    public void something();
}

public abstract class AbstractSomething implements ISomething
{
    /**
     * See {@link #doSomething()}
     */
    public final void something()
    {
        doSomething();
        // Do something else...
        ...
    }

    protected abstract void doSomething();
}

public class ConcreteSomething extends AbstractSomething
{

    /**
     * Concrete implementation of doSomething(). It does... something!
     */
    @Override
    protected void doSomething()
    {
        // Actually do something...
        ...
    }
}

所以我有一个看起来像这个的 class 层次结构。这个想法是使用 public final something() - 然后是抽象 - doSomething() 模式，以便扩展 classes 将有义务调用 super()，例如 Andrzej answer's

然后，我最终会有几个扩展 AbstractSomething 的实现。此代码的客户端随后将实例化这些实现并使用 ISomething 方法。

像这样：

public class Main
{
    public static void main(String[] args)
    {
        ConcreteSomething concrete = new ConcreteSomething();
        concrete.something();
    }
}

所以问题是，使用这种设计习惯是否有正确的方法来为层次结构编写良好的 javadoc？

我所说的正确是指：当客户调用 concrete.something() 时，我希望他们看到 ConcreteSomething#something() javadoc。但是，由于该方法是最终方法，我不能简单地覆盖它并编写一个具体的 javadoc。此外，我的客户不会看到 doSomething() 方法，因为它是受保护的，所以我不能把具体的 javadoc 也放在那里。

换句话说，我可能需要 {@InheritDoc} 的 相反 :)

有什么建议吗？

Answer 1

问题类似于接口的文档。客户将使用抽象并且主要看到该抽象的通用文档。在你的情况下，你能做的最好的事情就是将文档添加到每个具体 class 的构造函数中。至少这样客户会看到实施的细节，如果需要，您可以包括相关的 @link 和 @see。

在抽象方法中编写javadoc的正确方法是什么

What is the correct way to write javadoc in abstract methods

java

javadoc