JavaScript Docs

This initiative follows the inline docs initiative with a specific focus on JavaScript. The goal is to get all JavaScript files in WordPress well documented and make this documentation easily accessible. JavaScript development within WordPress core is speeding up fast and becoming more and more prominent given the current core editor and REST API focuses. To help these developments progress as smoothly as possible, we need to make sure the existing code is documented well.

If you’re not familiar with what inline documentation is, read our page on inline documentation standards.

Which JS files should be documented? Which JS files should be documented?

There are three pages tracking JS files for documentation:

Top ↑

How to get involved How to get involved

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 JavaScript 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).

3. Read Opening a Ticket to learn how to create a Trac ticket.

4. Creating patches:

  • Claim a file to start documenting.
  • 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:

  • Create a new ticket on Core Trac for the file:
    • Suggested Title formats could be “JSDoc correction for path/to/file.js” or “Improve documentation for path/to/file.js”.
    • The Type should be defect (bug).
    • Assign the ticket to the Component the file is associated with.
    • Leave the Version blank.
    • Add the docs and the JavaScript Focus by clicking on it.
    • Here’s a shortcut link to create a new ticket in the Media component with the docs and javascript focuses and the title JSDocs correction for, all that is left to add is the filename in the title: New JSDocs Ticket
  • 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!

Top ↑

Points of contact Points of contact

For any questions, pop by the #docs channel in Slack. For JavaScript specific questions, you can also join the #core-js channel.

Top ↑

Resources Resources