Changeset 26987

Timestamp:

01/21/2014 03:54:27 PM (11 years ago)

Author:

wonderboymusic

Message:

Elaborate on JSDoc blocks for media-editor.js.

See #26870.

File:

• trunk/src/wp-includes/js/media-editor.js (modified) (17 diffs)

trunk/src/wp-includes/js/media-editor.js

@@ -22 +22 @@
          * @global wp.media.view.settings.defaultProps
          *
-         * @param {Object} props
-         * @param {Object} attachment
+         * @param {Object} props Attachment details (align, link, size, etc).
+         * @param {Object} attachment The attachment object, media version of Post.
          * @returns {Object} Joined props
          */
@@ -103 +103 @@
          * @global wp.html.string
          *
-         * @param {Object} props
-         * @param {Object} attachment
+         * @param {Object} props Attachment details (align, link, size, etc).
+         * @param {Object} attachment The attachment object, media version of Post.
          * @returns {string} The link markup
          */
@@ -129 +129 @@
          * Create an Audio shortcode
          *
-         * @param {Object} props
-         * @param {Object} attachment
+         * @param {Object} props Attachment details (align, link, size, etc).
+         * @param {Object} attachment The attachment object, media version of Post.
          * @returns {string} The audio shortcode
          */
@@ -139 +139 @@
          * Create a Video shortcode
          *
-         * @param {Object} props
-         * @param {Object} attachment
+         * @param {Object} props Attachment details (align, link, size, etc).
+         * @param {Object} attachment The attachment object, media version of Post.
          * @returns {string} The video shortcode
          */
@@ -155 +155 @@
          *
          * @param {string} type The shortcode tag name: 'audio' or 'video'.
-         * @param {Object} props
-         * @param {Object} attachment
+         * @param {Object} props Attachment details (align, link, size, etc).
+         * @param {Object} attachment The attachment object, media version of Post.
          * @returns {string} The media shortcode
          */
@@ -200 +200 @@
          * @global wp.shortcode
          *
-         * @param {Object} props
-         * @param {Object} attachment
+         * @param {Object} props Attachment details (align, link, size, etc).
+         * @param {Object} attachment The attachment object, media version of Post.
          * @returns {string}
          */
@@ -305 +305 @@
              * @global wp.media.query
              *
-             * @param {Object} shortcode
-             * @returns {Object}
+             * @param {wp.shortcode} shortcode
+             * @returns {wp.media.model.Attachments} A Backbone.Collection containing
+             *  the images belonging to a gallery. The 'gallery' prop is a Backbone.Model
+             *  containing the 'props' for the gallery.
              */
             attachments: function( shortcode ) {
@@ -364 +366 @@
 
             /**
+             * Triggered when clicking 'Insert Gallery' pr 'Update Gallery'
+             *
              * @global wp.shortcode
              * @global wp.media.model.Attachments
              *
-             * @param {Object} attachments
+             * @param {wp.media.model.Attachments} attachments A Backbone.Collection containing
+             *  the images belonging to a gallery. The 'gallery' prop is a Backbone.Model
+             *  containing the 'props' for the gallery.
              * @returns {wp.shortcode}
              */
@@ -429 +435 @@
             },
             /**
+             * Triggered when double-clicking a Gallery shortcode placeholder
+             *   in the editor
+             *
              * @global wp.shortcode
              * @global wp.media.model.Selection
@@ -434 +443 @@
              *
              * @param {string} content
-             * @returns {wp.media.view.MediaFrame} A media workflow.
+             * @returns {wp.media.view.MediaFrame.Select} A media workflow.
              */
             edit: function( content ) {
@@ -500 +509 @@
          * @global wp.media.view.settings
          *
-         * @returns {wp.media.view.settings.post.featuredImageId|Number}
+         * @returns {wp.media.view.settings.post.featuredImageId|number}
          */
         get: function() {
@@ -535 +544 @@
          * @global wp.media.view.l10n
          *
-         * @returns {wp.media.view.MediaFrame} A media workflow.
+         * @returns {wp.media.view.MediaFrame.Select} A media workflow.
          */
         frame: function() {
@@ -600 +609 @@
          * @global tinymce
          * @global QTags
+         * @global wpActiveEditor
          *
          * @param {string} html
@@ -648 +658 @@
          * @param {Object} [options={}]
          *
-         * @returns {wp.media.view.MediaFrame} A media workflow.
+         * @returns {wp.media.view.MediaFrame.Select} A media workflow.
          */
         add: function( id, options ) {
@@ -731 +741 @@
          * @global tinymce
          *
-         * @param {string} id
-         * @returns {wpActiveEditor|String|tinymce.activeEditor.id}
+         * @param {string} [id='']
+         * @returns {wpActiveEditor|string|tinymce.activeEditor.id}
          */
         id: function( id ) {
@@ -773 +783 @@
         send: {
             /**
+             * Called when sending an attachment to the editor
+             *   from the medial modal.
+             *
              * @global wp.media.view.settings
              * @global wp.media.post
              *
-             * @param {Object} props
-             * @param {Object} attachment
+             * @param {Object} props Attachment details (align, link, size, etc).
+             * @param {Object} attachment The attachment object, media version of Post.
              * @returns {Promise}
              */
@@ -829 +842 @@
             },
             /**
+             * Called when 'Insert From URL' source is not an image. Example: YouTube url.
+             *
              * @global wp.media.view.settings
              *