Я участвую в проекте, в котором публичная документация по API является понятной. Чтобы убедиться, что выпуск соответствует этому требованию, я хотел бы убедиться, что цель выпуска в моем файле сборки Ant не выполнена, если охват документации слишком низкий.
Как минимум, каждый идентификатор с открытым или защищенным доступом должен иметь соответствующие теги Javadoc и описание. Например, публичные методы должны иметь тег @param для каждого параметра, тег @return, если тип возвращаемого значения не void, тег @throws для каждого исключения и описание в одну строку.
В настоящее время у меня есть отчеты о покрытии кода JUnit и условия сбоя с использованием Cobertura, поэтому что-то похожее на документацию было бы идеально. Однако, если обнаружение неисправного состояния недоступно, разумной заменой является отчет.
Документация должна быть в формате Javadoc. Никакой другой формат - включая Doxygen - не приемлем.