Документирование бизнес-логики с использованием пользовательского тега в JavaDoc?

Question

Можно ли создать список заметок из пользовательского тега, используя JavaDoc? У меня есть бизнес-правила, которые я хочу пометить в коде, и он действительно не подпадает ни под один из известных мне тегов. Я полагаю, если был тег, который делал что-то похожее на:

@ note logic - в этом контейнере может быть только двенадцать виджетов

Это своего рода обратное документирование ограничений или требований, и я хотел бы задокументировать их, потому что они не обязательно были частью исходной спецификации. Одна из причин, по которой я хотел бы задокументировать это в исходном коде, заключается в том, что исходный код никогда не теряется, в то время как спецификации проекта, ну ... (не говоря уже о том, что никто их не читает)

Answer 1

Почему бы просто не поместить его в обычные комментарии Javadoc? В качестве объяснения краткого описания класса, метода и т. Д. Это вполне приемлемо, и именно так задокументирована большая часть самого JDK.

Если этого недостаточно для вас, возможно, вы можете создать собственный атрибут для пометки членов / методов / классов, тогда вы можете легко программно сканировать классы и найти все свои заметки.

@CustomNote("You can only have twelve widgets in this container")
public class WidgetContainer { 
    ...

Answer 2

XDoclet должен быть в состоянии настроить то, что вы хотите сделать.

Если вы используете Java 1.5+, вы можете использовать обычные аннотации и скомпилировать их в отчет. Здесь - инструкции. Это определенно проще, чем подход XDoclet.