Gibt es einen Standard zur Dokumentation von GET/POST-Parametern?

Question

In einem PHP-Projekt, selbst wenn Front-Controller-Logik für die Hauptanwendung verwendet wird, kann es viele eigenständige Skripte, Ajax-Schnipsel und so weiter geben.

Gibt es einen standardisierten Weg - entweder PHPDoc oder etwas anderes - um im ersten Kommentarblock des Skripts zu definieren, welche GET- und/oder POST-Parameter das Skript akzeptiert/benötigt und von welchem ​​Typ sie sind?

Ich helfe mir normalerweise, indem ich nur @param s hinzufüge, als ob die Datei eine Funktion wäre, und eine @return Erklärung für das, was das Skript tut und zurückgibt, aber vielleicht gibt es eine spezialisiertere Art, von der ich nichts weiß.

Answer 1

phpDocumentor nicht @param und @return Tags in der Dateiebene Docblock mögen ...

Wenn Sie eine separate Datei, um sie zu dokumentieren, wie per Mr-sk Antwort, können Sie @link dort zeigen, aber es wird nicht sofort sichtbar in die Dokumentationsseite Ihrer Datei ... es wird nur ein Hyperlink sein, auf den Sie klicken müssen, um die Informationen zu sehen. Wenn Sie möchten, dass der Inhalt dieser Datei auf der Dokumentationsseite für Ihre Skriptdatei angezeigt wird, können Sie das Inline-Tag {@beispiel} verwenden, um darauf zu zeigen, oder auch nur bestimmte Zeilen darin, z. {@example/path/to/file 3 5}, um nur die Zeilen drei bis fünf anzuzeigen.

In diesem Szenario würde ich wahrscheinlich nur die Dinge in der langen Beschreibung des Docblocks auf Dateiebene erklären, da es eigentlich keine direkte Möglichkeit gibt, Ihre Parameter dort zu markieren, wo phpDocumentor sie als Codeelemente erkennt. Wenn einer der Parameter, die ich in meinen Beschreibungen verwendet habe, tatsächlich dokumentierte Codeelemente waren, die an anderer Stelle im Code entstammen, verwende ich den integrierten Code {@link}, um auf dieses Codeelement zu zeigen.

Nehmen wir zum Beispiel an, dass einige Konstanten in einer anderen Codedatei definiert sind und die Dokumentation dieser Elemente generiert wird, wenn diese andere Datei analysiert wird.Wenn meine lange Beschreibung, die ich in der Dateiebene Docblock eines Skripts geschützte Datei (wie Sie) schreiben über diese Konstanten als Parameter spricht, dann könnte meinen Satz sein:

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

Referenzen:

• inline {@example}-http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineexample.pkg.html
• inline @ {link}-http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlinelink.pkg.html

Answer 2

Pekka,

ich in mit einem WADL aussehen würde mit Ihrem API zu dokumentieren interagieren. Es beantwortet Ihre Frage nicht direkt - denn diese wird nicht aus der Quellcodedokumentation, deren XML generiert und separat gepflegt.

Es ist diese direkt beantwortet:

was GET und/oder POST-Parameter das Skript akzeptiert/erfordern und von , welche Art sie sind

Sie Probe Nutzlasten in der platzieren Dokument, zusammen mit URI-Parametern, akzeptiert Content-Typen, Fehlercodes/Antworten/Payloads. Ich finde es sehr wertvoll, und mit einem WADL kann jemand einen Client gegen Ihre API kodieren.

Für weitere Informationen: http://research.sun.com/techrep/2006/abstract-153.html und: http://en.wikipedia.org/wiki/Web_Application_Description_Language

Answer 3

würde ich @uses oder @see Derzeit verwende ich @uses verwende, weil es besser liest und macht Sinn

Referenz: https://phpdoc.org/docs/latest/references/phpdoc/tags/uses.html