Javadoc - документирование исходного кода

Javadoc — стандартный генератор документации в HTML-формате из комментариев исходного кода.

Для создания описания к элементу(поле, класс, метод) используются специальный комментарий, расположенный выше этого элемента:
/** Описание */
Для документирования можно использовать дескрипторы, вот некоторые из них:
@author — автор
@version — версия
@since — указывает с какой версии появился этот блок кода
@see — ссылка на другое место в документации
@param — передаваемый параметр методу
@return — описание возвращаемого значения метода
@exception и @throws — описание исключений
@deprecated — документирование устаревших частей кода
{@link} — создание ссылки, можно вставлять в любое место
{@value} — описание значения переменной

Рассмотрим пример:

/** Класс служит для хранения объектов со свойствами
 * <b>maker</b> и <b>price</b>.
 * @autor Filippov Yakov
 * @version 1.0
*/
class Product{
	/** Свойство - производитель */
	private String maker;
	
	/** Свойство - цена */
	public double price;
	
	/** Создает новый пустой объект
	 * @see Product#Product(String, double)
	*/
	Product(){
		setMaker("");
		price=0;
	}
	
	/** Создает новый объект с заданными значениями
	 * @param maker - производитель
	 * @param price - цена
	 * @see Product#Product()
	*/
	Product(String maker,double price){
		this.setMaker(maker);
		this.price=price;
	}
	
	/** Функция для получения значения поля {@link Product#maker}
	 * @return Возвращает название производителя
	 */
	public String getMaker() {
		return maker;
	}

	public void setMaker(String maker) {
		this.maker = maker;
	}
}

Как видно, в документации можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и через символ "#" его метод или поле.
Вот пример использования ссылок для документирования перегруженного конструктора:

/** Создает новый объект с заданными значениями
* @param maker - производитель
* @param price - цена
* @see Product#Product()
*/

На выходе получаем:
Пример документации конструктора
Чтобы увидеть документацию в eclipse выделите элемент и нажмите F2.

0 комментариев

Только зарегистрированные и авторизованные пользователи могут оставлять комментарии.