的Javadoc沒有HTML

Question

羅伯特C.馬丁的書Clean Code包含以下內容：

的HTML源代碼註釋是憎惡[...]如果評論是要通過一些工具來提取（喜歡的Javadoc）至出現在網頁中，那麼它應該是該工具的責任，而不是程序員，用適當的HTML來裝飾註釋。

我很同意 - 源代碼在沒有HTML標籤的情況下肯定會看起來更乾淨 - 但是如何製作體面看起來的Javadoc頁面呢？如果不使用HTML標籤，甚至無法分隔段落。 Javadoc manual說得很清楚：

doc評論是用HTML編寫的。

是否有一些預處理工具可以幫助您？ Markdown語法可能是適當的。

Answer 1

我同意。 （這也是我強烈反對C＃風格的「XML註釋塊」的原因; Javadoc DSL至少爲頂級實體提供了一些轉義！）。爲此目的，我只是不要儘量使javadoc看起來很漂亮...

...無論如何，你可能會對Doxygen感興趣。這是一個非常快速的帖子Doxygen versus Javadoc。它也帶來了你所做的事情:-)

Answer 2

HTML是什麼我想在「正常」的評論中看到。但是，對於像JavaDoc的工具，HTML增加的可能性增加格式化信息，要點等等

我會區分這兩種東西：

• 非javadoc的代碼註釋是程序員誰維護或增強了我的問題。他必須挖掘現有的源代碼，並且評論中的任何HTML都不會讓事情變得更簡單。所以，在正常的評論中禁止它。
• javadoc-comments用於生成文檔。在有幫助的地方使用HTML。但是HTML的一個非常有限的子集應該就足夠了。