php-doclisted

## Documentation (phpDoc) ### Golden Rule **Never duplicate signature information without adding value.** If the class name, method name, parameter names, and PHP types already tell the full story, skip the docblock entirely. Skip documentation when: - The method is trivial and self-explanatory (getters, setters, simple delegations) - The docblock would only repeat what the signature already says - Parameter names are descriptive enough (`$width`, `$height`, `$name`) Write documentation when: - The method has non-obvious behavior (returns null in specific conditions, throws exceptions) - Array contents need specification (`@return string[]`) - Parameters have constraints, formats, or valid ranges not captured by PHP types - The "why" behind a design choice matters for callers ### Writing Style - Always American English (color, not colour; behavior, not behaviour) - Start method descriptions with 3rd person singular present tense verb: Returns, Formats, Checks, Creates, Converts, Sets - Skip phrases like "Class that...", "Interface for...", "Method that..." - Don't duplicate method lists or implementation details in class docblocks - Use active phrasing describing main responsibility ### Preferred Phrases Use consistent phrasing for recurring situations: | Situation | Phrase | |-----------|--------| | Returns a value | "Returns..." | | Returns null on failure | "Returns X, or null if..." | | Checks a condition | "Checks whether..." | | Creates an object | "Creates..."