В PHP-проекте, даже если логика контроллера контроллера используется для основного приложения, может быть много автономных скриптов, фрагментов ajax и т. Д.
Существует ли стандартизованный способ – либо PHPDoc, либо что-то еще – определить в первом блоке комментариев скрипта параметры GET и / или POST, которые скрипт примет / потребует и какого типа они есть?
Я обычно помогаю себе, просто добавляя @param s, как если бы файл был функцией, и объяснение @return для того, что сценарий делает и возвращает, но, возможно, есть более специализированный способ, о котором я не знаю.
phpDocumentor не понравится тегам @param и @return в docblock уровня файла …
Если вы выберете отдельный файл для их документирования, в соответствии с ответом г-на sk , вы можете использовать @link для указания там, но он не будет сразу виден на странице документации вашего файла … это будет просто гиперссылку, которую вам нужно щелкнуть, чтобы перейти к информации. Если вы хотите, чтобы содержимое какого-либо файла было видимым на странице документации вашего файла сценария, вы можете использовать тег inline {@example}, чтобы указать на него, или даже определенные строки в нем, например {@example / path / to / file 3 5}, чтобы отображать только строки три-пять.
В этом случае я бы предпочел просто объяснить вещи в длинном описании файлового уровня docblock, поскольку на самом деле нет прямого способа пометить ваши параметры, где phpDocumentor будет распознавать их как элементы кода в любом случае. Если какой-либо из параметров, которые я использовал в своих описаниях, действительно были документированными элементами кода, которые происходят из другого места в коде, я бы использовал тег inline {@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