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

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

или подробнее:

Но что, если, например, аргумент вашей функции — сложный ассоциативный массив, и вам непременно надо проинструктировать коллегу (или себя самого в будущем), какие именно индексы в нем ожидаются. Оказывается, стандартных путей это сделать просто нет. Порывшись в StackOverflow, Quora и на сайтах, обсуждающих PSR и PHPDocumentor, обнаружил, что программисты каждый раз «изобратют велосипед», и в общем-то все варианты сводятся к разным вариантам индентации, а сама структура массива описывается просто перечислением ключей и, иногда, их типов следом за стандартным определением массива через @param. Например, так (ответ на StackOverflow):

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

или определять новые структуры данных в PHPDoc на уровне файла, к которому они относятся, и затем в качестве типа указывать эту структуру:

Обсуждение, однако, до сих пор открыто.

Другие варианты, предложенные на Stackoverflow:

и простое описание структуры массива в тегах <code> для удобочитаемости:

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

Лично я пришел к следующему варианту с учетом его красивого отображения в IDE PHP Storm (вся отбивка табами, строки @param и show_id там отстоят друг от друга на один таб).

Поделиться: Share on LinkedIn
Linkedin
Share on VK
VK
Share on Facebook
Facebook
0Share on Google+
Google+
0Tweet about this on Twitter
Twitter

Оставить комментарий

Ваш e-mail не будет опубликован.

Яндекс.Метрика