区分Javadoc的内部/外部方法

Question

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

（1）只将接口和工厂方法放在外部可见的包中，将这些接口的实现放在一个单独的包中，如this SO answer中所述。例如external.MyInterface和internal.MyInterfaceImpl。我觉得这很乱。

（2）在外部包中创建内部和外部方法public，并将Javadoc标记附加到内部方法，以便我可以在发布之前删除它们的文档，手动（容易出错）或者编写某种Javadoc预处理器或后处理器。

（3）使用Javadoc为此目的提供的机制 - 理想情况下，是一个Javadoc标记。

无论采用何种方法，我真正关心的是拥有一种为外部API自动生成Javadocs的一致方法。有没有标准的方法来做到这一点？一个工具为此目的？

Answer 1

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

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

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() { }
}

Answer 2

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

我不会被Javadoc困住，所以我可以选择Doxygen。然而，现在看看Doxygen，它与Javadoc如此不同，我不确定它是否值得学习曲线或建立先例只是为了能够生成外部API。

下面我将尝试构建另一个解决方案：我将划分仅限内部的源文件部分，编写一个复制外部包源文件的工具，同时删除部分内容仅在内部划分的文件，然后从生成的源运行Javadoc。这应该有效，除非Javadoc需要链接器满意。

我不知道是否值得回答我的问题。如果他们像我一样思考它，可能会帮助别人找到答案。即便如此，还没有人提出一个很好的解决方案。