我對javadoc中的文檔邏輯位置有疑問。例如，我有一個接口以下方法簽名：javadoc中的文檔邏輯
public int getTotalAssociationsAsParent(Long id, Long type);
該方法返回關聯，其中給定的ID是父和關聯類型「類型」的。 ID是必需的，但如果傳入的類型爲NULL，那麼我將返回ID爲父級的所有關聯。
我的問題是應該在哪裏記錄這種類型的邏輯？我毫不猶豫地將它放在界面的javadoc中，因爲這種方式限制了所有實現類遵循該邏輯。也許在將來，如果type爲NULL，我會有一個Impl類拋出IllegalArgumentException。
但是，如果我將它放入Impl類中的非javadoc中，則此方法的使用者將不知道該方法如何以NULL類型行爲。
你描述的是該方法的接口契約，所以它確實屬於Javadoc。界面的客戶需要知道該界面滿足的確切合同。如果派生類以不同的方式實現該方法，則它實際上違反了合同，因此打破Liskov Substitution Principle。
但是，如果你覺得真的有地方這種方法的不同實現，你有一些選擇：
您應說明會重新在什麼情況下轉向客戶。客戶不需要知道如何處理以返回它，但它應該知道某種輸入，會返回一些特殊的輸出。
在未來，如果你想拋出一個異常，你必須改變你的javadoc，使主叫方可以知道它具有處理異常
一般來說，你把這個接口，該接口定義上實現的行爲。然而，這裏並沒有硬性規定，如果某個特定實現的行爲不同，那麼也可以在實現註釋中加入這一差異。這與Java標準庫在JavaDoc中執行的操作非常相似。
考慮，例如，ArrayList的：
http://java.sun.com/javase/6/docs/api/java/util/ArrayList.html
具有的removeAll，這是在列表中定義和在類AbstractCollection
http://java.sun.com/javase/6/docs/api/java/util/List.html#removeAll(java.util.Collection)
List類定義實現它做了什麼，AbstractCollection類定義了它特定的行爲。
文檔是一個工具，讓你覺得適合使用它們，這個工具的最重要的部分是，他們保持目前的 - 這麼過來的文檔化後可引起頭痛，下記錄呢！通常，還要儘量保持每個方法中編寫的代碼簡潔明瞭，儘可能避免副作用，這樣您就可以閱讀代碼並理解它的含義，而不必依賴周圍的文檔。
看上去很適合的Javadoc：
/**
* The method returns associations where the given ID is the parent and the association is of type 'type'. <br>
* ID is required, but if type passed in is NULL, then I will return ALL associations where the ID is the parent.<br>
*<br>
* Subclasses may throw an IllegalArgumentException if type is NULL.<br>
* @param id Parent identifier
* @param type the type of association
* @return the Association or null if type is null
*/
public int getTotalAssociationsAsParent(Long id, Long type)
我希望有這樣的文檔在過去的我自己。
我通常會：
/**
* get the total associations as parent
* @param id the id
* @type the type
*/
public int getTotalAssociationsAsParent(Long id, Long type);
這是沒有用的。
謝謝你的建議（大家）。 我想我需要做的就是把這個接口的Javadoc，並定義這個方法應該做的。如果它曾經談到過，我確實需要返回所有關聯的方法，我只需創建： 公衆詮釋getTotalAssociationsAsParent（長ID）; 應當指出的是，這甚至不是一個要求，無論如何，所以我應該在這裏遵循YAGNI原則。 – sma 2010-05-25 15:49:39