Javadoc：package.html或package-info.java

211

當試圖創建包級Javadoc註釋時，最佳方法是什麼？你是做什麼？Javadoc：package.html或package-info.java

package-info.java

優點
- 較新的
缺點
- 一類的惡習 - 類是代碼，而不是隻評論

package.html的

優點
- HTML擴展意味着它不是代碼
- 語法高亮顯示在IDE的/文本編輯器
缺點
- 無？

對於我來說，我一直使用package.html的。但我想知道它是否是正確的選擇。

來源

2010-09-05 TheLQ

+42

'package-info.java'可以包含[package]註解 - 它不一定是所有的API文檔。 – 2010-09-05 02:12:52

+46

我不會將package-info.java限定爲濫用類。它是一個java源文件（具有「.java」文件擴展名），但不是類文件，因爲它不包含類聲明。事實上，它不能包含類聲明，因爲「package-info」不是合法的類名。 – Scrubbie 2011-12-28 18:45:26

+18

使用package-info.java而不是package.html的另一個原因可能是.java並不意味着文檔的特定輸出格式。例如，您可能希望將Javadoc輸出爲LaTeX或PDF文件。根據javadoc編譯器的實現情況，這可能會導致.html案例中的問題。 – honeyp0t 2012-07-13 12:06:22

255

package-info.java：「此文件是在JDK 5.0新，並且優於package.html的。」 - javadoc - The Java API Documentation Generator

附錄：最大的區別似乎是註解包。在7.4 Package Declarations的基本原理中還有一點點。

附錄：註釋功能也被提及here和here。

附錄：另請參閱Declarative Programming in Java: Package-Level Annotations。

來源

2010-09-05 02:09:16 trashgod

爲什麼它的首選的任何特定原因？ – TheLQ 2010-09-05 02:24:18

@TheLQ：我猜測包註釋，因爲編譯器有更多的信息可以使用;更多上面 – trashgod 2010-09-05 02:49:00

包註釋對我來說是新的，並且看起來是package-info.java的一個很好的原因，因爲它的作用域 – stacker 2010-09-05 02:55:50

Javadoc：package.html或package-info.java

回答

相關問題