Docs-focused Bug Scrub Friday

We’ll have a docs-focused bug scrub Friday, Oct. 7 2016 14:00 CDT in the #docs Slack channel, for anyone interested in contributing. We’ll focus on the needs-docs keyword first, then on the docs focus if there’s time.

#4-7, #inline-docs

No Inline Docs Chat Today

Due to a scheduling conflict, today’s Inline Docs chat has been cancelled.

See everyone next week!


Inline Docs Chat Agenda, Dec. 3

Here is the loose agenda for today’s inline docs chat in the #docs channel on Slack at 20:00 UTC

  1. Private/internal functionality
    We need to come up with a plan and frame of reference for how private/internal functionality should be treated in terms of what’s parsed and what’s not.
  2. Guidelines for `see` tags
    In some core DocBlocks, multiple functions are listed. Is that allowed/supported? Do we have adequate coverage for inline `see` tags?
  3. JavaScript Docs Standard
    Outstanding discussion topics:
    • List of text editors/IDEs with bundles/extensions for auto-creating JSDoc blocks (@ericlewis) (Sublime w/DocBlockr)
    • List of `@` tags we don’t use in core (Kim to write explanations why)
    • Consistency with the PHP Doc Standard (sections/format)


No inline-docs chat this week

Due to the Thanksgiving holiday this week, there will be no inline-docs chat this week. We have some items for an agenda and I’ll post that a day or before our regularly-schedule chat next week.

#chat, #inline-docs

Inline Docs chat this week

I’ll be hosting an inline docs chat this week Wednesday 19:00 UTC in #wordpress-sfd.

Meeting Agenda:

  • Discuss adopting a documentation standard for core JavaScript
  • Report on progress of aliasing dynamic hooks in core and the Code Reference

If you have anything you’d like to add to the agenda, leave a suggestion in the comments.


Agenda for today's Inline Docs chat

It’s been awhile since we’ve had an inline docs chat, and there are several items on the agenda for today’s meeting at 19:00 UTC (3:00 pm EDT) in IRC in #wordpress-sfd:

  • 4.0 Audit – #28885
  • Access tags for all the methods
  • Hook aliases + PHPDoc tags
  • PHPDoc tags for unit tests – #28558

If you’d like to suggest any additional items for the agenda, leave them in the comments below. Thanks!

#core, #inline-docs

Documenting all the dynamic hook aliases

A couple of weeks ago at Open Source Bridge, I started a conversation with @jorbin about an idea to document common aliases of dynamic hooks in core docs. A long-standing pain point in core, and now in the Code Reference, is that dynamic hooks aren’t really searchable.

For example, let’s say I want to search for the ‘publish_post’ hook. If I search the source, I see add_action() calls referencing that hook, but its origin is nowhere to be found. This is because the hook is actually {$new_status}_{$post->post_type}.

The idea would be to make it possible to search the source and the Code Reference for indexed common aliases like ‘publish_post’ and have it return the reference for {$new_status}_{$post->post_type}.

Great, so what’s next?

We’ve already started a spreadsheet at the WordCamp Seattle contributor day to begin identifying common aliases of all of the dynamic hooks in core. Big thanks goes to @trepmal for providing a complete list of all dynamic hooks from her presentation slides.

If you’d like to get in on the ground floor and help out, the spreadsheet can be found here:

Over the next few weeks, I’ll be working with @rarst to devise a solution for parsing hook aliases using WP-Parser. When we have a solution in place, we start planning the effort to begin patching hook docs in core.

We’ll be tracking progress on #557-meta on Meta Trac.

Yay progress!

#core, #inline-docs

No inline docs chat this week

We won’t be having an inline docs chat this week since @kpdesign will be unavailable, and I’ll be at a company retreat in Arizona until Friday.

If anyone has suggested agenda items for the May 21 meeting, please leave them in the comments.

#chat, #inline-docs

Inline Docs Weekly Office Hours Time Change

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!


Hook Docs sprint today

For anyone interested in helping out, @kpdesign and I are doing a Hook Docs sprint today starting at 19:00 UTC in #wordpress-sfd. Any tickets marked “needs patch” can be worked on, and the number of hooks to document is now marked in the title of each ticket.

This would be a great opportunity to get core credit in the soon-to-start 3.9 cycle.

To see a full list of Hook Docs tickets to work on, see here:

#inline-docs, #sprint