Javadocs без HTML

Question

Книга Роберта К. Мартина Чистый код содержит следующее:

HTML в комментариях к исходному коду является мерзостью [...] Если комментарии будут извлеченыкакой-то инструмент (например, Javadoc) для отображения на веб-странице, поэтому ответственность за то, чтобы этот комментарий соответствовал HTML, должен быть не у программиста, а у этого инструмента.

Я согласен - источниккод наверняка выглядел бы чище без HTML-тегов - но как вы тогда создаете прилично выглядящие страницы Javadoc?Невозможно даже разделить абзацы без использования HTML-тега. Руководство по Javadoc ясно говорит:

Комментарий документа написан на HTML.

Существуют ли какие-нибудь инструменты препроцессора, которые могут помочь здесь? Уценка * Синтаксис может быть подходящим.

Answer 1

Я согласен.(Это также причина того, почему я категорически против "стиля блоков XML-комментариев" в стиле C #; Javadoc DSL по крайней мере обеспечивает некоторый экранирование для объектов верхнего уровня!).С этой целью я просто не пытаюсь сделать Javadoc красивым ...

... в любом случае, вас может заинтересовать Doxygen.Вот очень быстрый пост Doxygen против Javadoc .Это также поднимает вопросы, которые вы делаете: -)

Answer 2

HTML - это ничего, что я хотел бы видеть в «нормальных» комментариях. Но для таких инструментов, как JavaDoc, HTML добавляет возможность добавлять информацию о форматировании, маркеры и т. Д. ...

Я бы выделил эти две вещи:

• комментарии не-javadoc-кода предназначены для программиста, который поддерживает или улучшает код, который я задаю. он должен копаться в существующих источниках, и любой HTML в комментариях просто не облегчает ситуацию. Так что, бан в нормальных комментариях.
• javadoc-комментарии используются для генерации документации. Используйте HTML там, где это помогает. Но достаточно ограниченного подмножества HTML.