-
-
Notifications
You must be signed in to change notification settings - Fork 470
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document how to write XML documentation files #2462
Comments
@GaryJones Good point. Then again, once the ongoing "let's get the documentation written" task has been finished, there shouldn't be much need for it aside from the odd new sniff. The documentation task issue #1722 contains reasonably detailed info on writing documentation. What do you think, would linking to that issue be enough ? Or maybe distilling the most essential bits ("guidelines" bullet point) ? The PHPCS Contributing Guide also has a section about writing docs, which we could link to. |
Maybe also relevant: for "what can go wrong", we currently have one QA check in place for the docs (though more will be added once available and two extra checks are being worked on). The current check validates that the XML docs at the very least comply with the XSD file as available from PHPCSDevTools. |
Is your feature request related to a problem?
I can't find an obvious place that tells new contributors how to write new XML documentation files.
Describe the solution you'd like
A section in
CONTRIBUTING.md
that highlights the existing "features" of existing documentation files, such as how and when to use the<em>
</em>
tags, to put the valid code before the invalid code, how descriptions should be written, how to handle where there is an imbalanced number of ways to get things wrong vs getting things right, etc.Additional context (optional)
The text was updated successfully, but these errors were encountered: