¿Existe un estándar para documentar los parámetros GET/POST?

Question

En un proyecto PHP, incluso cuando se utiliza la lógica del controlador frontal para la aplicación principal, puede haber muchos scripts independientes, fragmentos ajax, etc.

¿Existe una manera estandarizada, ya sea PHPDoc u otra cosa, para definir en el primer bloque de comentarios de la secuencia de comandos qué parámetros GET y/o POST aceptará/requerirá la secuencia de comandos y de qué tipo son?

Normalmente me ayudo añadiendo @param s como si el archivo fuera una función, y una explicación @return de lo que hace el script y lo devuelve, pero tal vez haya una forma más especializada que desconozco.

Answer 1

phpDocumentor no le va a gustar @param y @return etiquetas en el a nivel de archivo bloque de documentación ...

Si elige un archivo separado para documentarlos en, como por Mr-sk de la respuesta, puede usar @link para apuntar allí, pero no será visible inmediatamente en la página de documentación de su archivo ... solo será un hipervínculo en el que tendrá que hacer clic para ir a ver la información. Si desea que el contenido de alguno de los archivos esté visible en la página de documentación del archivo de script, puede usar la etiqueta en línea {@example} para señalarlo, o incluso solo algunas líneas, p. Ej. {@example/path/to/file 3 5} para mostrar solo las líneas tres a la cinco.

En este escenario, probablemente elegiría simplemente explicar las cosas en la descripción larga del docblock de nivel de archivo, ya que de hecho no hay una forma directa de etiquetar tus parámetros donde phpDocumentor los reconocerá como elementos de código. Si alguno de los parámetros que utilicé en mis descripciones eran elementos de código documentados que se originan en otro lugar del código, utilizaría la etiqueta {@link} en línea para apuntar a ese elemento de código.

Por ejemplo, supongamos que hay algunas constantes definidas en otro archivo de código, y la documentación propia de esos elementos se genera cuando se analiza ese otro archivo.Si mi larga descripción que escribo en el bloque de documentación a nivel de archivo de un archivo de script de sólo (como la suya) habla de esas constantes como parámetros, a continuación, la frase podría ser:

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

Referencias:

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

Answer 2

Pekka,

Me miro en el uso de un WADL para documentar la interacción con el API. No está respondiendo directamente a su pregunta, porque esto no se genera a partir de la documentación del código fuente, su XML, y se mantiene por separado.

No responder de manera directa:

lo consigue y/o POST los parámetros de la secuencia de comandos aceptará/requerir y de qué tipo son

Puede colocar cargas útiles de muestra en el documento, junto con parámetros de URI, tipos de contenido aceptados, códigos de error/respuestas/cargas útiles. Lo encuentro muy valioso, y con WADL, alguien puede codificar un cliente contra su API.

Para más información: http://research.sun.com/techrep/2006/abstract-153.html y : http://en.wikipedia.org/wiki/Web_Application_Description_Language

Answer 3

me gustaría utilizar @uses o @see Actualmente estoy usando @uses porque lee mejor y tiene sentido

Referencia: Nice pregunta https://phpdoc.org/docs/latest/references/phpdoc/tags/uses.html