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

Содержание

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

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

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

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

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

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

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

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

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

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

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

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

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

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