WordPress’ current inline documentation efforts really kicked off starting in the 3.7 release cycle, and gained momentum as the hook docs initiative progressed. The inline documentation, or “inline docs” initiative is a hybrid project, reporting to the Core, Documentation, and Developer Hub teams.
Inline documentation provides both necessary and useful information in the form of inline-comments, doc blocks, and more within the source code of WordPress itself.
The inline documentation is parsed with each release, and that documentation is displayed in the Code Reference at developer.wordpress.org.
Inline documentation is considered to be “technical” documentation, so some familiarity with the WordPress codebase will be necessary – you have to understand the code to write about it.
1. Familiarize yourself with the
PHP Documentation Standard, as well as the formatting guidelines and documenting tips.
2. Set up a local copy of the developer version of the WordPress codebase using
Varying Vagrant Vagrants (VVV). WordPress is versioning using SVN, but you can also use Git (the VVV link for how to do that).
Opening a Ticket to learn how to create a Trac ticket.
4. Creating patches:
Always update your local copy of WordPress trunk before editing the file and creating patches. Use
svn up or
git pull, as appropriate.
Generate the patch from the root directory of your WordPress SVN or Git checkout.
It is best to name your patch file with the Trac ticket number you created, such as
12345.patch or 12345.diff. Either file extension is acceptable.
5. How to submit a patch:
new ticket on Core Trac for the file:
Title formats could be “PHPDoc correction for path/to/file.php” or “Improve documentation for path/to/file.php”. The
Type should be defect (bug). Assign the ticket to the
Component the file is associated with. Leave the
Version blank. Add the
docs Focus by clicking on it. Upload your patch to the Trac ticket you created, and add the keyword
has-patch. Make sure to leave a comment describing your newly-uploaded patch. Simply uploading patches doesn’t trigger a notification for anyone watching the ticket.
Note: Documentation changes should not mix with code changes (even whitespacing) unless the ticket specifically calls for both.
6. You can also contribute to
inline docs-related Trac tickets that need iteration.
If a ticket is marked
needs-patch or needs-refresh, it’s possible the existing patch(es) might just need a touch-up or be refreshed against the latest trunk. Every little bit helps!
For any questions, feel free to ping
@drew (Drew Jaynes) anytime in Slack. Or pop by #docs on Slack and ask your question.