Существует ли стандарт для документирования, ПОЛУЧАЮТ/POST параметры?
В проекте PHP, даже когда логика фронтального контроллера используется для главного приложения, может быть много автономных сценариев, ajax отрывки и так далее.
Существует ли стандартизованный способ - или PHPDoc или что-то еще - для определения в первом блоке комментария сценария, что ДОБИРАЕТСЯ, и/или параметры POST, которые сценарий примет / требуют и которых вводят, они?
Я обычно помогаю мне, просто добавив @params, как будто файл был функцией и a @return объяснение того, что сценарий делает и возвращает, но возможно существует более специализированный способ, о котором я не знаю.
2 ответа
phpDocumentor не понравится @param и @return теги в док-блоке файлового уровня...
Если вы выберете отдельный файл для их документирования, согласно ответу Mr-sk, вы можете использовать @link, чтобы указать на них, но это не будет сразу видно на странице документации вашего файла... это будет просто гиперссылка, на которую вам нужно будет нажать, чтобы перейти к информации. Если вы хотите, чтобы любое содержимое этого файла было видно на странице документации к вашему файлу скрипта, вы можете использовать тег inline {@example}, чтобы указать на него, или даже просто некоторые строки в нем, например, {@example /path/to/file 3 5}, чтобы показать только строки с третьей по пятую.
В этом сценарии я, наверное, решил бы просто объяснить вещи в длинном описании док-блока файлового уровня, так как на самом деле нет прямого способа пометить ваши параметры там, где phpDocumentor все равно будет распознавать их как элементы кода. Если бы любой из параметров, которые я использовал в своих описаниях, действительно был документированным кодовым элементом, который возникает где-то еще в коде, я бы использовал тег inline {@link}, чтобы указать на этот кодовый элемент.
Например, скажем, есть некоторые константы, определенные в другом файле кода, и документация этих элементов генерируется при разборе этого другого файла. Если в моем длинном описании, которое я пишу в док-блоке файлового уровня в файле только для скрипта (как и в вашем), эти константы упоминаются в качестве параметров, то мое предложение может быть следующим:
Если установлен $POST['foo'], то его значение всегда должно быть либо {@link BAR_CONST}, либо {@link BAZ_CONST}.
Ссылки:
Pekka,
Я бы посмотрел на использование WADL для документирования взаимодействия с вашим API. Это не напрямую отвечает на ваш вопрос - потому что это не генерируется из документации исходного кода, его XML и поддерживается отдельно.
Это отвечает на это непосредственно:
Что получают и / или параметры публикации Сценарий будет принимать / требовать и Какой тип они
, вы можете разместить примерные нагрузки в документ, а также с парамерами URI, принятыми типами контента, коды / ответы / отзывы / полезные нагрузки. Я считаю это очень ценным, а с Wadl, кто-то может записать клиент против вашей API.
Для получения дополнительной информации: http://research.sun.com/techrep/2006/abstract-153.html и: http://en.wikipedia.org/wiki/web_aplication_description_language