reStructuredText (ReST) – язык разметки, предназначенный для документирования программ непосредственно в исходном коде.
Sphinx – генератор документации, преобразующий файлы в формате ReST в другие форматы (HTML, PDF, EPub и др.)
Модуль - набор алгоритмов, классов и других структур, имеющий имя, поставляемых как единое целое, объединенных общей целью и вариантом использования.
Следует разделять документацию модуля и документацию кода. Цель документирования модуля - описание структуры модуля, его вариантов использования, интерфейса взаимодействия с модулем. Цель документирования кода - описание внутренних структур модуля и алгоритмов.
Документирование модуля предназначено для ознакомления с предназначением модуля и его частей, особенностями его установки и использования. Именно на основании документации к модулю разработчик принимает решение о способе и варианте использования модуля.
Документирование кода является неотъемлемой частью разработки программных продуктов. Оно направлено на описание дополнительных аспектов того, что именно делает код.
Общие правила:
Документирование кода ведется с использованием генератора документации Sphinx и языка разметки reStructuredText.
Различаются два типа документирования:
Ручное документирование – в этом случае создается отдельный файл документации, в котором формируется текст в соответствии с языком разметки reStructuredText;
Документирование кода – в этом случае разработчик делает соответствующую разметку непосредственно в коде. После чего такая документация может использовать различными IDE или при автоматической сборке в режиме ручного документирования.
Обычно, документация к модулю состоит из следующих разделов:
Дополнительными разделами могут быть:
Из общего описания должно быть понятно предназначение модуля, его основные функции и состав. Можно описать варианты использования со ссылками на примеры из остальных пунктов.
В этом разделе могут быть описаны примеры использования при более тонкой настройке модуля, требующие более глубокого погружения в особенности работы модуля. Также могут быть примеры использования модуля в различных комбинациях настроек.
В этом разделе могут описываться все объекты и функции для обеспечения взаимодействия с модулем. Даются ссылки на автодокументацию по коду. Приводятся примеры и способы расширения и/или изменения функционала модуля.
В этом разделе описываются ответы на типичные вопросы, возникающие при использовании модуля. Также, рассматриваются возможные проблемы и способы их ршения (если это возможно). Рассматриваются возможные ошибки и их обработка.
В этом разделе могут содержаться любые иные сведения не описывающие использование модуля, но дополняющие его описание.
Каждый новый создаваемый модуль должен предваряться директивой:
#coding: utf-8
или
# -*- coding: utf-8 -*-
После которой в тройных кавычках идет аннотация к модулю. Аннотация может содержать в себе дату его создания, автора модуля, краткое резюме о предназначении модуля. Например:
""" Created on 12.05.13 :author: ivanov Описание моделей """
После строки определения класса должен следовать комментарий в тройных кавычках, о назначении этого класса.
class Account(BaseEnterpriseDictionaryModel): """ Модель плана счетов. """
После строки объявления функции (метода) должен следовать комментарий в тройных кавычках о назначении этой функции. Затем указывается перечень аргументов функции, их типов, возвращаемый результат, а также типы возможных исключений в функции. Описание функции и перечень аргументов необходимо разделять пустой строкой. Также пустой строкой отделяется перечень аргументов с их типами и перечень возвращаемых значений с типами возможных исключений.
Если описание элемента превышает в строке 79 символов, его необходимо перенести на новую строку с обязательным отступом.
Элементы синтаксиса документирования аргументов функций:
| Элемент | Назначение |
|---|---|
| :param [тип] имя: | Описание параметра функции |
| :type имя параметра: тип | Тип параметра |
| :return: | Описание возвращаемого результата |
| :rtype: | Тип возвращаемого результата |
| :raise: | Тип(ы) возможных исключений |
Если тип передаваемого параметра является встроенным типом языка Python, то он указывается с ключевым словом param. В противном случае, он указывается с ключевым словом type. Для возможности перехода к описанию типов программного продукта рекомендуется в параметре type указывать полный путь до типа, например:
web_bb.core.acc_chart.models.Account # для классов из ядра системы, web_bb.plugins.ack.models.Budget # для классов из плагинов.
Пример описания метода:
def create_doc(doc_model, operation, doc_params=None): """ Создание документа на основе полученных данных :param doc_model: класс модели документа :param operation: шаблон операции :type operation: web_bb.core.repos.models.DocumentOperations :param dict doc_params: словарь параметров, которые будут присвоены экземпляру документа :return: экземпляр на основе переданной модели документа :raise: KeyError """
Для переопределяемых методов в наследующих классах допустимо опускать описание только в случае, если описание присутствует в классе-родителе, и в методе потомка используется вызов такого же метода родителя.
Пример 1
Описание метода присутствует в классе-родителе, также используется вызов метода родителя с помощью ключевого слова super. Описание метода можно опустить
def get_rows(self, request, context, query_object): query_object.with_parents = True # "Соответствие капитальных вложений и счетов НМА" (НМАКапВл) # Заложено в фикстурах модуля acc_chart acc_group = 12 acc_list = get_equivalent_accounts_from_group(acc_group) query_object.filter = BE( 'id', BE.IN, acc_list) & query_object.filter return super(NMACapInvestAccChartPack, self).get_rows( request, context, query_object)
Пример 2
Полностью переопределяется метод родительского класса. Описание обязательно.
class MergeRecordsPack(RecordsPack): def validate_row(self, request, context, record, is_new): """Выключаем проверку базового класса """ pass
Документирование JavaScript-кода производится с использованием синтаксиса языка JSDoc. Строки документирования заключаются в секции /*…/. Все строки документирования помещаются перед определением параметров, функций, классов.
/** * Описание параметра, функции, класса и т.д. * * параметры, типы, возвращаемые результаты */
/** * Счетчик * @type {number} */ var i = 0; /** * Массив * @type {Array} */ var d = [];
С помощью ключевого слова type в фигурных скобках отражаем тип переменной.
/** * Проверяет какое-то условие * * @param а какой-то параметр * * @returns {boolean} */ function myFunction(a) { if (a) { return true; } else { return false; } }
С помощью ключевого слова param описываем аргументы функции. С помощью ключевого слова returns описываем возвращаемое значение. В фигурных скобках можно указать типы описываемых элементов.
/** * Создает экземпляр класса MyClass * * @param {number} x параметр x * @param {number} y параметр y * @this {MyClass} * @constructor */ function MyClass(x ,y) { this.x = x; this.y = y; }
С помощью ключевого слова constructor указываем, что данная функция является конструктором класса. С помощью ключевого слова this указываем, какого типа будет созданный объект.