Действительно ли необходимо генерировать javadoc как часть процесса сборки? [закрытый]
8 ответов
Вовсе нет.
Если большинство пользователей вашего кода напрямую обращаются к файлам Java и используют IDE, то они, вероятно, уже читают свои JavaDocs через наведение курсора в редакторе кода. Это может быть более свежая версия, чем версия, которая проверена или собирается (если у вас нет непрерывных сборок).
Если вы предоставляете клиентам промежуточные версии (например, вы являетесь проектом с открытым исходным кодом), то предоставление JavaDocs, а не просто файлов классов, дополнительно привязывает вас к определенной семантике. Имеет смысл обеспечить более строгий контроль над вашим API, и ваши JavaDocs по существу описывают ваш API.
Если вы не хотите, чтобы кто-либо извне использовал ваши общедоступные интерфейсы (например, вы оставляете их открытыми для будущих плагинов), вы не можете предотвратить это, но вы, безусловно, можете избежать поощрения этого, предоставляя JavaDocs.
Если ваш процесс сборки использует Ant, я бы сказал, что это может быть не обязательно, но это не должно быть сложной задачей. Вы просто используете задачу javadoc, генерируете его, и на этом все.
Вы решаете, нужно это или нет. Лично я не создаю javadoc и другие тяжелые отчеты (создание которых немного дорого) при каждой сборке , я хочу, чтобы сборка выполнялась на машинах разработчиков и с помощью механизма непрерывной интеграции как можно быстрее (хотя механизм непрерывной интеграции создает и публикует файлы jar-файлов с исходным кодом). Формирование отчетов происходит во время ночной сборки.
Нужно ли создавать javadoc как часть процесса сборки?
Нет
На самом деле, ничто не заставляет вас делать это, но если вы хотите распространять свои артефакты сборки в виде пригодной для использования библиотеки, то, конечно, полезно иметь хорошо написанные Javadoc, которые люди могут просмотреть еще до того, как они скачают ваш JAR.
Нет. То, что вы решите делать в процессе сборки, зависит от вас (или от клиента). Некоторые системы сборки могут включать генерацию JavaDoc по умолчанию, но это должно быть просто отключить.
Вы не упоминаете, идет ли речь о сборке, скажем, веб-приложения или библиотеки для распространения. Как отметили другие авторы, это не так уж необходимо, но и для веб-приложения, поддерживаемого внутри, и для библиотеки, распространяемой извне, документация (в виде javadoc) будет чрезвычайно полезна.