Docs: Remove @summary tags from JSDoc.

As decided in the JavaScript core chat. With a few reasons: * It is visually cleaner when reading the source. * This bring the JavaScript documentation closer to the PHP documentation. The only disadvantage is that the JSDoc parser doesn't split out the summary and the description in the new format. We've decided to solve this when building the JavaScript documentation parser. Props herregroen. Fixes #42901. Built from https://develop.svn.wordpress.org/trunk@42411 git-svn-id: http://core.svn.wordpress.org/trunk@42240 1a063a9b-81f0-0310-95a4-ce76da25c4cd
lenonleite · Dec 18, 2017 · f6a37e7 · f6a37e7
1 parent 65b715c
commit f6a37e7
Show file tree

Hide file tree

Showing 23 changed files with 323 additions and 354 deletions.
diff --git a/wp-admin/js/color-picker.js b/wp-admin/js/color-picker.js
@@ -10,8 +10,6 @@
 		_wrappingLabelText = '<span class="screen-reader-text"></span>';
 
 	/**
-	 * @summary Creates a jQuery UI color picker.
-	 *
 	 * Creates a jQuery UI color picker that is used in the theme customizer.
 	 *
 	 * @class $.widget.wp.wpColorPicker
@@ -31,7 +29,7 @@
 			slider: 'horizontal'
 		},
 		/**
-		 * @summary Creates a color picker that only allows you to adjust the hue.
+		 * Creates a color picker that only allows you to adjust the hue.
 		 *
 		 * @since 3.5.0
 		 *
@@ -56,7 +54,7 @@
 				hide: false,
 				color: color,
 				/**
-				 * @summary Handles the onChange event if one has been defined in the options.
+				 * Handles the onChange event if one has been defined in the options.
 				 *
 				 * @ignore
 				 *
@@ -75,8 +73,6 @@
 			} );
 		},
 		/**
-		 * @summary Creates the color picker.
-		 *
 		 * Creates the color picker, sets default values, css classes and wraps it all in HTML.
 		 *
 		 * @since 3.5.0
@@ -176,8 +172,6 @@
 				mode: self.options.mode,
 				palettes: self.options.palettes,
 				/**
-				 * @summary Handles the onChange event if one has been defined in the options.
-				 *
 				 * Handles the onChange event if one has been defined in the options and additionally
 				 * sets the background color for the toggler element.
 				 *
@@ -208,7 +202,7 @@
 			}
 		},
 		/**
-		 * @summary Binds event listeners to the color picker.
+		 * Binds event listeners to the color picker.
 		 *
 		 * @since 3.5.0
 		 *
@@ -220,7 +214,7 @@
 			var self = this;
 
 			/**
-			 * @summary Prevent any clicks inside this widget from leaking to the top and closing it.
+			 * Prevent any clicks inside this widget from leaking to the top and closing it.
 			 *
 			 * @since 3.5.0
 			 *
@@ -233,7 +227,7 @@
 			});
 
 			/**
-			 * @summary Open or close the color picker depending on the class.
+			 * Open or close the color picker depending on the class.
 			 *
 			 * @since 3.5
 			 */
@@ -246,8 +240,6 @@
 			});
 
 			/**
-			 * @summary Checks if value is empty when changing the color in the color picker.
-			 *
 			 * Checks if value is empty when changing the color in the color picker.
 			 * If so, the background color is cleared.
 			 *
@@ -271,8 +263,6 @@
 			});
 
 			/**
-			 * @summary Enables the user to clear or revert the color in the color picker.
-			 *
 			 * Enables the user to either clear the color in the color picker or revert back to the default color.
 			 *
 			 * @since 3.5.0
@@ -295,7 +285,7 @@
 			});
 		},
 		/**
-		 * @summary Opens the color picker dialog.
+		 * Opens the color picker dialog.
 		 *
 		 * @since 3.5.0
 		 *
@@ -311,7 +301,7 @@
 			$( 'body' ).trigger( 'click.wpcolorpicker' ).on( 'click.wpcolorpicker', this.close );
 		},
 		/**
-		 * @summary Closes the color picker dialog.
+		 * Closes the color picker dialog.
 		 *
 		 * @since 3.5.0
 		 *
@@ -327,8 +317,6 @@
 			$( 'body' ).off( 'click.wpcolorpicker', this.close );
 		},
 		/**
-		 * @summary Returns iris object or sets new color.
-		 *
 		 * Returns the iris object if no new color is provided. If a new color is provided, it sets the new color.
 		 *
 		 * @param newColor {string|*} The new color to use. Can be undefined.
@@ -344,8 +332,6 @@
 			this.element.iris( 'option', 'color', newColor );
 		},
 		/**
-		 * @summary Returns iris object or sets new default color.
-		 *
 		 * Returns the iris object if no new default color is provided.
 		 * If a new default color is provided, it sets the new default color.
 		 *

diff --git a/wp-admin/js/comment.js b/wp-admin/js/comment.js
@@ -1,7 +1,7 @@
 /* global postboxes, commentL10n */
 
 /**
- * @summary Binds to the document ready event.
+ * Binds to the document ready event.
  *
  * @since 2.5.0
  *
@@ -18,7 +18,7 @@ jQuery(document).ready( function($) {
 		$edittimestamp = $timestampdiv.siblings( 'a.edit-timestamp' );
 
 	/**
-	 * @summary Adds event that opens the time stamp form if the form is hidden.
+	 * Adds event that opens the time stamp form if the form is hidden.
 	 *
 	 * @listens $edittimestamp:click
 	 *
@@ -37,7 +37,7 @@ jQuery(document).ready( function($) {
 	});
 
 	/**
-	 * @summary Resets the time stamp values when the cancel button is clicked.
+	 * Resets the time stamp values when the cancel button is clicked.
 	 *
 	 * @listens .cancel-timestamp:click
 	 *
@@ -59,7 +59,7 @@ jQuery(document).ready( function($) {
 	});
 
 	/**
-	 * @summary Sets the time stamp values when the ok button is clicked.
+	 * Sets the time stamp values when the ok button is clicked.
 	 *
 	 * @listens .save-timestamp:click
 	 *