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

Документирование программы выполняется утилитой VipDoc.exe. Данная утилита выбирает описания основных объектов программы и генерирует документацию. Список документируемых объектов включает в себя:

• типы данных;

• объектные интерфейсы;

• объекты (vip-интерфейсы);

• методы /свойства /объектные индексы;

• визуальные элементы (окна);

• базовые формы;

• присоединенные формы;

• потоки данных;

• меню;

• статус-строки;

• кнопки главного меню (деск);

• точки расширения.

Для методов можно комментировать каждый элемент (имя метода, параметры, возвращаемое значение) по отдельности, см. пример 2.

Дополнительно к информации, содержащейся непосредственно в операторах программы (типы данных, параметры методов и т.п.), в генерируемый документ можно включить произвольный текст. Текст, включаемый в документацию, задается директивой компилятора #doc. Описание объекта включается в документацию независимо от наличия директивы #doc для данного объекта.

Директиву #doc можно размещать только перед документируемым объектом.

<оператор-документирования> = #doc <документация> #end

<документация> - описание документируемого объекта в произвольной форме в формате HTML. Дополнительно к стандартным тэгам HTML можно использовать тэги <краткое-описание> и <перекрестная-ссылка>.

<краткое-описание> = [ <brief> ] <описание> </brief>

<brief> - начало краткого описания объекта. При отсутствии открывающего тэга <brief> краткое описание попадает в полное.

<описание> - текст краткого описания объекта. Используется для краткой характеристики объектов, входящих в описываемый объект. Например, краткое описание метода будет использовано при перечислении методов, входящих в описываемый интерфейс. А раздел документации, относящийся к данному методу, будет содержать его полное описание.

</brief> - конец краткого описания объекта.

<перекрестная-ссылка> = <адрес-ссылки> <описание-ссылки> </link>

<адрес-ссылки> - начало описания перекрестной ссылки, задает адрес ссылки:

<адрес-ссылки> = <link <тип-объекта> <идентификатор-объекта>
  [ <тип-элемента> [ <идентификатор-элемента> ]] >

<тип-объекта> - тип объекта ссылки:

<тип-объекта> = component | objInterface | interface | type
  | function | property | index | window | form
  | linkForm | dataStream | menu | statusLine
  | button | extensionPoint  | resourceFile

<идентификатор-объекта> - идентификатор объекта ссылки:

<идентификатор-объекта> = [<имя-файла>|][<ID-компонента>::]<ID-объекта>[.<ID-элемента>]

<имя-файла> - файл, содержащий откомпилированную документацию на заданную тему. Имя файла отделяется от имени объекта вертикальной чертой. Атрибут доступен начиная с Атлантис 5.2.10.

<тип-элемента> - тип элемента ссылки:

<тип-элемента> = field | index

Атрибут доступен начиная с Атлантис 5.2.09.

<идентификатор-элемента> - имя поля таблицы. Если указанный элемент не будет найден, произойдёт переход на начало страницы описания соответствующего объекта. Атрибут доступен начиная с Атлантис 5.2.09.

<описание-ссылки> - текст, описывающий ссылку в документации.

</link> - конец описания перекрестной ссылки.

Примеры тэга <перекрестная-ссылка>:

см.<link table x$files field xf$title>x$files.xf$title</link>
см.<link table x$files index FILEBYLOC2>x$files.filebyloc2</link>
см.<link Interface f_plpor.chm|F_PLPOR::PDocs>Interface PDocs</link>
см.<link Form f_buhrep.chm|Anal_Nam>Form Anal_Nam</link>

Пример

Пример 1.

#doc
  Это краткое описание, которое попадает в полное</brief> <br>
  Проверим ссылки: <link interface VVV>посмотри на интерфейс <b>VVV</b></link>.
#end

Пример 2. Документирование функции.

#doc
Функция проверяет наличие ресурсов у заданного владельца.</brief>
#end
  function IsEmpty(
#doc
NRec владельца ресурсов.
#end
				cMaster : comp
#doc
 <p>true  - у владельца нет ресурсов;
 <p>false - у владельца есть ресурсы.
#end
				) : boolean;

Версия

Начиная с Атлантис 5.2.10 имеется возможность указывать файл, содержащий откомпилированную документацию на заданную тему (элемент ссылки <имя-файла>).

Начиная с Атлантис 5.2.09 имеется возможность адресовать ссылку с точностью до элемента объекта (элементы ссылки <тип-элемента> и <идентификатор-элемента>).

Атлантис 5.2.07.