Лекция 15
Документирование программного кода
Документирование программного кода
Цели документирования:
Упростить поддержку кода
Снизить количество ошибок при модификации
Упростить взаимодействие между разработчиками
Документирование
Основные принципы
Документирование производится непосредственно в программном коде
Для составления документации используется генератор документации
Генераторы документации: Javadoc (1995) - Java
Robodoc (1995) – C,C++,Perl,Lisp,Cobol, etc… DoxyGen (1997) – C,C++,Java,C#,D, etc… Sandcastle (2008) - *.NET
Создание документирующего блока
Javadoc обрабатывает все «исходные» файлы, включающие:
Исходные файлы *.java Комментарии к пакетам Файлы с обзорными комментариями
Прочие необрабатываемые файлы (картинки, примеры кода, HTML файлы и т.п.)
Оформление комментария в исходных файлах
Комментарий обрамлен /** … */.
Блок документации предшествует классу, полю, методу и конструктору.
/** |
|
* Returns an Image object that can then be painted on the screen. |
|
* The url argument must specify an absolute {@link URL}. The name |
|
* argument is a specifier that is relative to the url argument. |
|
* <p> |
|
* This method always returns immediately, whether or not the |
|
* image exists. When this applet attempts to draw the image on |
|
* the screen, the data will be loaded. The graphics primitives |
|
* that draw the image will incrementally paint on the screen. |
|
* |
url an absolute URL giving the base location of the image |
* @param |
|
* @param |
name the location of the image, relative to the url argument |
* @return |
the image at the specified URL |
* @see |
Image |
Пример документирования |
|
|
метода |
*/ |
|
public Image getImage(URL url, String name) { |
|
|
try { |
|
return getImage(new URL(url, name)); |
|
} catch (MalformedURLException e) { |
} |
} return null; |
|
|
Правила оформления
Каждая строка комментария выровнена с исходным кодом
Первая строка начинается с /**
Каждая новая строка начинается с * (с 1.4 не обязательно)
Первое предложение комментария – краткое описание метода, что он делает.
Если в комментарии больше одного параграфа – разделять их необходимо HTML тегом <p>
Необходимо вставить пустую строку между описанием и тегами
Первая строка, начинающаяся с символа @ завершает описание.
Комментарий завершается символами */
Результат
Первое предложение
Первое предложение – краткое описание метода, конструктора или класса, которое будет отображено в таблице summary.
Первое предложение ограничивается первым символом точки.
Возможные проблемы:
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
Решение:
This is a simulation of Prof. Knuth's MIX computer.
Или
This is a simulation of Prof.<!-- --> Knuth's MIX computer.
Перегрузка методов
/**
* Class constructor. */
foo() {
...
}
/**
* Class constructor specifying number of objects to create. */
foo(int n) {
...
}
Теги (блоки тегов)
Описание тегов производится в следующем порядке:
@param (классы, интерфейсы, методы и конструкторы)
@return (только методы)
@exception (синоним @throws)
@author (только классы и интерфейсы)
@version (только классы и интерфейсы)
@see
@since
@serial
@deprecated
Если описание содержит несколько тегов одного типа
– они разделаются переводом строки