При документировании приложения необходима также поддержка документации программы. Если документация и код разделены, то непроизвольно создаются сложности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации при изменении программного кода.
Как правило, все существующие среды разработки IDE приложений Java предлагают решение по связыванию кода с документацией в процессе разработки с использованием javadoc. Для этого необходимо соответствующим образом написать комментарий к коду, т.е. документировать. Java комментарии необходимы как для комментирования программы, так и для составления или оформления документации.
Разработан специальный синтаксис для оформления документации в виде комментариев и инструмент для создания из комментариев документации. Этим инструментом является javadoc, который обрабатывая файл с исходным текстом программы, выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов, методов и полей. Таким образом, при минимальных усилиях создания комментариев к коду, можно получить хорошую документацию к программе.
javadoc — это генератор документации в HTML-формате из комментариев исходного кода Java и определяет стандарт для документирования классов Java. Для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения, javadoc также предоставляет API. В каждом случае комментарий должен находиться перед документируемым элементом.
При написании комментариев к кодам Java используют три типа комментариев :
С помощью утилиты javadoc, входящей в состав JDK, комментарий документации можно извлекать и помещать в НТМL файл. Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.
Дескрипторы javadoc, начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например , называются встроенными и могут применяться внутри описания.
Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.
Содержание
- javadoc дескрипторы : @author, @version, @since, @see, @param, @return
- Форма документирования кода
- Сценарии ant и javadoc
- Отмечен как дубликат участником pavlofff java Участники со знаками java могут единолично закрывать вопросы с меткой java как дубликаты, а также повторно открывать их при необходимости. 6 фев в 12:06 .
- Вендоры
- JUG(Java User Group) & OSUM(OpenSource University Meetup)
- Форумы
- javadoc дескрипторы : @author, @version, @since, @see, @param, @return
- Форма документирования кода
- Сценарии ant и javadoc
- Отмечен как дубликат участником pavlofff java Участники со знаками java могут единолично закрывать вопросы с меткой java как дубликаты, а также повторно открывать их при необходимости. 6 фев в 12:06 .
- Вендоры
- JUG(Java User Group) & OSUM(OpenSource University Meetup)
- Форумы
javadoc дескрипторы : @author, @version, @since, @see, @param, @return
Форма документирования кода
Документирование класса, метода или переменной начинается с комбинации символов /** , после которого следует тело комментариев; заканчивается комбинацией символов */.
В тело комментариев можно вставлять различные дескрипторы. Каждый дескриптор, начинающийся с символа ‘@’ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.
Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа «#» его метод или поле.
Среда разработки IDE, как правило, помогает программисту «подсветкой» встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.
Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы, для которого генерируется НТМL файл. Документация для каждого класса содержится в отдельном НТМL файле. Кроме этого, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL файлы.
Сценарии ant и javadoc
Для создания документации можно использовать ant.
Пример сценария (задания) ant для формирования документации к приложению MyProject :
Подробная информация формирования документации представлена на странице Javadoc/Javadoc2
На данный вопрос уже ответили:
Где можно найти грубо говоря русскую документацию Java? Если её нет. Или ресурсы хорошие на Java?
Отмечен как дубликат участником pavlofff java Участники со знаками java могут единолично закрывать вопросы с меткой java как дубликаты, а также повторно открывать их при необходимости. 6 фев в 12:06 .
Подобный вопрос задавали ранее и на него уже получен ответ. Если представленные ответы не являются исчерпывающими, пожалуйста, задайте новый вопрос.
В продолжение первой части. Сегодня будем рассматривать ресурсы о Java в интернете, которые подразделим на 4 части: вендоры, JUG, форумы, новости. А заодно подведём итоги.
Вендоры
Sun Microsystems
На сайте IBM есть раздел DeveloperWorks, в котором публикуются переводные обзорные статьи по таким новым технологиям, как Groovy, Scala, Guice, Spring, Eclipse, а так же по линейкам IBM: WebSphere, Rational.
JUG(Java User Group) & OSUM(OpenSource University Meetup)
Sun создал социальную сеть на основе Ning. В ней есть группы разных университетов, в которых обсуждаются различные OpenSource технологии Sun, в том числе и Java.
Форумы
Единственным популярным тематическим форумом я бы назвал JavaTalks. Так же есть подразделы по Java в других сообществах: SQL.ru, RSDN, Vingrad, Исходники.ру и LiveJournal.
Раньше были и другие популярные Java-проекты, содержащие разделы для обсуждения: JUGA, JavaPortal, Javable. Сейчас ими никто не пользуется.
Источник: