Документация разрабатывается в reStructuredText формате (сокращенно ReST). Для написания документации в формате ReST достаточно изучить краткое описание.
Разработка документации ведется в отдельном проекте MSVS: Documents. У проекта две конфигурации: HTML и ALS.
Каждый разработчик сам пишет документацию на свои объекты, и согласовывает с руководителем проекта в какую часть общей документации будет входить документация по его разработке.
Для добавления произвольных html-файлов к сборке 1С++ нужно не забыть добавить имена файлов в раздел "Учебник" в файле 1cpp.rst. Сами файлы нужно поместить в подкаталог kb. Для примера можно посмотреть подключение файла TSQLInV7FirstSteps
Установить 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]. <Описание возвращаемого значения>.
В случае если метод не возвращает значение (является процедурой) - должна отсутствовать.
Содержит описание метода. Присутствует всегда.
Формат описания события совпадает с форматом описания метода.
Заголовок описания конструктора может быть любым. Рекомендуется чтобы он пояснял назначение и функциональность данного конструктора.
Описание конструктора составляется из следующих секций:
Секции должны следовать в указанном порядке. Заголовки секций выделяются жирным шрифтом.
Формат должен совпадать с форматом одноименной секции из описания метода.
Формат должен совпадать с форматом одноименной секции из описания метода.
Содержит описание конструктора. Присутствует всегда.