Главная » Java » Документирование кода с помощью Комментариев Java

0

 

Любой член Общества, появляющийся (либо только намеревающийся появиться)

в пределах территории с собакой,

должен заплатить взнос в размере 10 фунтов стерлингов. Любое животное, выполняющее функции поводыря слепого человека,

может считаться котом.

Из комментариев к статье 46 Устава Общества Оксфордского университета

    Комментарии документирования (documentation comments), кратко называемые doc comments, позволяют включать информацию справочного характера, предназначенную для программистов-пользователей приложения, непосредственно в его код. Содержимое комментариев документирования может быть применено для создания документации, представляемой, как правило, в формате HTML.

   Комментарии документирования обычно невелики по объему. Справочная документация, получаемая на их основе, служит для описания контрактов интерфейсов, классов, конструкторов, методов и полей на уровне детализации, удовлетворяющем требованиям и пожеланиям большинства пользователей кода. Она, разумеется, отличается от полной документации — последняя слишком пространна и подробна, чтобы выполнять функции справочного руководства. В полной документации каждому методу зачастую посвящается несколько страниц убористого текста, а справочное руководство в этом случае ограничивается одним-двумя абзацами, а то и несколькими краткими предложениями. Полные спецификации создаются отдельно, но это не значит, что они не могут быть связаны со справочной документацией (о том, как создавать перекрестные ссылки, мы расскажем ниже).

Процедура  создания  документации  на  основе  комментариев  существенным

образом зависит от особенностей применяемой среды разработки приложений

Java. Один из наиболее употребительных способов получения документации связан с использованием команды javadoc, которой в качестве параметра передает-

ся наименование пакета или типа; документацию, генерируемую подобным образом нередко называют жаргонным словечком javadoc.

этой главе мы рассмотрим, из чего состоят комментарии документирования

 как интерпретируется их содержимое. Здесь мы затронем и вещи, которые, строго говоря, выходят за рамки языка Java как такового, но относятся к соглашениям,   регламентирующим  процедуры  автоматизированного  создания  документации

, в частности правила документирования пакетов и размещения файлов изображений и иных вспомогательных ресурсов. Вполне вероятно, что инструменту документирования из среды разработки Java, которой пользуетесь вы ,присущи некоторые особенности, отличающие его от javadoc, но если это и так, имеющаяся альтернатива наверняка окажется достойной.

 

Источник: Арнолд, Кен, Гослинг, Джеймс, Холмс, Дэвид. Язык программирования Java. 3-е изд .. : Пер. с англ. – М. : Издательский дом «Вильяме», 2001. – 624 с. : ил. – Парал. тит. англ.

По теме:

  • Комментарии