区分Javadoc的内部/外部方法

Question

我正在用Java编写一个库。我将它的实现分成了Java包，以帮助管理复杂性。只有一个软件包包含对客户端可见的类。但是，因为只有公共方法在包的外部可见供库的其他包使用，所以我发现自己被迫执行以下操作之一：

（1）仅将接口和工厂方法放在外部可见包，将这些接口的实现放在一个单独的包中，如this SO answer中所述。例如external.MyInterface和internal.MyInterfaceImpl。我觉得这很混乱。 （2）在外部软件包中创建内部和外部方法public，并将Javadoc标签附加到内部方法，以便在发布之前删除他们的文档，可以手动（容易出错）或通过编写某种Javadoc预处理器或后处理器。 （3）使用Javadoc为此提供的机制 - 最好是Javadoc标记。不管采取什么方法，我真正关心的是如何使用一致的方式为外部API自动生成Javadoc。有没有一个标准的方法来做到这一点？一个用于这个目的的工具？

Answer 1

我在SO上的其他地方找到了these two answers。一种方法是创建一个自定义Javadoc注释，并在生成Javadoc之前使用Ant任务替换注释deprecated。另一种更简单的方法是使用Doxygen的条件包含。

我没有卡住Javadoc，所以我可以跟Doxygen一起去。然而，现在看着Doxygen，它与Javadoc完全不同，我不确定它是否值得学习曲线或建立一个能够生成外部API的先例。

下面是另一个解决方案，下次我将尝试构建：我将划分仅限于内部的源文件部分，编写一个工具来复制外部包的源文件，同时删除仅限于内部分区的文件部分，然后从生成的源代码运行Javadoc。这应该工作，除非Javadoc需要链接器才能开心。

我不知道是否值得保留我的问题。可以帮助别人找到答案，他们是否应该像我那样思考问题。尽管如此，还没有人提出过很好的解决方案。

Answer 2

我多年来一直使用的替代解决方案是使用此博客中提供的公共域代码添加@exclude标记：Implementing @exclude using Dynamic Proxies。

从的Javadoc输出排除Java元素（属性，方法，构造函数，类，内部类或包），只需添加@exclude标签在它的Javadoc：

public class MyClass { 
    /** 
    * This is my internal attribute, javadoc not exposed. 
    * @exclude 
    */ 
    protected String myInternalAttribute; 

    /** 
    * This is my external attribute, javadoc is exposed. 
    */ 
    protected String myExternalAttribute; 

    /** 
    * This is my internal method, javadoc not exposed. 
    * @exclude 
    */ 
    public void myInternalMethod() { } 

    /** 
    * This is my external method, javadoc is exposed. 
    */ 
    public void myExternalMethod() { } 
}