]>

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

Содержание

- Разработка документации
  - Компиляция документации
    - Установка программного обеспечения
- Оформление описания объектов (встроенных классов)
  - Описание объекта
  - Описание свойства
    - Секция Доступ
    - Секция Тип
    - Секция Описание
  - Описание метода
    - Секция Синтаксис
    - Секция Параметры
    - Секция Возвращает
    - Секция Описание
  - Описание события
  - Описание конструктора
    - Секция Синтаксис
    - Секция Параметры
    - Секция Описание

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

Документация разрабатывается в 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]. <Описание возвращаемого значения>.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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