JS docs initiative: Add inline-docs for JavaScript! (part 2)

Because of a restriction of wordpress.org, you cannot comment on posts older than 120 days. This new post can be used to track the work on Javascript inline-docs. The original post on the JS docs initiative can be found here. In this post I have excluded files that have already been completed.

At the bottom is a list of every first-party JavaScript file in core. Files with a checkmark have been patched and are considered completed. Files marked with (username #xxxxx) are already claimed, and being worked on.

Directly below is the process we’re using to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.

How to contribute

  1. Familiarize yourself with the JavaScript documentation standard, as well as the formatting guidelines and documenting tips.
  2. Check the list first to make sure the file you want to work on hasn’t already been claimed.
  3. Update your local WordPress SVN (use svn up) or Git repo (use git pull) to the latest version of WordPress trunk.
  4. Create a new ticket on Trac for the file.
    • Format the title as “JSDoc: 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 javascript focuses.
  5. Edit the file, and make a patch. Please make sure you create the patch from the root directory of your WordPress SVN or Git checkout.
  6. Upload your patch to the Trac ticket you created, and add the keyword “has-patch”.

We’d like to welcome everyone to start contributing inline documentation! You can start contributing by picking a file from the list of unclaimed files below and claiming it in the comments. Please also see the JS docs handbook page for a step by step guide on how to get started.

Note: Note: To give everyone a chance to claim a file and to ensure the work proceeds as quickly as possible, please only work on one file at a time.

Determining the since version

We use JSDoc’s @since tag to indicate when a particular function was added to WordPress core. When you are documenting a function, you will also need to identify when that function was first introduced.

The recommended tool to use when searching for the version something was added to WordPress is svn blame. An additional resource for hooks is the WordPress Hooks Database. If, after using these tools, the version number cannot be determined, use @since Unknown.

If you use the git repository of WordPress you can also use git to determine the @since version. Either use git blame or the GitHub blame function. Once you have the commit hash which introduced a piece of code you can find out the version by using git tag --contains [commit-hash]. This will list all versions a certain commit has been shipped in. The lowest version is then what you put after the @since annotation.

Note: Make sure that the commit you found it the actual commit where a piece of code was introduced. JavaScript files have been moved around a lot in the past, so make sure to take that into account.

Note: All @since tags should follow the three digit x.x.x format.

Keeping Discussions Focused:

Any discussion about the specifics of a patch itself should happen on Trac. Any discussion about the broader scope of what we’re trying to do should take place during the weekly devchat. That’s either #core-js or #core.

Files needing patches:

Checked files are completed, marked files are claimed

  • src/js/_enqueues/wp/customize/controls.js (@jjcomack)
  • src/js/_enqueues/wp/customize/nav-menus.js
  • src/js/_enqueues/wp/customize/widgets.js
  • src/js/_enqueues/lib/gallery.js (@hunkriyaz)
  • src/js/_enqueues/admin/link.js (@andg)
  • src/js/_enqueues/lib/nav-menu.js
  • src/js/_enqueues/admin/plugin-install.js
  • src/js/_enqueues/wp/revisions.js
  • src/js/_enqueues/admin/set-post-thumbnail.js
  • src/js/_enqueues/wp/svg-painter.js
  • src/js/_enqueues/wp/theme.js (@igorsch)
  • src/js/_enqueues/wp/updates.js
  • src/js/_enqueues/admin/user-profile.js
  • src/js/_enqueues/admin/widgets.js
  • src/js/_enqueues/deprecated/fullscreen-stub.js
  • src/js/_enqueues/wp/customize/base.js
  • src/js/_enqueues/wp/customize/loader.js
  • src/js/_enqueues/wp/customize/models.js
  • src/js/_enqueues/wp/customize/preview-nav-menus.js
  • src/js/_enqueues/wp/customize/preview.js
  • src/js/_enqueues/wp/customize/selective-refresh.js
  • src/js/_enqueues/wp/customize/views.js
  • src/js/_enqueues/wp/mce-view.js
  • src/js/_enqueues/wp/media/audiovideo.js
  • src/js/_enqueues/wp/media/editor.js
  • src/js/_enqueues/wp/media/grid.js
  • src/js/_enqueues/wp/media/models.js
  • src/js/_enqueues/wp/media/views.js
  • src/js/media/controllers/audio-details.js
  • src/js/media/controllers/collection-add.js
  • src/js/media/controllers/collection-edit.js
  • src/js/media/controllers/edit-attachment-metadata.js
  • src/js/media/controllers/embed.js
  • src/js/media/controllers/featured-image.js
  • src/js/media/controllers/image-details.js
  • src/js/media/controllers/library.js
  • src/js/media/controllers/media-library.js
  • src/js/media/controllers/region.js
  • src/js/media/controllers/replace-image.js
  • src/js/media/controllers/site-icon-cropper.js
  • src/js/media/controllers/state-machine.js
  • src/js/media/controllers/state.js
  • src/js/media/controllers/video-details.js
  • src/js/media/models/attachment.js
  • src/js/media/models/post-image.js
  • src/js/media/models/post-media.js
  • src/js/media/models/query.js
  • src/js/media/models/selection.js
  • src/js/media/routers/manage.js
  • src/js/media/utils/selection-sync.js
  • src/js/media/views/attachment-compat.js
  • src/js/media/views/attachment-filters.js
  • src/js/media/views/attachment-filters/all.js
  • src/js/media/views/attachment-filters/date.js
  • src/js/media/views/attachment-filters/uploaded.js
  • src/js/media/views/attachment.js (@digitalarticle)
  • src/js/media/views/attachment/details-two-column.js
  • src/js/media/views/attachment/details.js (@maartenleenders)
  • src/js/media/views/attachment/edit-library.js
  • src/js/media/views/attachment/edit-selection.js
  • src/js/media/views/attachment/library.js
  • src/js/media/views/attachment/selection.js
  • src/js/media/views/attachments/browser.js
  • src/js/media/views/attachments/selection.js
  • src/js/media/views/audio-details.js
  • src/js/media/views/button-group.js
  • src/js/media/views/button.js (@dfangstrom)
  • src/js/media/views/button/delete-selected-permanently.js
  • src/js/media/views/button/delete-selected.js
  • src/js/media/views/button/select-mode-toggle.js
  • src/js/media/views/cropper.js (@kapteinbluf)
  • src/js/media/views/edit-image-details.js
  • src/js/media/views/edit-image.js
  • src/js/media/views/embed.js
  • src/js/media/views/embed/image.js
  • src/js/media/views/embed/link.js
  • src/js/media/views/embed/url.js
  • src/js/media/views/focus-manager.js
  • src/js/media/views/frame.js
  • src/js/media/views/frame/audio-details.js
  • src/js/media/views/frame/edit-attachments.js
  • src/js/media/views/frame/image-details.js
  • src/js/media/views/frame/manage.js
  • src/js/media/views/frame/media-details.js
  • src/js/media/views/frame/post.js
  • src/js/media/views/frame/select.js
  • src/js/media/views/frame/video-details.js
  • src/js/media/views/iframe.js
  • src/js/media/views/image-details.js
  • src/js/media/views/label.js
  • src/js/media/views/media-details.js
  • src/js/media/views/media-frame.js
  • src/js/media/views/menu-item.js
  • src/js/media/views/menu.js
  • src/js/media/views/modal.js
  • src/js/media/views/priority-list.js
  • src/js/media/views/router-item.js
  • src/js/media/views/router.js
  • src/js/media/views/search.js (@boblinthorst)
  • src/js/media/views/selection.js
  • src/js/media/views/settings.js
  • src/js/media/views/settings/attachment-display.js
  • src/js/media/views/settings/gallery.js
  • src/js/media/views/settings/playlist.js
  • src/js/media/views/sidebar.js
  • src/js/media/views/site-icon-cropper.js
  • src/js/media/views/site-icon-preview.js
  • src/js/media/views/toolbar.js
  • src/js/media/views/toolbar/embed.js
  • src/js/media/views/toolbar/select.js
  • src/js/media/views/uploader/editor.js
  • src/js/media/views/uploader/inline.js
  • src/js/media/views/uploader/status-error.js
  • src/js/media/views/uploader/status.js
  • src/js/media/views/uploader/window.js
  • src/js/media/views/video-details.js
  • src/js/media/views/view.js
  • src/js/_enqueues/lib/quicktags.js
  • src/js/_enqueues/wp/shortcode.js (@hanopcan)
  • src/js/_enqueues/lib/cookies.js
  • src/js/_enqueues/wp/a11y.js
  • src/js/_enqueues/lib/ajax-response.js
  • src/js/_enqueues/wp/api.js
  • src/js/_enqueues/lib/auth-check.js (@pskli)
  • src/js/_enqueues/wp/custom-header.js
  • src/js/_enqueues/lib/embed-template.js
  • src/js/_enqueues/wp/embed.js
  • src/js/_enqueues/wp/emoji.js (@igorsch, @nicollle)
  • src/js/_enqueues/lib/list-revisions.js
  • src/js/_enqueues/lib/lists.js
  • src/js/_enqueues/lib/pointer.js (@maartenleenders)
  • src/js/_enqueues/wp/util.js
  • src/js/_enqueues/lib/link.js

Current status:

Happy documenting!

#inline-docs

#javascript

JS docs initiative: Add inline-docs for JavaScript!

There is a new post which you can comment on to claim files.

We are pleased to announce the JS docs initiative! It’s an ongoing effort 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 better documentation will help this work progress as smoothly as possible.

In the last few months, we’ve fixed the JavaScript documentation standards by discussing sticking points in the #core-js weekly meeting. The structural documentation of all the Backbone classes has also been fixed (major props to @herregroen for fixing this).

At the bottom is a list of every first-party JavaScript file in core. Files with a checkmark have been patched and are considered completed. Files marked with (username #xxxxx) are already claimed, and being worked on.

Directly below is the process we’re using to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.

How to contribute

  1. Familiarize yourself with the JavaScript documentation standard, as well as the formatting guidelines and documenting tips.
  2. Check the list first to make sure the file you want to work on hasn’t already been claimed.
  3. Update your local WordPress SVN (use svn up) or Git repo (use git pull) to the latest version of WordPress trunk.
  4. Create a new ticket on Trac for the file.
    • Format the title as “JSDoc: 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 javascript focuses.
  5. Edit the file, and make a patch. Please make sure you create the patch from the root directory of your WordPress SVN or Git checkout.
  6. Upload your patch to the Trac ticket you created, and add the keyword “has-patch”.

We’d like to welcome everyone to start contributing inline documentation! You can start contributing by picking a file from the list of unclaimed files below and claiming it in the comments. Please also see the JS docs handbook page for a step by step guide on how to get started.

Note: Note: To give everyone a chance to claim a file and to ensure the work proceeds as quickly as possible, please only work on one file at a time.

Determining the since version

We use JSDoc’s @since tag to indicate when a particular function was added to WordPress core. When you are documenting a function, you will also need to identify when that function was first introduced.

The recommended tool to use when searching for the version something was added to WordPress is svn blame. An additional resource for hooks is the WordPress Hooks Database. If, after using these tools, the version number cannot be determined, use @since Unknown.

If you use the git repository of WordPress you can also use git to determine the @since version. Either use git blame or the GitHub blame function. Once you have the commit hash which introduced a piece of code you can find out the version by using git tag --contains [commit-hash]. This will list all versions a certain commit has been shipped in. The lowest version is then what you put after the @since annotation.

Note: Make sure that the commit you found it the actual commit where a piece of code was introduced. JavaScript files have been moved around a lot in the past, so make sure to take that into account.

Note: All @since tags should follow the three digit x.x.x format.

Keeping Discussions Focused:

Any discussion about the specifics of a patch itself should happen on Trac. Any discussion about the broader scope of what we’re trying to do should take place during the weekly devchat. That’s either #core-js or #core.

Files needing patches:

Checked files are completed, marked files are claimed

  • wp-admin/js/accordion.js
  • wp-admin/js/bookmarklet.js
  • wp-admin/js/color-picker.js
  • wp-admin/js/comment.js
  • wp-admin/js/common.js
  • wp-admin/js/custom-background.js
  • wp-admin/js/custom-header.js
  • wp-admin/js/customize-controls.js (@jjcomack)
  • wp-admin/js/customize-nav-menus.js
  • wp-admin/js/customize-widgets.js
  • wp-admin/js/edit-comments.js (@atimmer)
  • wp-admin/js/editor-expand.js
  • wp-admin/js/editor.js
  • wp-admin/js/gallery.js (@hunkriyaz)
  • wp-admin/js/image-edit.js
  • wp-admin/js/inline-edit-post.js
  • wp-admin/js/inline-edit-tax.js
  • wp-admin/js/language-chooser.js
  • wp-admin/js/link.js
  • wp-admin/js/media-gallery.js
  • wp-admin/js/media-upload.js
  • wp-admin/js/media.js
  • wp-admin/js/nav-menu.js
  • wp-admin/js/password-strength-meter.js
  • wp-admin/js/plugin-install.js
  • wp-admin/js/post.js
  • wp-admin/js/postbox.js
  • wp-admin/js/press-this.js
  • wp-admin/js/revisions.js
  • wp-admin/js/set-post-thumbnail.js
  • wp-admin/js/svg-painter.js
  • wp-admin/js/tags-box.js (@carolinegeven)
  • wp-admin/js/tags.js
  • wp-admin/js/theme.js
  • wp-admin/js/updates.js
  • wp-admin/js/user-profile.js
  • wp-admin/js/user-suggest.js (@timhavinga)
  • wp-admin/js/widgets.js
  • wp-admin/js/word-count.js
  • wp-admin/js/wp-fullscreen-stub.js
  • wp-admin/js/xfn.js (@kapteinbluf)
  • wp-includes/js/admin-bar.js
  • wp-includes/js/autosave.js
  • wp-includes/js/comment-reply.js
  • wp-includes/js/customize-base.js
  • wp-includes/js/customize-loader.js
  • wp-includes/js/customize-models.js
  • wp-includes/js/customize-preview-nav-menus.js
  • wp-includes/js/customize-preview-widgets.js
  • wp-includes/js/customize-preview.js
  • wp-includes/js/customize-selective-refresh.js
  • wp-includes/js/customize-views.js
  • wp-includes/js/dashboard.js
  • wp-includes/js/heartbeat.js
  • wp-includes/js/mce-view.js
  • wp-includes/js/media-audiovideo.js
  • wp-includes/js/media-editor.js
  • wp-includes/js/media-grid.js
  • wp-includes/js/media-models.js
  • wp-includes/js/media-views.js
  • wp-includes/js/media/audiovideo.manifest.js
  • wp-includes/js/media/controllers/audio-details.js
  • wp-includes/js/media/controllers/collection-add.js
  • wp-includes/js/media/controllers/collection-edit.js
  • wp-includes/js/media/controllers/cropper.js
  • wp-includes/js/media/controllers/customize-image-cropper.js
  • wp-includes/js/media/controllers/edit-attachment-metadata.js
  • wp-includes/js/media/controllers/edit-image.js
  • wp-includes/js/media/controllers/embed.js
  • wp-includes/js/media/controllers/featured-image.js
  • wp-includes/js/media/controllers/gallery-add.js (@atimmer)
  • wp-includes/js/media/controllers/gallery-edit.js (@manuelaugustin)
  • wp-includes/js/media/controllers/image-details.js
  • wp-includes/js/media/controllers/library.js
  • wp-includes/js/media/controllers/media-library.js
  • wp-includes/js/media/controllers/region.js
  • wp-includes/js/media/controllers/replace-image.js
  • wp-includes/js/media/controllers/site-icon-cropper.js
  • wp-includes/js/media/controllers/state-machine.js
  • wp-includes/js/media/controllers/state.js
  • wp-includes/js/media/controllers/video-details.js
  • wp-includes/js/media/grid.manifest.js
  • wp-includes/js/media/models.manifest.js
  • wp-includes/js/media/models/attachment.js
  • wp-includes/js/media/models/post-image.js
  • wp-includes/js/media/models/post-media.js
  • wp-includes/js/media/models/query.js
  • wp-includes/js/media/models/selection.js
  • wp-includes/js/media/routers/manage.js
  • wp-includes/js/media/utils/selection-sync.js
  • wp-includes/js/media/views.manifest.js
  • wp-includes/js/media/views/attachment-compat.js
  • wp-includes/js/media/views/attachment-filters.js
  • wp-includes/js/media/views/attachment-filters/all.js
  • wp-includes/js/media/views/attachment-filters/date.js
  • wp-includes/js/media/views/attachment-filters/uploaded.js
  • wp-includes/js/media/views/attachment.js
  • wp-includes/js/media/views/attachment/details-two-column.js
  • wp-includes/js/media/views/attachment/details.js (@maartenleenders)
  • wp-includes/js/media/views/attachment/edit-library.js
  • wp-includes/js/media/views/attachment/edit-selection.js
  • wp-includes/js/media/views/attachment/library.js
  • wp-includes/js/media/views/attachment/selection.js
  • wp-includes/js/media/views/attachments.js
  • wp-includes/js/media/views/attachments/browser.js
  • wp-includes/js/media/views/attachments/selection.js
  • wp-includes/js/media/views/audio-details.js
  • wp-includes/js/media/views/button-group.js
  • wp-includes/js/media/views/button.js
  • wp-includes/js/media/views/button/delete-selected-permanently.js
  • wp-includes/js/media/views/button/delete-selected.js
  • wp-includes/js/media/views/button/select-mode-toggle.js
  • wp-includes/js/media/views/cropper.js (@kapteinbluf)
  • wp-includes/js/media/views/edit-image-details.js
  • wp-includes/js/media/views/edit-image.js
  • wp-includes/js/media/views/embed.js
  • wp-includes/js/media/views/embed/image.js
  • wp-includes/js/media/views/embed/link.js
  • wp-includes/js/media/views/embed/url.js
  • wp-includes/js/media/views/focus-manager.js
  • wp-includes/js/media/views/frame.js
  • wp-includes/js/media/views/frame/audio-details.js
  • wp-includes/js/media/views/frame/edit-attachments.js
  • wp-includes/js/media/views/frame/image-details.js
  • wp-includes/js/media/views/frame/manage.js
  • wp-includes/js/media/views/frame/media-details.js
  • wp-includes/js/media/views/frame/post.js
  • wp-includes/js/media/views/frame/select.js
  • wp-includes/js/media/views/frame/video-details.js
  • wp-includes/js/media/views/iframe.js
  • wp-includes/js/media/views/image-details.js
  • wp-includes/js/media/views/label.js
  • wp-includes/js/media/views/media-details.js
  • wp-includes/js/media/views/media-frame.js
  • wp-includes/js/media/views/menu-item.js
  • wp-includes/js/media/views/menu.js
  • wp-includes/js/media/views/modal.js
  • wp-includes/js/media/views/priority-list.js
  • wp-includes/js/media/views/router-item.js
  • wp-includes/js/media/views/router.js
  • wp-includes/js/media/views/search.js
  • wp-includes/js/media/views/selection.js
  • wp-includes/js/media/views/settings.js
  • wp-includes/js/media/views/settings/attachment-display.js
  • wp-includes/js/media/views/settings/gallery.js
  • wp-includes/js/media/views/settings/playlist.js
  • wp-includes/js/media/views/sidebar.js
  • wp-includes/js/media/views/site-icon-cropper.js
  • wp-includes/js/media/views/site-icon-preview.js
  • wp-includes/js/media/views/spinner.js (@avillegasn)
  • wp-includes/js/media/views/toolbar.js
  • wp-includes/js/media/views/toolbar/embed.js
  • wp-includes/js/media/views/toolbar/select.js
  • wp-includes/js/media/views/uploader/editor.js
  • wp-includes/js/media/views/uploader/inline.js
  • wp-includes/js/media/views/uploader/status-error.js
  • wp-includes/js/media/views/uploader/status.js
  • wp-includes/js/media/views/uploader/window.js
  • wp-includes/js/media/views/video-details.js
  • wp-includes/js/media/views/view.js
  • wp-includes/js/quicktags.js
  • wp-includes/js/shortcode.js
  • wp-includes/js/tw-sack.js
  • wp-includes/js/utils.js
  • wp-includes/js/wp-a11y.js
  • wp-includes/js/wp-ajax-response.js
  • wp-includes/js/wp-api.js
  • wp-includes/js/wp-auth-check.js
  • wp-includes/js/wp-backbone.js
  • wp-includes/js/wp-custom-header.js
  • wp-includes/js/wp-embed-template.js
  • wp-includes/js/wp-embed.js
  • wp-includes/js/wp-emoji-loader.js (@dfangstrom)
  • wp-includes/js/wp-emoji.js (@igorsch, @nicollle)
  • wp-includes/js/wp-list-revisions.js
  • wp-includes/js/wp-lists.js
  • wp-includes/js/wp-pointer.js (@maartenleenders)
  • wp-includes/js/wp-util.js
  • wp-includes/js/wpdialog.js (@lisannekluitmans)
  • wp-includes/js/wplink.js
  • wp-includes/js/zxcvbn-async.js (@lisannekluitmans)

Current status:

Happy documenting!

#inline-docs

#javascript