C'è uno standard per documentare i parametri GET / POST?

In un progetto PHP, anche quando la logica del front controller viene utilizzata per l'applicazione principale, ci possono essere molti script stand-alone, ajax snippet e così via.

Esiste un modo standardizzato – PHPDoc o qualcos'altro – per definire nel primo block di commento dello script quali parametri GET e / o POST lo script accetterà / richiederà e di quale tipo sono?

Di solito mi aiuto aggiungendo @param s come se il file fosse una function, e una spiegazione @return per ciò che lo script fa e ritorna, ma forse c'è un modo più specializzato che non conosco.

phpDocumentor non gradirà i tag @param e @return nel docblock a livello di file …

Se scegli un file separato per documentarli, come per la risposta di Mr-sk , puoi usare @link per puntare lì, ma non sarà immediatamente visibile nella pagina della documentazione del tuo file … sarà solo un collegamento ipertestuale che dovrai click per andare a vedere le informazioni. Se vuoi che i contenuti di quel file siano visibili nella pagina di documentazione del tuo file di script, puoi usare il tag {@example} inline per puntarlo, o anche solo alcune righe in esso, ad esempio {@esempio / path / a / file 3 5} per mostrare solo le righe da tre a cinque.

In questo scenario, probabilmente sceglierei semplicemente di spiegare le cose nella lunga descrizione del docblock a livello di file, poiché in realtà non esiste un modo diretto di codificare i parametri in cui phpDocumentor li riconoscerà comunque come elementi di codice. Se uno qualsiasi dei parametri che ho usato nelle mie descrizioni fossero effettivamente elementi di codice documentati che hanno origine da qualche altra parte nel codice, userei il tag inline {@link} per puntare a quell'elemento di codice.

Ad esempio, supponiamo che alcune costanti siano definite in un altro file di codice e che la documentazione di tali elementi venga generata quando viene analizzato l'altro file. Se la mia lunga descrizione che scrivo nel file docblock a livello di file di un file di script (come la tua) parla di queste costanti come parametri, allora la mia frase potrebbe essere:

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

Riferimenti:

Pekka,

Vorrei esaminare l'utilizzo di un WADL per documentare l'interazione con la tua API. Non risponde direttamente alla tua domanda, perché non è generata dalla documentazione del codice sorgente, dal suo XML e mantenuta separatamente.

Risponde direttamente a questo:

quali parametri GET e / o POST lo script accetterà / richiederà e di quale tipo sono

È ansible posizionare payload di esempio nel documento, insieme a parametri URI, tipi di contenuto accettati, codici di errore / risposte / carichi utili. Lo trovo molto prezioso e con un WADL, qualcuno può codificare un client contro la tua API.

Per maggiori informazioni: http://research.sun.com/techrep/2006/abstract-153.html e: http://en.wikipedia.org/wiki/Web_Application_Description_Language

Vorrei usare @uses o @see Attualmente sto usando @uses perché legge meglio e ha senso

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