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