Boost не требует какой-либо конкретной структуры документации. Однако есть некоторые важные соображения, которые влияют на содержание и структуру. Например, многие библиотеки Boost предлагаются для включения в C++. Стандартные, поэтому их написание с текстом, подходящим для включения в стандарт, может быть полезным. Кроме того, к документации библиотеки Boost часто обращаются через Всемирную паутину, в том числе через поисковые системы, поэтому контекст часто важен для каждой страницы. Наконец, библиотеки Boost должны предоставлять дополнительную документацию, такую как вводный, учебный, примерный и рациональный контент. Имея это в виду, мы предлагаем следующие рекомендации по увеличению документации библиотеки.
Структура документации, необходимая для C++ Стандарт является эффективным способом описания технических характеристик библиотеки. Этот формат знаком многим пользователям Boost и гораздо точнее, чем большинство специальных форматов. Нижеследующее описание основано на подразделе 17.3 Стандарта. (Обратите внимание, что хотя окончательные предложения по стандарту должны включать полную стандартную формулировку, которую комитет не будет делать для вас, этот уровень детализации не ожидается от документации библиотеки Boost.)
Резюме представляет собой синопсис категории и вводит подзаголовки первого уровня. Каждый подзаголовок также содержит резюме, в котором перечислены заголовки, указанные в подзаголовке, и объекты библиотеки, представленные в каждом заголовке.
Пункты с пометкой "Примечание(ы):" или "Пример(ы):" являются информативными, другие пункты являются нормативными.
Резюме и подробные спецификации представлены в порядке:
Библиотеку можно расширить с помощью программы C++. Каждый пункт, в зависимости от обстоятельств, описывает требования, которым должны соответствовать такие расширения. Такие расширения, как правило, являются одним из следующих:
Шаблонные аргументы
Производные классы
Контейнеры, итераторы и/или алгоритмы, соответствующие стандарту интерфейса
Требования к интерфейсным конвенциям сформулированы как можно шире. Вместо того, чтобы констатировать, что «<class X>должно определить функцию<operator++()>члена», интерфейс требует «для любого объекта<x>из<class X>,<++x>определен». То есть, является ли оператор участником, не уточняется.
Требования формулируются в терминах четко определенных выражений, которые определяют действительные термины типов, удовлетворяющих требованиям. Для каждого набора требований существует таблица, которая определяет исходный набор действительных выражений и их семантику. Любой общий алгоритм, который использует требования, описывается в терминах допустимых выражений для его формальных параметров типа.
Требования к аргументам шаблона иногда упоминаются по имени.
В некоторых случаях семантические требования представлены в виде кода C++. Такой код предназначен как спецификация эквивалентности конструкции другой конструкции, а не обязательно как способ реализации конструкции.(2)
Postconditions: the observable
results established by the function
Returns: a description of the value(s)
returned by the function
Throws: any exceptions thrown by the
function, and the conditions that would cause the exception
Complexity: the time and/or space
complexity of the function
Rationale: the rationale for the
function's design or existence
Требования к сложности, указанные в библиотечных пунктах, являются верхними границами, а реализации, обеспечивающие лучшие гарантии сложности, удовлетворяют требованиям.
Описание функционального семантического элементавышевзято непосредственно из стандарта C++ и является довольно кратким. Вот более подробное объяснение каждого из элементов.
Обратите внимание на использование тега<<code> ... </code>>шрифта, чтобы отличить фактическое использование C++ от английской прозы.
Предпосылки для вызова функции, как правило, выражаются как предикаты. Наиболее распространенными предпосылками являются требования к значению аргументов, часто в виде выражений C++. Например,
void limit( int * p, int min, int max );
Requires:p != 0 && min <= max
Требования, уже применяемые правилами языка C++ (например, тип аргументов), не повторяются в пунктах Требований.
Действия, выполняемые функцией, описаны либо в прозе, либо в C++. Описание в прозе часто менее ограничивает реализаторов, но часто менее точно, чем код C++.
Если эффект указан в одном из других элементов, в частностипостусловий,возвратовилибросков, он также не описан в пунктеэффектов. Наличие только одного описания гарантирует наличие одной и только одной спецификации и, таким образом, исключает риск расхождения.
Наблюдаемые результаты функции, такие как значение переменных. Постусловия часто выражаются как предикаты, которые верны после завершения функции, в виде выражений C++. Например:
Определение сложности функции во времени и/или пространстве часто нежелательно, поскольку она чрезмерно ограничивает реализаторов и ее трудно правильно определить. Таким образом, сложность часто лучше оставить в качестве проблемы качества реализации.
Однако библиотечный компонент может стать непортативным, если между соответствующими реализациями существуют значительные различия в производительности. Контейнеры являются ярким примером. В этих случаях стоит указать сложность.
Определение обоснования дизайна или существования функции часто может дать пользователям представление о том, почему библиотека спроектирована именно так. Что еще более важно, это может помочь предотвратить «исправление» чего-то, что не было сломано по мере созревания библиотеки.
Web Reference Documentation
Доступ к документации библиотеки часто осуществляется через Всемирную паутину. С помощью поисковых систем можно просматривать страницу в глубине справочного контента без какого-либо дополнительного контекста. Поэтому полезно добавить дополнительный контекст, такой как следующее, на каждую страницу:
Describe the enclosing namespace or use fully scoped
identifiers.
Document required headers for each type or function.
Link to relevant tutorial information.
Link to related example code.
Include the library name.
Include navigation elements to the beginning of the
documentation.
Также полезно учитывать эффективность описания в поисковых системах. Терсовые или загадочные описания с меньшей вероятностью помогут любопытным найти соответствующую функцию или тип.
(1) To save
space, items that do not apply to a clause are omitted. For example, if a
clause does not specify any requirements, there will be no "Requirements"
subclause.
(2) Although
in some cases the code is unambiguously the optimum implementation.
(3) To save
space, items that do not apply to a class are omitted. For example, if a
class does not specify any comparison functions, there will be no
"Comparison functions" subclause.
(4) To save
space, items that do not apply to a function are omitted. For example, if
a function does not specify any precondition, there will be no "Requires"
paragraph.
Пересмотрено04 Декабря 200604
December, 2006[ORIG_END] -->
