Документирование кода

В языке Java используются блочные и однострочные комментарии /* */
и //, аналогичные комментариям, применяемым в C++. Введен также новый вид комментария /** */, который может содержать дескрипторы вида:

@author – задает сведения об авторе;

@version – задает номер версии класса;

@exception – задает имя класса исключения;

@param – описывает параметры, передаваемые методу;

@return – описывает тип, возвращаемый методом;

@deprecated – указывает, что метод устаревший и у него есть более совершенный аналог;

@since – с какой версии метод (член класса) присутствует;

@throws – описывает исключение, генерируемое методом;

@see – что следует посмотреть дополнительно.

Из java-файла, содержащего такие комментарии, соответствующая утилита javadoc.exe может извлекать информацию для документирования классов
и сохранения ее в виде HTML-документа.

В качестве примера можно рассмотреть снабженный комментариями слегка измененный класс User из предыдущей главы.

package chapt02;

public class User {

/**

* personal user’s code

*/

private int numericCode;

/**

* user’s password

*/

private String password;

/**

* see also chapter #3 "Classes"

*/

public User() {

password = "default";

}

/**

* @return the numericCode

* return the numericCode

*/

public int getNumericCode() {

return numericCode;

}

/**

* @param numericCode the numericCode to set

* parameter numericCode to set

*/

public void setNumericCode(int numericCode) {

this.numericCode = numericCode;

}

/**

* @return the password

* return the password

*/

public String getPassword() {

return password;

}

/**

* @param password the password to set

* parameter password to set

*/

public void setPassword(String password) {

this.password = password;

}

}

Сгенерированный для этого класса HTML-документ будет иметь вид:

clip_image002

Рис. 2.1. Фрагмент документации для класса User

Вы можете следить за любыми ответами на эту запись через RSS 2.0 ленту. Вы можете оставить ответ, или trackback с вашего собственного сайта.

Оставьте отзыв

XHTML: Вы можете использовать следующие теги: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

 
Rambler's Top100