When we document our class, method and/or function with phpDocumentor, is there any specific order I should follow according to the standards?
I know it doesn’t matter for output the document. Since it is outputting the order what I have written.
This is for my knowledge and understanding if there is any order standards for it.
Not as such… At least, none that I can find/think of. However, docblocks commonly follow a distinct format/pattern:
/**
* 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>
*/
The logical order here is:
- Summary
- Description
- Annotations documenting the code even more, examples, files, links etc…
- Annotations that document behavior and usage of code ( (like
@see) - Annotations regarding ungoing development
- Annotations indicating visibility and expected usage (
@apior@internal) Structural - Annotations indicating internals (dependencies on methods/properties) Structural
- Annotations regarding availability (deprecation, preferably mentioning alternatives) Structural
- Annotations regarding the function/method’s signature (
@param, then@return) - Annotations covering unexpected behaviour (ie
@throws)
Some might say that the @throws annotation should precede the @returns, seeing as the last thing a function should do is return something. It is common, though, to put the @throws in last. That, to me, makes more sense: the documentation covers the flow of the method you’re commenting. If something (an exceptional case) disrupts the flow, an exception is thrown, hence the @throws annotation shouldn’t be part of the “normal” description of the method.
Either way, the simple rule of thumb here is:
- IDE tooltip info comes first (summary, description,
@see) - Additional documentation
- Development info (
@todo,@example, possibly@version) - Structural elements (the ones that apply)
- The expected parameters info comes next (
@param) - The result (
@return) - In case of errors (
@throws)
Note that the annotations listed here as Structural elements require you to document the classes and properties, too: /** @var <type> */ and, perhaps include @version and @license tags, too