Skip to content

Commit

Permalink
Docs: Improve inline comments per the documentation standards.
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@SergeyBiryukov
SergeyBiryukov committed Jan 29, 2020
1 parent bd2cd57 commit cfc3b57
Show file tree
Hide file tree
Showing 810 changed files with 9,871 additions and 8,362 deletions.
76 changes: 39 additions & 37 deletions Gruntfile.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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'
Expand All @@ -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' ],
Expand Down Expand Up @@ -448,7 +448,7 @@ module.exports = function(grunt) {
},
rtlcss: {
options: {
// rtlcss options
// rtlcss options.
opts: {
clean: false,
processUrls: { atrule: true, decl: false },
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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',
Expand All @@ -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;
}
Expand All @@ -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;
}
Expand Down Expand Up @@ -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: {
Expand Down Expand Up @@ -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( '\', \'' ) + '\'';
Expand Down Expand Up @@ -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/**' );
Expand Down
4 changes: 2 additions & 2 deletions phpcompat.xml.dist
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. -->
Expand All @@ -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. -->
Expand Down
32 changes: 16 additions & 16 deletions phpcs.xml.dist
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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"/>
Expand All @@ -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"/>
Expand All @@ -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>
Expand All @@ -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>

Expand Down Expand Up @@ -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>

Expand Down Expand Up @@ -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"/>
Expand All @@ -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"/>
Expand All @@ -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"/>
Expand Down Expand Up @@ -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>
Expand All @@ -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>
Expand Down
6 changes: 3 additions & 3 deletions phpunit.xml.dist
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion src/index.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.' )
Expand Down
2 changes: 1 addition & 1 deletion src/js/_enqueues/admin/comment.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 );

Expand Down
Loading

0 comments on commit cfc3b57

Please sign in to comment.