L'ordine dei tag phpDocumentor è importante?

Non come tale ... Almeno, nessuno che io possa trovare / pensare. Tuttavia, i docblock seguono generalmente un formato / modello distinto:

/**
 * Summary
 * [optional blank line]
 * Description
 * [optional blank line]
 * @see Optional, but more documentation can be added here
 * [optional blank line]
 * @todo: Development docs here
 * [optional blank line]
 * @api indicator of expected/intended usage of code
 * @uses Use-cases of code
 * @property* property-access
 * @deprecated
 * [optional blank line]
 * @param <type> $name [ = default value]
 * @return <return type, if any>
 * @throws <ExceptionType> [optionally explain when and why]
 * @throws <ExceptionType>
 */

L'ordine logico qui è:

• Sommario
• Descrizione
• Annotazioni che documentano ancora di più il codice, esempi, file, collegamenti ecc.
• Annotazioni che documentano il comportamento e l'uso del codice ((come @see )
• Annotazioni riguardanti lo sviluppo senza precedenti
• Annotazioni che indicano visibilità e utilizzo previsto ( @api o @internal ) Strutturale
• Annotazioni che indicano interni (dipendenze da metodi / proprietà) Strutturale
• Annotazioni relative alla disponibilità (deprecazione, preferibilmente menzionando alternative) Strutturale
• Annotazioni riguardanti la firma della funzione / metodo ( @param , poi @return )
• Annotazioni relative a comportamenti imprevisti (ad esempio @throws )

Alcuni potrebbero dire che l'annotazione @throws dovrebbe precedere il @returns , in quanto l'ultima cosa che una funzione dovrebbe fare è restituire qualcosa. È normale, tuttavia, inserire il @throws in ultimo. Questo, per me, ha più senso: la documentazione copre il flusso del metodo che stai commentando. Se qualcosa (un caso eccezionale) interrompe il flusso, viene generata un'eccezione, quindi l'annotazione @throws non deve far parte della "normale" descrizione del metodo.

In entrambi i casi, la semplice regola empirica è:

• vengono fornite le informazioni sulla descrizione IDE prima (riepilogo, descrizione, @see )
• Documentazione aggiuntiva
• Informazioni di sviluppo ( @todo , @example , possibilmente @version )
• Elementi strutturali (quelli che si applicano)
• Le informazioni sui parametri previsti vengono dopo ( @param )
• Il risultato ( @return )
• In caso di errori ( @throws )

Si noti che le annotazioni elencate qui come Elementi strutturali richiedono di documentare anche le classi e le proprietà: /** @var <type> */ e, forse anche @version e @license tag