Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

git-svn-id: https://develop.svn.wordpress.org/trunk@47122 602fd350-edb4-49c9-b593-d223f7449a82

Author: SergeyBiryukov

Gruntfile.js

@@ -43,7 +43,7 @@ module.exports = function(grunt) {
 
 	// Load tasks.
 	require('matchdep').filterDev(['grunt-*', '!grunt-legacy-util']).forEach( grunt.loadNpmTasks );
-	// Load legacy utils
+	// Load legacy utils.
 	grunt.util = require('grunt-legacy-util');
 
 	// Project configuration.
@@ -144,7 +144,7 @@ module.exports = function(grunt) {
 							'!assets/**', // Assets is extracted into separate copy tasks.
 							'!js/**', // JavaScript is extracted into separate copy tasks.
 							'!.{svn,git}', // Exclude version control folders.
-							'!wp-includes/version.php', // Exclude version.php
+							'!wp-includes/version.php', // Exclude version.php.
 							'!**/*.map', // The build doesn't need .map files.
 							'!index.php', '!wp-admin/index.php',
 							'!_index.php', '!wp-admin/_index.php'
@@ -168,7 +168,7 @@ module.exports = function(grunt) {
 						[ WORKING_DIR + 'wp-includes/js/clipboard.js' ]: [ './node_modules/clipboard/dist/clipboard.js' ],
 						[ WORKING_DIR + 'wp-includes/js/hoverIntent.js' ]: [ './node_modules/jquery-hoverintent/jquery.hoverIntent.js' ],
 
-						// Renamed to avoid conflict with jQuery hoverIntent.min.js (after minifying)
+						// Renamed to avoid conflict with jQuery hoverIntent.min.js (after minifying).
 						[ WORKING_DIR + 'wp-includes/js/hoverintent-js.min.js' ]: [ './node_modules/hoverintent/dist/hoverintent.min.js' ],
 						[ WORKING_DIR + 'wp-includes/js/imagesloaded.min.js' ]: [ './node_modules/imagesloaded/imagesloaded.pkgd.min.js' ],
 						[ WORKING_DIR + 'wp-includes/js/jquery/jquery-migrate.js' ]: [ './node_modules/jquery-migrate/dist/jquery-migrate.js' ],
@@ -448,7 +448,7 @@ module.exports = function(grunt) {
 		},
 		rtlcss: {
 			options: {
-				// rtlcss options
+				// rtlcss options.
 				opts: {
 					clean: false,
 					processUrls: { atrule: true, decl: false },
@@ -516,7 +516,7 @@ module.exports = function(grunt) {
 					'!wp-includes/css/*.min.css',
 					'!wp-includes/css/dist',
 
-					// Exceptions
+					// Exceptions.
 					'!wp-includes/css/dashicons.css',
 					'!wp-includes/css/wp-embed-template.css',
 					'!wp-includes/css/wp-embed-template-ie.css'
@@ -558,7 +558,7 @@ module.exports = function(grunt) {
 				src: [
 					'twenty*/**/*.js',
 					'!twenty{eleven,twelve,thirteen}/**',
-					// Third party scripts
+					// Third party scripts.
 					'!twenty{fourteen,fifteen,sixteen}/js/html5.js',
 					'!twentyseventeen/assets/js/html5.js',
 					'!twentyseventeen/assets/js/jquery.scrollTo.js',
@@ -575,35 +575,36 @@ module.exports = function(grunt) {
 				cwd: SOURCE_DIR,
 				src: [
 					'js/_enqueues/**/*.js',
-					// Third party scripts
+					// Third party scripts.
 					'!js/_enqueues/vendor/**/*.js'
 				],
-				// Remove once other JSHint errors are resolved
+				// Remove once other JSHint errors are resolved.
 				options: {
 					curly: false,
 					eqeqeq: false
 				},
-				// Limit JSHint's run to a single specified file:
-				//
-				//    grunt jshint:core --file=filename.js
-				//
-				// Optionally, include the file path:
-				//
-				//    grunt jshint:core --file=path/to/filename.js
-				//
+				/*
+				 * Limit JSHint's run to a single specified file:
+				 *
+				 *    grunt jshint:core --file=filename.js
+				 *
+				 * Optionally, include the file path:
+				 *
+				 *    grunt jshint:core --file=path/to/filename.js
+				 */
 				filter: function( filepath ) {
 					var index, file = grunt.option( 'file' );
 
-					// Don't filter when no target file is specified
+					// Don't filter when no target file is specified.
 					if ( ! file ) {
 						return true;
 					}
 
-					// Normalize filepath for Windows
+					// Normalize filepath for Windows.
 					filepath = filepath.replace( /\\/g, '/' );
 					index = filepath.lastIndexOf( '/' + file );
 
-					// Match only the filename passed from cli
+					// Match only the filename passed from cli.
 					if ( filepath === file || ( -1 !== index && index === filepath.length - ( file.length + 1 ) ) ) {
 						return true;
 					}
@@ -618,22 +619,23 @@ module.exports = function(grunt) {
 					'**/*.js',
 					'!**/*.min.js'
 				],
-				// Limit JSHint's run to a single specified plugin directory:
-				//
-				//    grunt jshint:plugins --dir=foldername
-				//
+				/*
+				 * Limit JSHint's run to a single specified plugin directory:
+				 *
+				 *    grunt jshint:plugins --dir=foldername
+				 */
 				filter: function( dirpath ) {
 					var index, dir = grunt.option( 'dir' );
 
-					// Don't filter when no target folder is specified
+					// Don't filter when no target folder is specified.
 					if ( ! dir ) {
 						return true;
 					}
 
 					dirpath = dirpath.replace( /\\/g, '/' );
 					index = dirpath.lastIndexOf( '/' + dir );
 
-					// Match only the folder name passed from cli
+					// Match only the folder name passed from cli.
 					if ( -1 !== index ) {
 						return true;
 					}
@@ -703,12 +705,12 @@ module.exports = function(grunt) {
 					'wp-includes/js/tinymce/plugins/wordpress/plugin.js',
 					'wp-includes/js/tinymce/plugins/wp*/plugin.js',
 
-					// Exceptions
+					// Exceptions.
 					'!**/*.min.js',
 					'!wp-admin/js/custom-header.js', // Why? We should minify this.
 					'!wp-admin/js/farbtastic.js',
 					'!wp-includes/js/swfobject.js',
-					'!wp-includes/js/wp-embed.js' // We have extra options for this, see uglify:embed
+					'!wp-includes/js/wp-embed.js' // We have extra options for this, see uglify:embed.
 				]
 			},
 			embed: {
@@ -1030,41 +1032,41 @@ module.exports = function(grunt) {
 
 								grunt.log.writeln( 'Fetching list of Twemoji files...' );
 
-								// Fetch a list of the files that Twemoji supplies
+								// Fetch a list of the files that Twemoji supplies.
 								files = spawn( 'svn', [ 'ls', 'https://github.com/twitter/twemoji.git/trunk/assets/svg' ] );
 								if ( 0 !== files.status ) {
 									grunt.fatal( 'Unable to fetch Twemoji file list' );
 								}
 
 								entities = files.stdout.toString();
 
-								// Tidy up the file list
+								// Tidy up the file list.
 								entities = entities.replace( /\.svg/g, '' );
 								entities = entities.replace( /^$/g, '' );
 
-								// Convert the emoji entities to HTML entities
+								// Convert the emoji entities to HTML entities.
 								partials = entities = entities.replace( /([a-z0-9]+)/g, '&#x$1;' );
 
-								// Remove the hyphens between the HTML entities
+								// Remove the hyphens between the HTML entities.
 								entities = entities.replace( /-/g, '' );
 
-								// Sort the entities list by length, so the longest emoji will be found first
+								// Sort the entities list by length, so the longest emoji will be found first.
 								emojiArray = entities.split( '\n' ).sort( function ( a, b ) {
 									return b.length - a.length;
 								} );
 
-								// Convert the entities list to PHP array syntax
+								// Convert the entities list to PHP array syntax.
 								entities = '\'' + emojiArray.filter( function( val ) {
 									return val.length >= 8 ? val : false ;
 								} ).join( '\', \'' ) + '\'';
 
-								// Create a list of all characters used by the emoji list
+								// Create a list of all characters used by the emoji list.
 								partials = partials.replace( /-/g, '\n' );
 
-								// Set automatically removes duplicates
+								// Set automatically removes duplicates.
 								partialsSet = new Set( partials.split( '\n' ) );
 
-								// Convert the partials list to PHP array syntax
+								// Convert the partials list to PHP array syntax.
 								partials = '\'' + Array.from( partialsSet ).filter( function( val ) {
 									return val.length >= 8 ? val : false ;
 								} ).join( '\', \'' ) + '\'';
@@ -1158,7 +1160,7 @@ module.exports = function(grunt) {
 		}
 	});
 
-	// Allow builds to be minimal
+	// Allow builds to be minimal.
 	if( grunt.option( 'minimal-copy' ) ) {
 		var copyFilesOptions = grunt.config.get( 'copy.files.files' );
 		copyFilesOptions[0].src.push( '!wp-content/plugins/**' );

phpcompat.xml.dist

@@ -4,7 +4,7 @@
 
 	<rule ref="PHPCompatibilityWP"/>
 
-	<!-- WordPress Core currently supports PHP 5.6+ -->
+	<!-- WordPress Core currently supports PHP 5.6+. -->
 	<config name="testVersion" value="5.6-"/>
 
 	<!-- Only scan PHP files. -->
@@ -25,7 +25,7 @@
 	<!-- Check up to 20 files simultaneously. -->
 	<arg name="parallel" value="20"/>
 
-	<!-- Show sniff codes in all reports -->
+	<!-- Show sniff codes in all reports. -->
 	<arg value="ps"/>
 
 	<!-- For now, only the files in src are scanned. -->

phpcs.xml.dist

@@ -20,7 +20,7 @@
 	<!-- Check up to 20 files simultaneously. -->
 	<arg name="parallel" value="20"/>
 
-	<!-- Show sniff codes in all reports -->
+	<!-- Show sniff codes in all reports. -->
 	<arg value="ps"/>
 
 	<file>.</file>
@@ -48,7 +48,7 @@
 	<rule ref="WordPress.NamingConventions.ValidVariableName">
 		<properties>
 			<property name="customPropertiesWhitelist" type="array">
-				<!-- From database structure queries -->
+				<!-- From database structure queries. -->
 				<element value="Collation"/>
 				<element value="Column_name"/>
 				<element value="Default"/>
@@ -62,22 +62,22 @@
 				<element value="Null"/>
 				<element value="Sub_part"/>
 				<element value="Type"/>
-				<!-- From plugin/theme data -->
+				<!-- From plugin/theme data. -->
 				<element value="authorAndUri"/>
 				<element value="Name"/>
 				<element value="Version"/>
-				<!-- From the result of wp_xmlrpc_server::wp_getPageList() -->
+				<!-- From the result of wp_xmlrpc_server::wp_getPageList(). -->
 				<element value="dateCreated"/>
 
-				<!-- From DOMDocument -->
+				<!-- From DOMDocument. -->
 				<element value="childNodes"/>
 				<element value="formatOutput"/>
 				<element value="nodeName"/>
 				<element value="nodeType"/>
 				<element value="parentNode"/>
 				<element value="preserveWhiteSpace"/>
 				<element value="textContent"/>
-				<!-- From PHPMailer -->
+				<!-- From PHPMailer. -->
 				<element value="AltBody"/>
 				<element value="Body"/>
 				<element value="CharSet"/>
@@ -89,11 +89,11 @@
 				<element value="MIMEHeader"/>
 				<element value="Sender"/>
 				<element value="Subject"/>
-				<!-- From PHPUnit_Util_Getopt -->
+				<!-- From PHPUnit_Util_Getopt. -->
 				<element value="longOptions"/>
-				<!-- From POP3 -->
+				<!-- From POP3. -->
 				<element value="ERROR"/>
-				<!-- From ZipArchive -->
+				<!-- From ZipArchive. -->
 				<element value="numFiles"/>
 			</property>
 		</properties>
@@ -102,7 +102,7 @@
 	<!-- Exclude the build folder in the current directory, as Travis puts the checkout in a build directory. -->
 	<exclude-pattern type="relative">^build/*</exclude-pattern>
 
-	<!-- Directories and third party library exclusions -->
+	<!-- Directories and third party library exclusions. -->
 	<exclude-pattern>/node_modules/*</exclude-pattern>
 	<exclude-pattern>/vendor/*</exclude-pattern>
 
@@ -140,7 +140,7 @@
 
 	<exclude-pattern>/tests/phpunit/includes/speed-trap-listener\.php</exclude-pattern>
 
-	<!-- Test data and fixtures -->
+	<!-- Test data and fixtures. -->
 	<exclude-pattern>/tests/phpunit/build*</exclude-pattern>
 	<exclude-pattern>/tests/phpunit/data/*</exclude-pattern>
 
@@ -214,7 +214,7 @@
 	<rule ref="WordPress.Files.FileName">
 		<properties>
 			<property name="custom_test_class_whitelist" type="array">
-				<!-- Test case parent classes -->
+				<!-- Test case parent classes. -->
 				<element value="WP_UnitTestCase"/>
 				<element value="WP_Ajax_UnitTestCase"/>
 				<element value="WP_Canonical_UnitTestCase"/>
@@ -229,7 +229,7 @@
 				<element value="WP_Import_UnitTestCase"/>
 				<element value="Tests_Query_Conditionals"/>
 
-				<!-- Mock classes -->
+				<!-- Mock classes. -->
 				<element value="Spy_REST_Server"/>
 				<element value="WP_REST_Test_Controller"/>
 				<element value="WP_Image_Editor_Mock"/>
@@ -238,7 +238,7 @@
 				<element value="MockAction"/>
 				<element value="WP_Object_Cache"/>
 
-				<!-- PHPUnit helpers -->
+				<!-- PHPUnit helpers. -->
 				<element value="TracTickets"/>
 				<element value="WP_PHPUnit_Util_Getopt"/>
 				<element value="PHPUnit_Util_Test"/>
@@ -270,7 +270,7 @@
 		</properties>
 	</rule>
 
-	<!-- Assignments in while conditions are a valid method of looping over iterables -->
+	<!-- Assignments in while conditions are a valid method of looping over iterables. -->
 	<rule ref="WordPress.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition">
 		<exclude-pattern>*</exclude-pattern>
 	</rule>
@@ -283,7 +283,7 @@
 		<exclude-pattern>/tests/phpunit/tests/*</exclude-pattern>
 	</rule>
 
-	<!-- Exclude some old classes that can't be renamed, as it would break back compat -->
+	<!-- Exclude some old classes that can't be renamed, as it would break back compat. -->
 	<rule ref="PEAR.NamingConventions.ValidClassName.Invalid">
 		<exclude-pattern>/src/wp-admin/includes/class-wp-filesystem-ftpsockets\.php</exclude-pattern>
 		<exclude-pattern>/src/wp-includes/class-wp-oembed\.php</exclude-pattern>

phpunit.xml.dist

@@ -5,12 +5,12 @@
 		beStrictAboutTestsThatDoNotTestAnything="true"
 		>
 	<testsuites>
-		<!-- Default test suite to run all tests -->
+		<!-- Default test suite to run all tests. -->
 		<testsuite name="default">
 			<directory suffix=".php">tests/phpunit/tests</directory>
 			<exclude>tests/phpunit/tests/rest-api/rest-autosaves-controller.php</exclude>
 		</testsuite>
-		<!-- Sets the DOING_AUTOSAVE constant, so needs to be run last -->
+		<!-- Sets the DOING_AUTOSAVE constant, so needs to be run last. -->
 		<testsuite name="restapi-autosave">
 			<file>tests/phpunit/tests/rest-api/rest-autosaves-controller.php</file>
 		</testsuite>
@@ -44,7 +44,7 @@
 		<whitelist addUncoveredFilesFromWhitelist="true">
 			<directory suffix=".php">src</directory>
 			<exclude>
-				<!-- Third party library exclusions -->
+				<!-- Third party library exclusions. -->
 				<directory suffix=".php">src/wp-includes/ID3</directory>
 				<directory suffix=".php">src/wp-includes/IXR</directory>
 				<directory suffix=".php">src/wp-includes/random_compat</directory>

src/index.php

@@ -29,7 +29,7 @@
 wp_check_php_mysql_versions();
 wp_load_translations_early();
 
-// Die with an error message
+// Die with an error message.
 $die = sprintf(
 	'<p>%s</p>',
 	__( 'You are running WordPress without JavaScript and CSS files. These need to be built.' )

src/js/_enqueues/admin/comment.js

@@ -70,7 +70,7 @@ jQuery(document).ready( function($) {
 	 * @param {Event} event The event object.
 	 * @return {void}
 	 */
-	$timestampdiv.find('.save-timestamp').click( function( event ) { // crazyhorse - multiple ok cancels
+	$timestampdiv.find('.save-timestamp').click( function( event ) { // Crazyhorse - multiple OK cancels.
 		var aa = $('#aa').val(), mm = $('#mm').val(), jj = $('#jj').val(), hh = $('#hh').val(), mn = $('#mn').val(),
 			newD = new Date( aa, mm - 1, jj, hh, mn );