Существует ли стандарт для документирования параметров GET/POST?
В проекте PHP, даже когда логика фронт-контроллера используется для основного приложения, может быть много автономных сценариев, фрагментов ajax и так далее.
Существует ли стандартизированный способ - либо PHPDoc, либо что-то еще - чтобы определить в первом блоке комментариев скрипта, какие параметры GET и / или POST скрипт примет / потребует и какого типа они являются?
Я обычно помогаю себе, просто добавляя @paramкак если бы файл был функцией, а @return объяснение того, что делает и возвращает скрипт, но, возможно, есть более специализированный способ, о котором я не знаю.
3 ответа
phpDocumentor не понравятся теги @param и @return в блоке документов на уровне файлов...
Если вы выберете отдельный файл для их документирования, согласно ответу Mr-sk, вы можете использовать @link, чтобы указать на него, но он не будет сразу виден на странице документации вашего файла... это будет просто гиперссылка, по которой вам нужно будет перейти, чтобы увидеть информацию. Если вы хотите, чтобы какое-либо содержимое этого файла было видно на странице документации для вашего файла сценария, вы можете использовать встроенный тег {@example}, чтобы указать на него, или даже только некоторые строки в нем, например, {@example /path/to/file 3 5}, чтобы показать только строки с третьей по пятую.
В этом сценарии я бы, вероятно, решил просто объяснить что-то в длинном описании докблока на уровне файлов, поскольку на самом деле нет прямого способа пометить ваши параметры так, чтобы phpDocumentor распознал их как элементы кода в любом случае. Если бы любой из параметров, которые я использовал в своих описаниях, действительно был документированными элементами кода, которые происходят где-то еще в коде, я бы использовал встроенный тег {@link}, чтобы указать на этот элемент кода.
Например, скажем, есть некоторые константы, определенные в другом файле кода, и собственная документация этих элементов генерируется при разборе этого другого файла. Если мое длинное описание, которое я записываю в докблок на уровне файлов файла, содержащего только сценарии (например, ваше), говорит об этих константах в качестве параметров, то мое предложение может быть следующим:
If $POST['foo'] is set, its value should always be either {@link BAR_CONST} or {@link BAZ_CONST}.
Рекомендации:
Пекка,
Я хотел бы изучить использование WADL для документирования взаимодействия с вашим API. Он не отвечает непосредственно на ваш вопрос - потому что он не генерируется из документации по исходному коду, его XML и поддерживается отдельно.
Это отвечает прямо на это:
какие параметры GET и / или POST скрипт примет / потребует и какого типа они
Вы можете разместить образцы полезных данных в документе вместе с параметрами URI, принятыми типами содержимого, кодами ошибок / ответами / полезными нагрузками. Я нахожу это очень ценным, и с помощью WADL кто-то может кодировать клиента под ваш API.
Для получения дополнительной информации: http://research.sun.com/techrep/2006/abstract-153.html и: http://en.wikipedia.org/wiki/Web_Application_Description_Language
Я хотел бы использовать @uses или же @see В настоящее время я использую @uses потому что читается лучше и имеет смысл
Ссылка: https://phpdoc.org/docs/latest/references/phpdoc/tags/uses.html