.. Автор: Дмитрий Ощепков aka DmitrO, mailto: dmitro@russian.ru

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

.. contents:: **Содержание**

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

Документация разрабатывается в `reStructuredText 
<http://docutils.sourceforge.net/rst.html>`_ формате (сокращенно ReST). 
Для написания документации в формате ReST достаточно изучить
`краткое описание <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_.

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

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

.. __:

Секция Описание
---------------------------------------------------------------------
Содержит описание метода. Присутствует всегда. 

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

.. __: `Описание метода`_

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

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

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

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

.. __:

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

.. __:

Секция Параметры
---------------------------------------------------------------------
Формат должен совпадать с `форматом одноименной секции из описания 
метода`__.

.. __:

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

.. __: МетодСекцияСинтаксис_
.. __: МетодСекцияПараметры_
