Tagged: inline-docs Toggle Comment Threads | Keyboard Shortcuts
Quick note to let everyone know that the Inline Docs weekly office hours time is changing.
Due to a schedule conflict, we’ll be meeting an hour later, starting this week. Same day (Wednesday), now at 20:00 UTC in #wordpress-sfd.
If you’re interested in contributing to Inline Docs, come join us!
We haven’t posted an update in several weeks, so thought we’d bring everyone up to speed on the Inline Docs project.
This project started July at WordCamp San Francisco as a 3.7 release action item. Work continues into the 3.8 release cycle, and we would like to have the hook documentation completed by the time 3.8 is released in December.
PHP Documentation Standards
The PHP Documentation Standard has been amended several times since it was first published in early September. The latest amendments include:
- Documenting Tips (language, tools for finding the version for
@since, code refactoring)
- Formatting Guidelines
- A change to the way duplicate hooks should be documented (
/** This action|filter is documented in path/to/file.php */)
If you are one of our contributors, please make sure you read the standards again to familiarize yourself with the changes.
WordCamp Contributor Days
We would like to thank WordCamp Toronto (10/6), WordCamp Europe (10/7), and WordCamp Sofia (10/27) for including Inline Docs as part of their respective Contributor Days. Approximately 35 files were documented, and several new contributors had their first patches committed to WordPress core as a result. Woot!
So far, 47 people have received props for submitting inline docs patches:
@admiralthrawn, @aeg0125, @a.hoereth, @andg, @aralbald, @bananastalktome, @ben.moody, @betzster, @bftrick, @dllh, @drewapicture, @dougwollison, @dustyf, @enej, @ericlewis, @Faison, @FrankKlein, @gayadesign, @gizburdt, @johnafish, @johnbillion, @jonlynch, @kpdesign, @l10n, @nacin, @naomicbush, @NikV, @ninio, @miyauchi, @morduak, @Nao, @natejacobs, @netweb, @nukaga, @nullvariable, @pauldewouters, @r3df, @rzen, @sboisvert, @SergeyBiryukov, @ShinichiN, @Siobhyb, @swissspidy, @tmtoy, @tomauger, @tw2113, @vinod dalvi
There are 10 other contributors with patches waiting to be reviewed and committed that will be added to this list. We want to thank everyone for their participation so far, and hope you continue contributing!
Progress To Date
According to the “master list“, there are 185 files containing hooks to be documented. The current status, as of today:
- Completed: 92 files (49.72%)
- In progress: 23 files
- Available to claim: 70 files
Weekly Office Hours
We continue to hold weekly office hours meetings on Wednesdays at 19:00 UTC in #wordpress-sfd.
- Documenting Tips (language, tools for finding the version for
After last week’s weekly Inline Docs meeting we decided to begin doing a weekly ticket triage on Wednesdays.
As of last Wednesday, we’re happy to report that 19 patches have been committed to core from 12 different contributors. We’ve also updated the original make/core post to reflect the files that have been completed (please go claim some!). You can see the full report of last week’s triage on Trac. It’s really spectacular, and you should show some gratitude towards Drew for putting the report together.
Finally, beginning this week, our weekly inline-docs office hours are moving to #wordpress-sfd on Freenode. They’ll continue to be held on Wednesdays at 18:00 UTC, and we hope you can join us!
There will be a weekly office hours meeting on Wednesday, September 11, 2013 at 18:00 UTC in #wordpress-dev. Agenda includes status update on the hooks initiative that kicked off last week, and answering questions anyone may have about the effort.
If you’re interested in participating, please plan on attending.
It’s been awhile since you’ve heard from any of us about the inline-docs initiative for 3.7. We’ve been getting our ducks in a row, so to speak, and we’d like to start pounding pavement this week.
We’re going to hold an office-hours meeting on Wednesday, September 4 at 18:00 UTC in #wordpress-dev. We’ll review where we left off last meeting, cover the details on how we want to proceed, and make sure the details about getting involved really do show up here on Make/Core.
This meeting is mostly to help us on the planning team make sure we’re on the same page, but all are welcome. As I said, the next action steps for interested parties will get posted back here.
Thanks, too, for all of the encouragement around this. We’re pretty excited about it!
For the 3.7 cycle we’re going to focus hard on improving the inline docs throughout WP core. Eric Lewis, Drew Jaynes and myself will be leading this charge, and we invite anyone who is interested to join us.
You can join us for a meeting on the subject in #wordpress-dev IRC on Tuesday, August 13, 18:00 UTC.
For the first time ever, we’ll be adding inline docs to the many, many hooks found within core. This is the area I’ll be contributing the most, personally. Since we’ll mostly be marching to the beat of our own drum to document the hooks, so I’d like to use the remainder of this post to explain a bit more about our plan of attack – which we’ll discuss during Tuesday’s meeting.
Hook Doc Style
We’ll be using the same inline PHPDoc standard that is used for functions to documenting each of the hooks. This means both short description and long descriptions (where applicable), along with @since and @param tags. We will not be using the @return tag, however, because actions return nothing and filters simply return the first param.
The DocBlocks will appear, in almost every case, on the line directly preceding the call to do_action() or apply_filters. We feel this is the most logical placement when grokking the code as a human, and also the most convenient position for the parser that will power developer.wordpress.org.
Note that in this third example we are using on the PHPDoc spec for describing hashes in order to document each of the passed items in the array. This, I think, provides a great deal of context for the array and a much greater value to our documentation (especially given the number of filters in core that pass arrays). As an aside, I agree that it may be odd we’re referencing the associative array keys as var names, rather than a string literal, but it’s necessary for parsing the docs properly.
Some Potential Issues
- I know there are a few hooks that appear in more than one location. In this case we’ll be documenting them in just one function and adding a pointer to that function across all other instances. We’ll determine the best way to handle this pointer in the weeks to come, for the immediate future I’ll just be using a shorthand comment for my own references.
- Many filters throughout core passed unnamed parameters and just embed the values of their parameters directly. In these instances I look first to core to see if an add_filter() is being called on the filter and then default to the var names passed there. If core is not calling the filter anywhere I’ve used names that seem most logical (e.g. $output)
- Several hooks have variable names. I don’e believe this will actually pose an issue, but I do want to make note of it.
Because of the sheer volume of things we need to document, the best idea I’ve got so far (as recommended by Mark Jaquith) is to allow anyone willing to contribute an opportunity to “claim” the files they’d like to document. This would grant them a 2 day “lock” on the file(s) to document everything and submit a patch. This will help us minimize or eliminate duplicated efforts and stale patches as much as possible. We’ll likely have 2 separate tickets: one for documenting hooks, one for documenting functions, and all patches will be made directly to those tickets. This could become unwieldy, and we’ll discuss the merits of this approach in Tuesday’s meeting.
Don’t worry if you really want to help, but can’t attend the meeting. It will all be logged, and we’ll be posting updates back to the blog here (using the inline-docs tag). Once we get underway you’ll be able to track progress directly on the trac tickets.
Hope you’re as excited about this as I am!