java-docs

Java 文件 (Javadoc) 最佳實務

• 公開和受保護的成員應使用 Javadoc 註解進行文件化。
• 也建議為套件私有和私有成員撰寫文件，特別是當它們較複雜或不易自解釋時。
• Javadoc 註解的第一句話是摘要說明。它應簡潔概述方法的功能，並以句點結尾。
• 使用 @param 標記方法參數。說明以小寫字母開頭，且不以句點結尾。
• 使用 @return 標記方法回傳值。
• 使用 @throws 或 @exception 記錄方法拋出的例外。
• 使用 @see 參照其他型別或成員。
• 使用 {@inheritDoc} 繼承基底類別或介面的文件。
  • 除非有重大行為變更，此時應記錄差異。
• 使用 @param <T> 標記泛型型別或方法中的型別參數。
• 使用 {@code} 標記行內程式碼片段。
• 使用 <pre>{@code ... }</pre> 標記程式碼區塊。
• 使用 @since 標記功能引入的版本（例如版本號）。
• 使用 @version 指定成員的版本。
• 使用 @author 指定程式碼的作者。
• 使用 @deprecated 標記成員為已棄用，並提供替代方案。