Главная » Java » Пример документированной версии класса в Java

0

 

  Следующий код представляет документированную версию класса Attr, рассмотренного в разделе 3.1:

/**

* Объект <code>Attr</code> определяет атрибут в виде пары

* <code>name/value</code>,   где <code>name</code> – объект типа

<code>Stri ng</code>,

* a <code>value</code>- произвольный объект <code>Object</code>.

*

* @version 1.1

* @author Plato

 *            ©since 1.0

*/

class Attr {

/** <code>name</code>- имя атрибута. */

 private final string name;

/** <code>value</code>- значение атрибута. */

 private object value = null;

/**

* создает новый атрибут с заданным именем <code>name</code>

* и исходным значением <code>value</code>,

                                              равным <code>null</code>.

 *            @see Attr#Attr(String,object)

*/

public Attr(String name) {

this.name = name;

}

/**

* Создает новый атрибут с заданными именем <code>name</code>.

* и исходным значением <code>value</code>.

 * @see Attr#Attr(String)

*/

public Attr(String name,  Object value)  {

this.name = name;

   this.value = value;

 }

/** Возвращает имя текущего объекта атрибута.   */

public String getName()   {

 return name;

/** Возвращает значение текущего объекта атрибута.   */

 public Object getvalueO  {

 return value;

/**

* Задает новое значение атрибута.

* значение будет возвращено при вызове {©link #getvalue}.

* @param newvalue  новое значение атрибута.

* @return  Исходное значение.

* @see #getvalue()

*/

public Object setvalue(Object newvalue) {

   object oldval = value;

value = newvalue;

 return oldval;

}

  /**

* возвращает строку вида <code>name=value</code>.

 public String toStringO {

   return name + "=’" + value + "’";

  }

}

 

ДЛЯ простых методов наподобие getName, единственное назначение которых состоит в возврате значения, описанного в комментарии к методу, тэг @return может быть опущен как явно избыточный. Аналогично, при документировании конструкторов не используются тэги @раram, поскольку смысл параметров ясен из основного комментария. В различных компаниях, как правило, приняты собственные соглашения, касающиеся того, что именно следует комментировать и с какой степенью полноты. На двух следующих иллюстрациях приведено содержимое файла HTML с описанием класса Attr (сведения о полях класса для краткости опущены), полученное в результате работы программы javadoc, B том виде, как оно выглядит в окне Web-броузера.

Посредством комментариев документирования, вообще говоря, следует описывать все члены класса или интерфейса, включая и те, которые обладают признаками доступа уровня пакета или обозначены как private. Генераторы документации, такие как javadoc, обычно предоставляют возможность выбора, позволяя включать в результат описания приватных членов либо нет. Добротным образом сформированная и удобочитаемая документация, относящаяся к особенностям внутренней организации типа, подчас бывает полезна не только его автору, но и тем, кто хотел бы поближе познакомиться с особенностями применяемых инструментальных средств.

  Упражнение 14.1. Снабдите комментариями документирования текст класса LinkedList, предложенного в виде упражнения 2.2 в разделе 2.1.2 на странице 59 и развиваемого по ходу изложения главы 2. Сгенерируйте документацию и попросите коллегу, тещу или прохожего воспользоваться вашим классом при написании небольшого приложения. Если пользователь не удовлетворен качеством документации, попробуйте исправить ее и вновь повторите процесс.

  Упражнение 14.2. Расширьте решение предыдущего упражнения, включив в документацию сведения о приватных членах класса. Создайте полную версию документации, охватывающую информацию об особенностях внутренней организации класса, и попросите тех же коллегу, тещу или прохожего подробно рассказать вам о назначении класса и всех его элементов. Если пользователь не пошлет вас подальше и согласится высказать собственные замечания, примите их к сведению и напишите улучшенный вариант комментариев.

 

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

По теме:

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