Существует ли стандарт для документирования параметров GET/POST?

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

Существует ли стандартизованный способ - либо PHPDoc, либо что-то еще - определить в первом блоке комментариев script, какие параметры GET и/или POST будут принимать/требуют script и какой тип они являются?

Я обычно помогаю себе, просто добавляя @param, как если бы файл был функцией, и объяснение @return для того, что делает и возвращает script, но, возможно, есть более специализированный способ, который я не знаю.

Ответы

Ответ 1

phpDocumentor не будет использовать теги @param и @return в докблоке уровня файла...

Если вы выберете отдельный файл для их документирования, в соответствии с ответом Mr-sk, вы можете использовать @link, чтобы указать там, но он не будет сразу виден на странице документации файла... это будет просто гиперссылка, которую вам нужно будет щелкнуть, чтобы перейти к информации. Если вы хотите, чтобы какое-либо содержимое этого файла было видимым на странице документации вашего файла script, вы можете использовать тег inline {@example}, чтобы указать на него, или даже на определенные строки в это, например {@example/path/to/file 3 5}, чтобы показывать только строки от трех до пяти.

В этом случае, я бы выбрал только объяснить вещи в длинном описании DocBlock уровня файлов, так как на самом деле не прямой путь пометки параметров туда, где PhpDocumentor распознает их как элементы кода в любом случае. Если какой-либо из параметров, которые я использовал в своих описаниях, были действительно документированными элементами кода, которые происходят из другого места в коде, я бы использовал тег inline {@link}, чтобы указать на этот элемент кода.

Например, скажем, есть некоторые константы, определенные в другом файле кода, и их документация создается, когда этот другой файл разбирается. Если мое длинное описание, которое я пишу в докблоке на уровне файла файла script -only (например, ваш), говорит об этих константах в качестве параметров, тогда мое предложение может быть:

If $POST['foo'] is set, its value should always be either {@link BAR_CONST} or {@link BAZ_CONST}.

Литература:

Ответ 2

Пекка,

Я бы рассмотрел использование WADL для документирования взаимодействия с вашим API. Он не отвечает напрямую на ваш вопрос, потому что это не генерируется из документации исходного кода, его XML и поддерживается отдельно.

Это прямо ответит:

какие параметры GET и/или POST script будет принимать/требовать и которые имеют тип

Вы можете поместить образцы данных в документ вместе с параметрами URI, принятыми типами контента, кодами ошибок/ответами/полезными нагрузками. Я считаю, что это очень ценно, и с помощью WADL кто-то может закодировать клиента против вашего API.

За дополнительной информацией: http://research.sun.com/techrep/2006/abstract-153.html и: http://en.wikipedia.org/wiki/Web_Application_Description_Language