Что такое документация к коду

Документация как код: шесть принципов программирования, которые помогут создавать документы, понятные каждому

Авторизуйтесь

Документация как код: шесть принципов программирования, которые помогут создавать документы, понятные каждому

Рассказывает Дмитрий Толоконников, бизнес-аналитик департамента ИТ-аутсорсинга ALP Group

Больше пяти лет я занимаюсь бизнес-процессами. В особенности процессами технической поддержки, которую мы оказываем коммерческим и государственным компаниям. Например, я слежу, чтобы уровень качества IT-обслуживания соответствовал международным стандартам. Я программирую и работаю с документацией — пишу регламенты и процедуры, описываю процессы, выпускаю инструкции.

Всё это время я неосознанно «перетаскиваю» общие принципы программирования в работу с документами. Это помогает мне не делать бесполезные «спагетти-простыни» и писать внятные рабочие документы с ясной структурой, даже если документация очень объёмная и должна часто меняться в соответствии с изменениями в компании и все её части должны быть связаны воедино, чётко объяснять, как что-то работает. Возможно, мои приёмы помогут и вам.

Принципы работы с текстом

DRY — Don’t repeat yourself. Не повторяйся

Если вы вставили один и тот же блок в 10 разных регламентов и что-то меняете в нём, то у вас образуется 10 одинаковых мест, куда нужно внести одинаковые изменения. Вероятность забыть об этом тоже растёт, даже если вы пользуетесь бессмертным «Ctrl+C» — «Ctrl+V». Особенно в последней паре документов.

В программировании такие блоки выделяют в отдельные функции, классы, а в работе с документами повторяющиеся элементы нужно выносить в отдельные разделы или документы и давать ссылки на них.

KISS — Keep it simple, stupid. Не усложняй

Посмотрите вокруг: люди привыкли к простоте. Интуитивно понятные интерфейсы и всплывающие подсказки в приложениях. Принцип одного окна в IT-обслуживании. Засилье коротких статей и обучающих видео в Интернете. Той же простоты они ждут и от рабочих документов.

4 декабря, Онлайн, Беcплатно

Этот принцип я обычно использую как маркер. Если описание процесса слишком сложное — нужно упростить процесс. Если инструкция к приложению слишком замысловатая — надо доработать приложение.

Обычно это проще и дешевле, чем писать сложную документацию, заставлять каждого нового сотрудника её читать, понимать и учиться действовать по ней. А ведь потом ещё нужно будет вносить изменения в документацию.

YAGNI — You ain’t gonna need it. Тебе это не понадобится

Это продолжение принципа KISS. Обычно я применяю его, когда собираюсь создать универсальное решение с заделом на будущее. Проблема в том, что такое решение — само по себе усложнение. Не факт, что в будущем оно понадобится. Обычно нет смысла создавать всеобъемлющее описание бизнес-процессов направления, которое только сформировалось и активно развивается. Практика показывает, что будущее внесёт серьёзные коррективы.

Но здесь важно разумно подходить к вопросу. Есть вещи, изменение которых дорого обходится. Их как раз нужно готовить с заделом на будущее. В программировании эту работу относят к архитектуре приложения, а в документации просто сразу говорят: «Это нам не понадобится». И в будущем с трудом навёрстывают упущенное.

Принципы работы со структурой

Чем объёмнее становится документация, тем сложнее поддерживать её актуальность. Изменение одного документа влечёт за собой каскадное изменение остальных, логическая целостность ломается, структура требует очередной переработки. К счастью, для программирования это стандартная проблема, и за прошедшие десятилетия выработались общие принципы написания легко поддерживаемого кода. Часть из них можно применять и к документам.

SRP — Single Responsibility Principle. Принцип единственной ответственности

Яркий маркер нарушения принципа — наличие побочных действий. Например, метод класса отвечает за отправку клиенту уведомления о новом заказе в интернет-магазине, но при этом ещё и обновляет текущий баланс клиента.

То же самое справедливо и для документации. Например, в регламент регистрации обращения клиента не нужно впихивать что-то «заодно»: принципы вежливого общения с клиентами, краткое описание self-service портала и т. д.

Нельзя рассчитывать, что такая информация будет усвоена или сотрудники запомнят, к какому документу нужно обращаться, чтобы её получить. Зато это запутывает документ, лишает структуру чёткости и требует дополнительного времени для актуализации. Если вы действительно хотите напомнить о вежливости при общении с клиентом, вставьте в регламент ссылку на соответствующий документ (вспомните о DRY).

Соблюдение принципа позволяет делать документы короче. Их название соответствует назначению, а чтение не вызывает неприятных сюрпризов. Их проще прочитать за раз. И не забыть, с чего документ начинался.

SLAP — Single Level of Abstraction Principle. Принцип единого уровня абстракции

Является логичным продолжением принципа единственной ответственности (SRP).

Применение принципов KISS и SRP побуждает писать небольшие, простые и понятные документы. Но эти документы нужно собрать в такую же простую и понятную структуру. Здесь помогает выделение и соблюдение уровней абстракций.

Например, очевидно, что нет смысла пытаться поместить в один огромный документ объёмную документацию вроде описания системы менеджмента качества. Намного логичнее разбить его на уровни абстракций и сделать для каждого уровня разные документы — верхнеуровневое описание системы, описание каждого процесса и т. д.

При этом важно соблюдать принцип единого уровня абстракций и относить информацию только к нужному уровню. Если вы пишете верхнеуровневое описание, не надо вдаваться в детали работы конкретного процесса. Не тот уровень абстракции! Оставьте эту информацию для описания процесса. Этот принцип дополняет SRP, заставляя автора контролировать не только то, за что отвечает документ, но и на каком уровне в иерархии он находится.

LoD — Law of Demeter (Don’t talk to strangers). Закон Деметры (Не разговаривай с незнакомцами)

Если применить закон к документации, то каждый документ:

Например, процесс управления IT-инцидентами взаимодействует с процессом управления проблемами напрямую, а с процессом управления изменениями — только через управление проблемами. Тогда в описании управления инцидентами можно ссылаться на описание управления проблемами. А вот ссылаться на описание управления изменениями не надо.

Итого

Указанные выше принципы сильно помогают мне при написании документации по процессам, в создании регламентов, процедур и инструкций. К сожалению, это лишь небольшая часть рекомендаций по управлению качеством кода, поэтому заинтересовавшимся рекомендую самостоятельно углубиться в тему. Из неё можно извлечь много полезного. При этом важно помнить, что эти принципы не являются законами. В Интернете много спорят об их правильном использовании и часто злоупотребляют ими. Поэтому, пожалуйста, не впадайте в крайности. И не забывайте о здравом смысле.

Источник

Как сделать документацию к коду?

Простой 3 комментария

Есть две крайности, которых лучше избегать:
1. красивая и исчерпывающая документация требует колоссальных ресурсов на поддержку
2. сложно воспринимаемый код, без малейших подсказок с чего все начинается и чем заканчивается

Кстати, проектная работа, это не только документация к коду, это еще и свод правил, которые позволят архитектуре не расползтись кто в лес кто по дрова, а также сохранят стилистику написания кода для единообразия и легкой поддерживаемости кода.

Думаю, вышеописанные пукнты не вяжутся с JS, хоть и прекрасно работают в других средах (php, java etc).

На JS вообще очень сложно писать «правильно» и «хорошо»))

Согласен, JSDOC, юнит тесты и автоматическая документация прекрасно работают в JS, но это, имхо, вообще не тот язык, который следует использовать в таких приложениях.

На счет 2007-го, а разве в JS уже появилась статическая типизация, интерфейсы, приватные свойства?))

Да и в сто раз проще написать hhvm совместимый код на PHP+фрейме ежели использовать его. Выйдет и быстрее, и проще, и лучше.

Источник

Пять стратегий документирования кода

В этом разделе мы рассмотрим подходы к фактическому документированию кода. Существует несколько подходов, которыми пользуются писатели и инженеры, мы познакомимся с пятью из них с примерами и комментариями.

После прочтения вступления к модулю “Документирование кода” одна из читательниц поделилась своим подходом. Вот, что она написала:

Кажется, такое разделение и расположение комментариев кода имеет место быть. Можно разделять пояснения на две основные категории:

После разделения, пояснения Как? встраиваются в код в виде комментариев (примерно на каждые 5-10 строк). Пояснения Почему? встраиваются во внешних разделах до или после кода. Разумеется, в пояснениях Как? можно получить подробную информацию о Почему? причинах, и наоборот, поэтому разделение этих двух вопросов на практике может быть не таким простым. Но такая общая закономерность, скорее всего, верна.

Кроме того, такой подход интересен тем, что он побуждает подумать над вопросом Почему?. Техническим писателям, документирующим код (который пишут другие), не всегда получается учитывать Почему?.Иногда бывает трудно понять, какие вопросы Почему? существуют. Зачем использовать этот класс вместо другого? Почему так, а не так? Часто существует много разных способов достижения цели, так почему же идти по этому пути, а не каким-то другим?

В общении с разработчиками о примерах кода, стоит задавать это вопрос: Почему?

Подход 2: сопоставление комментариев в третьей колонке

Лучшие практики для документации в целом (не только для документирования кода) включают размещение полезных инструкций рядом с областью, вызывающей затруднения, что в контексте документирования кода может означать добавление встроенных комментариев, пронизывающих весь код. Но предположим, что нужен большой комментарий о том, что происходит в коде (поскольку уровень сложности не может быть передан в коротком комментарии). Как сопоставить длинную концептуальную / пояснительную информацию с кодом?

Если ваш комментарий больше кода, есть риск сделать код нечитаемым. Если разместить комментарий в разделах, которые идут задолго до или после кода, есть риск создать пропасть между объяснением и кодом, так что читатели не будут знать, к каким частям кода относится объяснение.

Документация Twilio, с третьей колонкой для кода

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

Некоторые экраны Twilio фактически “размывают” нерелевантный код, позволяя сосредоточить свое внимание на линиях, сформулированных в концептуальной области, например:

Размытие нерелевантного кода

Одной из проблем такого подхода является пространство экрана. Чтобы добавить третью колонку, нужно занять весь экран без полей. (Странно, что в Twilio нет возможности свернуть левую панель навигации, освободив тем самым больше места для кода.)

Таким образом, код виден только частично. Код можно растянуть по горизонтали с возможностью прокрутки вправо, но, несомненно, дизайнерам тяжело дался пользовательский интерфейс, который включает в себя горизонтальную и вертикальную прокрутку.

Вдобавок, реализация размытия фокуса области экрана с кодом, на описании которого находится пользователь, должна быть технически сложной и громоздкой.

Другая проблема заключается в том, что код и пояснения к нему редко можно выровнять линейно. Предположим, есть метод в коде, который занимает всего одну строку, но описание этого метода занимает три длинных параграфа концептуального объяснения. К тому времени, когда пользователь достигает нижней части концептуального объяснения, код уже не виден. Пользователю приходится сделать много лишних манипуляций, чтобы найти соответствующий код. Дизайн пользовательского интерфейса для размещения всех этих движущихся частей не только кажется сложным, но и увеличивает нагрузку на пользователя.

Еще одна проблема, связанная с таким дизайном, заключается в том, что код часто относится к нескольким файлам. Отображение в колонке не указывает, отображается ли весь код в одном и том же файле Java или мы видим код из нескольких файлов Java. Представление вкладок в столбце кода требует еще более сложного формата документации. Сложно представить, что все это возможно сделать с помощью синтаксиса Markdown.

Подход 3: подход Лего

Другой подход заключается в создании кода с нуля, уровня за уровнем, который можно назвать “подходом Лего”. В качестве примера подхода Лего можно посмотреть на пример в eBay Shopping API Поиск по продавцу: Просмотр информации о продавце.

Подход Лего показан в API eBay Shopping

У них в руководстве всего 5 шагов:

Проблема с подходом Лего заключается в том, что технический писатель вряд ли воссоздаст логику построения, которой следовал разработчик. Скорее всего, разработчики просто отправят готовый кусок кода в документ, и тогда придется получать пояснения от разработчика о коде, как описано в разделе Почему так трудно документировать код?, где описаны основные проблемы.

Несмотря на проблемы с подходом Лего, если нужно научить кого-то, как понимать код, нужно начать с простого и идти шаг за шагом от простого к сложному. Следующая техника объясняет такой подход от простого к сложному при помощи метафоры наутилуса.

Подход 4: подход Наутилус

Подход Наутилус аналогичен подходу Лего, но вместо того, чтобы описывать куски работы, которые выполняются один за другим в порядке сборки, здесь описываются основные простые шаблоны, которые должны знать пользователи. Начинается с самого простого кода, а затем проект увеличиваться и увеличиваться по мере необходимости, как растущая спиральная структура оболочки наутилуса.

Пол Густафсон, управляющий компанией, занимающейся техническим обслуживанием письма, в Bay Area, которая называется Экспертная поддержка, представляет подход с метафорой Наутилуса, описанный здесь. Пол говорит, что наутилус является хорошей метафорой для технической коммуникации, потому что наутилус представляет спиральную схему (последовательность Фибоначчи), которая начинает с малого и постепенно растет по мере необходимости:

Следуя подходу Наутилус, мы начинаем с простых базовых шаблонов, а затем постепенно наращиваем объем кода вокруг него по мере необходимости. Мы не начинаем с описания сложной законченной работы с самого начала. Законченная работа, вероятно, включает в себя все виды абстракций кода и перестановки для чистого, готового продукта.

Проблема в том, что мы часто хотим объяснить, как работает готовый код, проводя пользователя через все от начала до конца. У нас может быть 500 строк кода, которые мы хотим сформулировать, но подход Nautilus заставил бы нас объяснить только несколько небольших фрагментов этого кода (по крайней мере, для начала). Следовательно, существует проблема типа A-против-Z: мы описываем A (самый простой шаблон ядра), но конечным продуктом является Z. Как именно мы добираемся от A до Z? Как мы придем от простых шаблонов, которые могут занимать 20 строк кода, до чудовищно сложного, законченного кода, который занимает 500 строк?

Для технического писателя, смотрящего на окончательный код, нет ясного понимания того, как разработчик попал туда. Мы часто не можем отделить подобную логику, с которой начинал разработчик, что привело его к этой более сложной цели. Все, что мы видим, это этот сложный конец. Как декомпилировать код, чтобы восстановить логику, с которой разработчик начал? Как понять, что это были за начальные паттерны, которые положили начало всему процессу? Если вы не разрабатывали код и не являетесь разработчиком, то будет практически невозможно восстановить шаблон Наутилуса, стоящий за кодом.

Как задокументировать процесс создания картины?

Чтобы задокументировать процесс создания такой картины, что лучше: начать с верха и идти к низу? Нет, это было бы смешно. Скорее всего, лучше начинать с создания овала головы. Потом, несколько общих набросков для глаз и так далее. Может быть, набросать линии перспективы и другую основную структуру. Никто сразу не приступает к цветам, освещению и теням, верно? То же самое с кодом. Начинаем с основы, а затем прокладываем путь к большему количеству завершающих деталей.

Чтобы проиллюстрировать этот момент более четко, приведем пример кода. Автор курса не инженер, но ему удобно работать с Jekyll и темами, он создал шаблон, который будет принимать экспорт контента из инструмента для создания тикетов (например, JIRA) и отображать его в виде отчета документации на веб-странице.

Финальный шаблон выглядит так:

Этот код выглядит как бред, правда. Здесь есть несколько инклюдов, в которых абстрагирована логика, потому что они будут повторяться ее из отчета в отчет. Здесь убраны скрипты и стили, так как они загромождают код, поэтому они хранятся во включаемых файлах.

Представьте, что вы пытаетесь задокументировать этот код. Если бы вы начали сверху и дошли до конца, это было бы настоящим беспорядком. Пользователю также будет трудно читать длинное объяснение. Такой запутанный клубок. И он не распутается, если поспешно собрать все, не задумываясь о чистом, элегантном решении. Нужно было быстро выпустить отчет, поэтому шаблон был взломан как можно быстрее. Разработчики, создающие приложения, часто внедряют подобные хаки и другие костыли, используя скотч и WD-40, как говорит Джоэл Спольски, чтобы получить рабочее решение, поставленное в срок.

Даже этот кусок сбивает с толку, поскольку есть странные вещи с переменными, вставленными в скобки в ссылках на файл YAML.

Чтобы по-настоящему объединить код с основной логикой, разработчики должны начать с этого:

Чтобы собрать эту информацию, нужно взять интервью у разработчика. И при общении с разработчиком, нужно понимать его язык и объяснения. В качестве альтернативы можно попросить разработчика описать логику собственного кода с помощью руководства с правильными вопросами. Например, можно спросить:

Подход 5: Интерактивный браузер

Изучение основных шаблонов смещает документацию в область руководства. С этим типом обучения связан интерактивный браузер, в котором действие сочетается с обучением. Интерфейсы, выполняемые браузером, имеют своей целью помочь пользователям лучше понять результаты входных и выходных данных, чтобы пользователи могли сами убедиться в том, как работает код, используя более практичный для себя подход.

Кнопка Try it out в интерфейсе Swagger

Swagger предлагает оригинальное сочетание документации с активным взаимодействием, которые помогают пользователям изучать API (читая и выполняя). Но выполнение запросов с помощью конечных точек API REST обычно довольно простое. Более интенсивные руководства по коду будет сложнее сделать интерактивными в браузере. Тем не менее, некоторые «Notebooks» (как их часто называют) позволяют запускать код, в частности Jupyter Notebooks. Описание Jupyter:

У Google есть несколько вариантов блокнота для совместной работы с документацией TensorFlow, в которой есть операции, которые можно выполнять на веб-страницах. На следующем скриншоте можно увидеть опцию Run code now :

Интерактивный пример кода от TensorFlow

Клик на Run code now открывает интерактивную записную книжку Google, которая фактически запускает код в браузере:

Интерактивный блокнот Google позволяет запускать код в браузере

Хотя интерактивные записные книжки выглядят круто, они кажутся огромной работой для чего-то, что может быть легко достигнуто с помощью образца приложения. Вместо того, чтобы выяснить, как вы можете скомпилировать код Python или другой язык в браузере, почему бы просто не предоставить пример приложения, которое пользователи могут загрузить, а затем выполнить локально, используя свои собственные инструменты компиляции и настройки?

Заключение

В этом разделе мы рассмотрели 5 подходов документирования кода:

Лучше использовать подход, который помогает пользователям получить нужные знания для создания собственного кода.

👨‍💻 Практическое занятие: сравниваем документацию кода с одним из подходов

Ищем раздел с руководством по коду на одном из сайтов документации API, которые изучали. Или посмотрите на один из сайтов документации API в этом посте от Nordic APIs: 5 Примерjd отличной документации API (и почему мы так думаем). В этом посте перечислены пять примеров документации API: Stripe, Twilio, Dropbox, GitHub и Twitter.

И попробуем выяснить, какому подходу лучше всего соответствует документация кода.

Источник

Документирование кода

Doxygen — это система генерации документации. В Друпале, документирование функций, классов, констант и так далее, делается с помощью специально оформленных комментариев. Документация извлекается прямо из исходного кода, что делает более удобным хранение документации вместе с исходным кодом. На сайте Doxygen находится замечательное руководство по этой системе. Следующие рекомендации имеют отношению к работе с Doxygen в Друпале.

Общие правила

Эти стандартны применяются как к внутристрочным, так и к вынесенным комментариям:

Внутристрочное комментирование

Приветствуется использование внутристрочных и невынесенных комментариев общего характера. Общее правило их использования: если вы смотрите на код и думаете про себя «Ого! Я даже не хочу попробовать это описать», — вам нужно обязательно это описать, пока вы не забыли как это работает.

Комментарий должен идти перед строкой или блоком кода к которому он относиться и не должен отделяться от него пустой строкой, например:

В случае, если комментирование требуется для каждой строки кода и используются внутристрочные комментарии, для их выравнивания могут использоваться пробелы — это улучшает чтение.

Используйте комментирование в стиле C (/* */) или в стиле C++ (//). Комментирование в стиле Perl/shell (#) не приветствуется.

Общий синтаксис надстрочных комментариев

Чтобы документировать блок определённого кода, например, функции, класса, метода, константу и так далее, используется следующий синтаксис:

Doxygen поймёт любые комментарии расположенные в таком блоке. Ваш стиль должен содержать по возможности команды стандартные для Doxygen, таким образом, мы сохраняем источник разборчивым. Любые упоминания функций или названий файлов в документации автоматически создадут ссылки на тот код, на который они ссылаются. Блок с документацией должен идти перед описываемым кодом, без пустых строк между блоком и кодом.

Директивы Doxygen — общие замечания

Списки

В Doxygen, списки могут находиться где угодно. Парсер документации требует строгого следования синтаксису, чтобы текст мог быть корректно выведен в HTML-формате:

Секция «Смотрите также»

The @see directive may be used to link to (existing) functions, files, classes, methods, constants, groups/topics, URLs, etc. @see directives should always be placed on their own line, and generally at the bottom of the documentation header. Use the same format in @see that you would for automatic links (see below, or see examples above). In addition, you can link to a group/topic using the internal name of the group (what follows the @defgroup in its definition).

Ссылки

The @link. @endlink directive may be used to output a HTML link in line with the text. Some notes:

Автоматические ссылки

Any function, file, constant, class, etc. in the documentation will automatically be linked to the page where that item is documented (assuming that item has a doxygen header). For functions and methods, you must include () after the function/method name to get the link. For files, just put the file name in (not the path to the file). Groups will not be automatically linked; use @see or @link.

Образцы кода

Примеры кода могут быть встроены в документацию Doxygen с использованием директив @code и @endcode. Любой код между этими директивами будет выводиться отформатированным.

Планируемые изменения

To document known issues and development tasks in code, @todo statements may be used. Notes:

@todo statements in inline comments follow the same rules as above, especially regarding indentation of subsequent comments, but you don’t need to leave a blank line between other comments and the @todo line.

Документирование файлов

Каждый файл должен начинаться с комментария, который описывает то, что он делает. Пример:

Note that a blank line should follow a @file documentation block.

Строка, которая идёт сразу за директивой @file, это описание, которое показывается на странице со списком всех файлов. Если строка начинается с глагола, то он должен быть в настоящем времени, например, «Обрабатывает загрузку файлов». Описание, которое не нужно добавлять на страницу со списком всех файлов, должно идти после пустой строки.

Вообще, директива @file не должна содержать подробного описания, которое лучше поместить в директиву @defgroup. Таким образом, разработчики смогут просматривать документацию верхнего уровня, пользуясь группами (смотрите список тем/групп API ядра на странице http://api.drupal.org/api/drupal/groups).

Для файлов содержащих определение только одного класса, используйте шаблон:

Документирование функций и методов

Все функции и методы должны быть документированы. Блок комментирования функции должен ей непосредственно предшествовать.

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

If there is no return value, omit the @return directive entirely. Краткая форма Functions that are easily described in one line may use the function summary only, for example:

If the abbreviated syntax is used, the parameters and return value must be described within the one-line summary. Data types on param/return Note: This section of the standard was adopted as of Drupal 8. In previous versions, data type specification was recommended in the case of non-obvious types or specific classes/interfaces only.

The data type of a parameter or return value MUST be specified in @param or @return directives, if it is not obvious or of a specific class or interface type.

The data type MAY be specified (as in: recommended) for other @param or @return directives, including those with primitive data types, arrays, and generic objects (stdClass).

This line should indicate which PHP or Drupal function directly takes this callback as an argument, and also which Drupal API function calls that function. If multiple API functions call it, format as a list.

Note that there are also specific standards for some functions that might be considered callbacks, such as hook implementations, menu callbacks, and form callbacks.

Документирование определений хуков

Документирование определения хука следует тем же правилам, что и документирование обычных функций (смотрите выше) за исключением того, что в первой строке используется глагол в повелительном наклонении. Кроме того, приводится пример содержания функции, обычно из реализации хука в модуле ядра. Также полезно упомянуть откуда вызывается хук.

Documenting hook implementations and theme preprocess functions

If the implementation of a hook is rather standard and does not require more explanation than the hook reference provides, a shorthand documentation form may be used in place of the full function documentation block described above:

This generates a link to the hook reference, reminds the developer that this is a hook implementation, and avoids having to document parameters and return values that are the same for every implementation of the hook.

In the case of hooks that have variables in the names, such as hook_form_FORM_ID_alter(), a slightly expanded syntax should be used:

This generates a link to the hook reference, as well as to the particular form that is being altered. Again, optionally you can add more information in a separate paragraph to describe the particular quirks of your hook implementation.

Theme preprocess functions work the same as hook_form_FORM_ID_alter(). Example:

For hook_update_N() implementations, there is a different standard, because the documentation’s first line is displayed to tell people what will happen (or did happen) when update.php is run. So they are documented as follows:

Note that the first line should start with an imperative verb, so it will make sense to people running update.php.

Документирование функций генерирующих формы

/**
* Form validation handler for user_login_form().
*
* @see user_login_form_submit()
*/
function user_login_form_validate($form, &$form_state) <
.
>

/**
* Form submission handler for user_login_form().
*
* @see user_login_form_validate()
*/
function user_login_form_submit($form, &$form_state) <
.
>

If the form generates a page (i.e., in a hook_menu() implementation, the page callback is ‘drupal_get_form’ and the page argument is this form), include an @see reference to the hook_menu() implementation that uses it.

Documenting Render API callbacks

The Render API uses various callbacks functions, which you can assign to a render element when setting up a render array (or a form). Document them as follows:

Этот блок добавлен для Друпала 8.

Документирование функций темизации

In order to provide a quick reference for themers, we tag all themeable functions so that Doxygen can group them together. A themeable function is defined as any function meant to be called via theme(), and you can indicate that a function is themeable by adding an @ingroup themeable directive. It is also beneficial to use @see directives to link the theme function with its preprocessing functions.

In the rare case that your theme function returns some other type of formatted output other than HTML, you should add a @return directive with a description of what the function generates and returns.

See also the hook implementations section for how to document preprocess functions.

Документирование шаблонов тем

If a template file (themeablename.tpl.php) and a preprocess function is used instead of a theming function, both the template file and the preprocessing function need to be documented. The template file should be documented with a @file directive, should have @ingroup themeable in the file documentation header, and should contain a list of the variables that the template_preprocess_HOOK has prepared for it. If any of these variables contain data that is unsafe to output for XSS reasons, that should be documented; otherwise it can be assumed that variables available have already been appropriately filtered. Anything not listed should not be assumed to be safe to output. It should also contain a @see directive to link back to the preprocessing function.

See also the hook implementations section for how to document preprocess functions.

Documenting hook_menu() callbacks

(This standard was adopted for Drupal version 8.x.) The page, access, title, and other callbacks that are registered in hook_menu() are documented as follows:

Документирование констант и переменных

Constants, global variables, and member variables of classes should have documentation blocks. As usual, the documentation block should start with a one-line description, and any additional needed documentation should be separated from the summary line by a blank line (though usually only one line is needed).

Документирование классов и интерфейсов

Each class and interface should have a doxygen documentation block, and each member variable, constant, and function/method within the class or interface should also have its own documentation block. Example:

/**
* Defines a common interface for a prepared statement.
*/
interface DatabaseStatementInterface extends Traversable <

/**
* Represents a prepared statement.
*
* Default implementation of DatabaseStatementInterface.
*/
class DatabaseStatementBase extends PDOStatement implements DatabaseStatementInterface <

/**
* Returns the foo information.
*
* @return object
* The foo information as an object.
*
* @throws MyFooUndefinedException
*/
public function getFoo () <
// Function body here.
>

Документирование групп/тем

You can make «Topics» pages by defining a «group», also known as a «module» in Doxygen terminology. We use topic/group pages to group functions that form an API that is meant to be used by multiple modules. Do not define a topic/group for functions that are internal to a particular file or module. See http://api.drupal.org/api/drupal/groups for a list of existing API topics/groups in Drupal Core.

Here is the basic syntax for defining a group:

The @defgroup line gives the name of the group that will be used in the URL, and then the name that will be used as the page title and in the Topics listing. Any text within the @defgroup’s own doxygen header appears as text on the topic page.

If you put the group definition immediately before one or more functions that belong in the group, you can automatically add functions to the group by using this syntax:

/**
* @defgroup group_identifier Name of the group for Topics page
* @<
* One line, one sentence description of the topic/group.
*
* One or more additional paragraphs of information, which will appear
* on the topic page.
*/

// Functions here are automatically added to the group.

/**
* @> End of «defgroup group_identifier».
*/

If you have functions that need to be added to a group whose definition is not right above the functions, there are two ways to do it:

before the functions, and

after the group of functions.

Ограничения и советы

Drupal’s Doxygen processing module, API module, currently only supports a small subset of all Doxygen commands and makes some assumptions about the formatting of the source. Code to be processed by api.module is advised to stick to these conventions.

The API module currently supports only one of Doxygen’s three grouping mechanisms: Modules (@defgroup, @ingroup, @addtogroup, @<, @>). See groups section above for more information on how we use modules/groups.

Источник