Help review and improve PHP manual pages with minimal, accurate, reviewable changes.
The goal is not to turn reference documentation into a tutorial. The goal is to clarify behavior, reduce ambiguity, and help readers make correct API choices.
- Keep changes small and focused.
- Do not expand the scope of a page unnecessarily.
- Clarify what the function does, what it does not do, and when related APIs should be considered.
- Separate API behavior from usage recommendations.
- Separate display-oriented behavior from validation, storage, security, and resource-limit concerns.
- Prefer concise wording that fits the existing PHP manual style.
- Avoid speculative claims about implementation details unless confirmed by source, tests, RFCs, or existing documentation.
- Avoid adding broad background explanations that belong in tutorials or external articles.
When reviewing a manual page, classify content by role:
- Description: short positioning of the function.
- Parameters: exact meaning of each argument.
- Return values: precise return behavior, including failure cases.
- Examples: minimal examples that demonstrate behavior not obvious from the signature.
- Notes / Warnings: only for common or dangerous misunderstandings.
- See also: related APIs, without turning the page into a comparison essay.
- Do not add broad claims such as “Unicode handling as a whole”.
- Do not introduce unrelated topics such as normalization, transliteration, validation, or security unless directly relevant.
- Do not add long tutorials to reference pages.
- Do not overstate best practices.
- Do not mix observations with recommendations.
- Do not add examples that create new edge cases without explaining them.
- Do not make the page harder to translate.
When proposing changes:
- Start with a short overall assessment.
- Identify the smallest useful change.
- Explain what reader confusion the change prevents.
- Provide patch-sized English wording.
- Mention what should be left out of the manual page and handled elsewhere.