Правила оформления документации

Разработка документации
Оформление описания объектов (встроенных классов)


Разработка документации

Документация разрабатывается в reStructuredText формате (сокращенно ReST). Для написания документации в формате ReST достаточно изучить краткое описание.

Разработка документации ведется в отдельном проекте MSVS: Documents. У проекта две конфигурации: HTML и ALS.

Каждый разработчик сам пишет документацию на свои объекты, и согласовывает с руководителем проекта в какую часть общей документации будет входить документация по его разработке.

Компиляция документации


Компиляция документации

Установка программного обеспечения


Установка программного обеспечения

  • Установить Python: http://www.python.org (рекомендуется версия 2.4)

  • Установить Docutils: http://docutils.sourceforge.net/index.html (рекомендованная версия 0.4). Распаковать *.tgz архив, зайти в каталог Docutils, запустить:

    setup.py install

  • В VS Tools/Options закладка Directories, Show Directories for: Executable files прописать путь: <Каталог установки Docutils>\tools

После этого файлы проекта Documents можно компилировать как обычно это делается в VS.


Оформление описания объектов (встроенных классов)

В начале описания объекта размещается общая информация об объекте. Свойства, методы, события, конструкторы (создание через фабрику объектов) описываюстя в соответствующих подразделах. Формат описания объекта:

<РусскоеИмяВстроенногоКласса> / <АнглийскоеИмяВстроенногоКласса>
<Описание объекта>

Свойства
<Описание свойства> [ ...n]

Методы
<Описание метода> [ ...n]

События
<Описание события> [ ...n]

Конструкторы
<Описание конструктора> [ ...n]

Любой подраздел может отсутствовать.

Описание объекта
Описание свойства
Описание метода
Описание события
Описание конструктора


Описание объекта

Описание назначения и возможностей объекта.


Описание свойства

Заголовок описания свойства должен быть таким:

<РусскоеИмяСвойства> / <АнглийскоеИмяСвойства>

Описание свойства составляется из следующих секций:

Доступ: <Секция Доступ>.
Тип: <Секция Тип>.
Описание: <Секция Описание>.

Секции должны следовать в указанном порядке. Заголовки секций выделяются жирным шрифтом.

Секция Доступ
Секция Тип
Секция Описание


Секция Доступ

Содержит описание вида доступа к свойству. Присутствует всегда. Может содержать следующие варианты:

чтение и запись.
только чтение.
только запись.


Секция Тип

Содержит имя типа свойства. Присутствует всегда. Допускается указывать: Любой.


Секция Описание

Содержит описание свойства. Присутствует всегда.


Описание метода

Заголовок описания метода должен быть таким:

<РусскоеИмяМетода> / <АнглийскоеИмяМетода>

Описание метода составляется из следующих секций:

Синтаксис: <Секция Синтаксис>.
Параметры:
<Секция Параметры>.
Возвращает: <Секция Возвращает>.
Описание: <Секция Описание>.

Секции должны следовать в указанном порядке. Заголовки секций выделяются жирным шрифтом.

Секция Синтаксис
Секция Параметры
Секция Возвращает
Секция Описание


Секция Синтаксис

Содержит синтаксис вызова метода. Формат:

<РусскоеИмяМетода>([<ИмяПараметра> [, ...n]])

Присутствует всегда.

Если параметр не обязательный, то имя параметра должно быть заключено в квадратные скобки.


Секция Параметры

Должна быть представлена не нумерованным списком. Каждый элемент списка - описание параметра.

Формат описания параметра:

- <ИмяПараметра> - тип: <ИмяТипа> [, ...n]. <Описание параметра>;

Последний элемент списка заканчивается точкой. Если метод не имеет параметров - должна отсутствовать.

Если параметр не обязательный, в описании параметра указывается значение по умолчанию.


Секция Возвращает

Формат:

тип: <ИмяТипа> [, ...n]. <Описание возвращаемого значения>.

В случае если метод не возвращает значение (является процедурой) - должна отсутствовать.


Секция Описание

Содержит описание метода. Присутствует всегда.


Описание события

Формат описания события совпадает с форматом описания метода.


Описание конструктора

Заголовок описания конструктора может быть любым. Рекомендуется чтобы он пояснял назначение и функциональность данного конструктора.

Описание конструктора составляется из следующих секций:

Синтаксис: <Секция Синтаксис>.
Параметры:
<Секция Параметры>.
Описание: <Секция Описание>.

Секции должны следовать в указанном порядке. Заголовки секций выделяются жирным шрифтом.

Секция Синтаксис
Секция Параметры
Секция Описание


Секция Синтаксис

Формат должен совпадать с форматом одноименной секции из описания метода.


Секция Параметры

Формат должен совпадать с форматом одноименной секции из описания метода.


Секция Описание

Содержит описание конструктора. Присутствует всегда.