Skip to content

Commit 3666c0e

Browse files
audrasjbaudrasjb
committed
Docs: Replace multiple single line comments with multi-line comments.
This changeset updates various comments as per WordPress PHP Inline Documentation Standards. See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments. Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180]. Props costdev, audrasjb. See #58459. git-svn-id: https://develop.svn.wordpress.org/trunk@56191 602fd350-edb4-49c9-b593-d223f7449a82
1 parent a5352c3 commit 3666c0e

8 files changed

Lines changed: 163 additions & 87 deletions

File tree

‎src/wp-includes/formatting.php‎

Lines changed: 54 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -136,8 +136,10 @@ function wptexturize( $text, $reset = false ) {
136136
$static_characters = array_merge( array( '...', '``', '\'\'', ' (tm)' ), $cockney );
137137
$static_replacements = array_merge( array( '…', $opening_quote, $closing_quote, ' ™' ), $cockneyreplace );
138138

139-
// Pattern-based replacements of characters.
140-
// Sort the remaining patterns into several arrays for performance tuning.
139+
/*
140+
* Pattern-based replacements of characters.
141+
* Sort the remaining patterns into several arrays for performance tuning.
142+
*/
141143
$dynamic_characters = array(
142144
'apos' => array(),
143145
'quote' => array(),
@@ -340,8 +342,10 @@ function wptexturize_primes( $haystack, $needle, $prime, $open_quote, $close_quo
340342
// Assume the rightmost quote-period match is the end of quotation.
341343
$pos = strrpos( $sentence, "$flag." );
342344
} else {
343-
// When all else fails, make the rightmost candidate a closing quote.
344-
// This is most likely to be problematic in the context of bug #18549.
345+
/*
346+
* When all else fails, make the rightmost candidate a closing quote.
347+
* This is most likely to be problematic in the context of bug #18549.
348+
*/
345349
$pos = strrpos( $sentence, $flag );
346350
}
347351
$sentence = substr_replace( $sentence, $close_quote, $pos, strlen( $flag ) );
@@ -976,8 +980,10 @@ function _wp_specialchars( $text, $quote_style = ENT_NOQUOTES, $charset = false,
976980
}
977981

978982
if ( ! $double_encode ) {
979-
// Guarantee every &entity; is valid, convert &garbage; into &garbage;
980-
// This is required for PHP < 5.4.0 because ENT_HTML401 flag is unavailable.
983+
/*
984+
* Guarantee every &entity; is valid, convert &garbage; into &amp;garbage;
985+
* This is required for PHP < 5.4.0 because ENT_HTML401 flag is unavailable.
986+
*/
981987
$text = wp_kses_normalize_entities( $text, ( $quote_style & ENT_XML1 ) ? 'xml' : 'html' );
982988
}
983989

@@ -1601,8 +1607,10 @@ function remove_accents( $text, $locale = '' ) {
16011607

16021608
if ( seems_utf8( $text ) ) {
16031609

1604-
// Unicode sequence normalization from NFD (Normalization Form Decomposed)
1605-
// to NFC (Normalization Form [Pre]Composed), the encoding used in this function.
1610+
/*
1611+
* Unicode sequence normalization from NFD (Normalization Form Decomposed)
1612+
* to NFC (Normalization Form [Pre]Composed), the encoding used in this function.
1613+
*/
16061614
if ( function_exists( 'normalizer_is_normalized' )
16071615
&& function_exists( 'normalizer_normalize' )
16081616
) {
@@ -1817,8 +1825,7 @@ function remove_accents( $text, $locale = '' ) {
18171825
'€' => 'E',
18181826
// GBP (Pound) sign.
18191827
'£' => '',
1820-
// Vowels with diacritic (Vietnamese).
1821-
// Unmarked.
1828+
// Vowels with diacritic (Vietnamese). Unmarked.
18221829
'Ơ' => 'O',
18231830
'ơ' => 'o',
18241831
'Ư' => 'U',
@@ -2661,17 +2668,24 @@ function force_balance_tags( $text ) {
26612668
$tag = '';
26622669
}
26632670
} else { // Begin tag.
2664-
if ( $has_self_closer ) { // If it presents itself as a self-closing tag...
2665-
// ...but it isn't a known single-entity self-closing tag, then don't let it be treated as such
2666-
// and immediately close it with a closing tag (the tag will encapsulate no text as a result).
2671+
if ( $has_self_closer ) {
2672+
/*
2673+
* If it presents itself as a self-closing tag, but it isn't a known single-entity self-closing tag,
2674+
* then don't let it be treated as such and immediately close it with a closing tag.
2675+
* The tag will encapsulate no text as a result.
2676+
*/
26672677
if ( ! $is_single_tag ) {
26682678
$attributes = trim( substr( $attributes, 0, -1 ) ) . "></$tag";
26692679
}
2670-
} elseif ( $is_single_tag ) { // Else if it's a known single-entity tag but it doesn't close itself, do so.
2680+
} elseif ( $is_single_tag ) {
2681+
// Else if it's a known single-entity tag but it doesn't close itself, do so.
26712682
$pre_attribute_ws = ' ';
26722683
$attributes .= '/';
2673-
} else { // It's not a single-entity tag.
2674-
// If the top of the stack is the same as the tag we want to push, close previous tag.
2684+
} else {
2685+
/*
2686+
* It's not a single-entity tag.
2687+
* If the top of the stack is the same as the tag we want to push, close previous tag.
2688+
*/
26752689
if ( $stacksize > 0 && ! in_array( $tag, $nestable_tags, true ) && $tagstack[ $stacksize - 1 ] === $tag ) {
26762690
$tagqueue = '</' . array_pop( $tagstack ) . '>';
26772691
$stacksize--;
@@ -2925,8 +2939,10 @@ function _make_url_clickable_cb( $matches ) {
29252939
$url = $matches[2];
29262940

29272941
if ( ')' === $matches[3] && strpos( $url, '(' ) ) {
2928-
// If the trailing character is a closing parethesis, and the URL has an opening parenthesis in it,
2929-
// add the closing parenthesis to the URL. Then we can let the parenthesis balancer do its thing below.
2942+
/*
2943+
* If the trailing character is a closing parethesis, and the URL has an opening parenthesis in it,
2944+
* add the closing parenthesis to the URL. Then we can let the parenthesis balancer do its thing below.
2945+
*/
29302946
$url .= $matches[3];
29312947
$suffix = '';
29322948
} else {
@@ -3106,8 +3122,10 @@ function make_clickable( $text ) {
31063122
)
31073123
(\)?) # 3: Trailing closing parenthesis (for parethesis balancing post processing).
31083124
~xS';
3109-
// The regex is a non-anchored pattern and does not have a single fixed starting character.
3110-
// Tell PCRE to spend more time optimizing since, when used on a page load, it will probably be used several times.
3125+
/*
3126+
* The regex is a non-anchored pattern and does not have a single fixed starting character.
3127+
* Tell PCRE to spend more time optimizing since, when used on a page load, it will probably be used several times.
3128+
*/
31113129

31123130
$ret = preg_replace_callback( $url_clickable, '_make_url_clickable_cb', $ret );
31133131

@@ -3556,15 +3574,19 @@ function is_email( $email, $deprecated = false ) {
35563574
// Split out the local and domain parts.
35573575
list( $local, $domain ) = explode( '@', $email, 2 );
35583576

3559-
// LOCAL PART
3560-
// Test for invalid characters.
3577+
/*
3578+
* LOCAL PART
3579+
* Test for invalid characters.
3580+
*/
35613581
if ( ! preg_match( '/^[a-zA-Z0-9!#$%&\'*+\/=?^_`{|}~\.-]+$/', $local ) ) {
35623582
/** This filter is documented in wp-includes/formatting.php */
35633583
return apply_filters( 'is_email', false, $email, 'local_invalid_chars' );
35643584
}
35653585

3566-
// DOMAIN PART
3567-
// Test for sequences of periods.
3586+
/*
3587+
* DOMAIN PART
3588+
* Test for sequences of periods.
3589+
*/
35683590
if ( preg_match( '/\.{2,}/', $domain ) ) {
35693591
/** This filter is documented in wp-includes/formatting.php */
35703592
return apply_filters( 'is_email', false, $email, 'domain_period_sequence' );
@@ -3766,16 +3788,20 @@ function sanitize_email( $email ) {
37663788
// Split out the local and domain parts.
37673789
list( $local, $domain ) = explode( '@', $email, 2 );
37683790

3769-
// LOCAL PART
3770-
// Test for invalid characters.
3791+
/*
3792+
* LOCAL PART
3793+
* Test for invalid characters.
3794+
*/
37713795
$local = preg_replace( '/[^a-zA-Z0-9!#$%&\'*+\/=?^_`{|}~\.-]/', '', $local );
37723796
if ( '' === $local ) {
37733797
/** This filter is documented in wp-includes/formatting.php */
37743798
return apply_filters( 'sanitize_email', '', $email, 'local_invalid_chars' );
37753799
}
37763800

3777-
// DOMAIN PART
3778-
// Test for sequences of periods.
3801+
/*
3802+
* DOMAIN PART
3803+
* Test for sequences of periods.
3804+
*/
37793805
$domain = preg_replace( '/\.{2,}/', '', $domain );
37803806
if ( '' === $domain ) {
37813807
/** This filter is documented in wp-includes/formatting.php */

‎src/wp-includes/functions.php‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3797,8 +3797,10 @@ function _default_wp_die_handler( $message, $title = '', $args = array() ) {
37973797
$text_direction = $parsed_args['text_direction'];
37983798
$dir_attr = "dir='$text_direction'";
37993799

3800-
// If `text_direction` was not explicitly passed,
3801-
// use get_language_attributes() if available.
3800+
/*
3801+
* If `text_direction` was not explicitly passed,
3802+
* use get_language_attributes() if available.
3803+
*/
38023804
if ( empty( $args['text_direction'] )
38033805
&& function_exists( 'language_attributes' ) && function_exists( 'is_rtl' )
38043806
) {
@@ -5085,9 +5087,8 @@ function _wp_array_set( &$input_array, $path, $value = null ) {
50855087
* @return string kebab-cased-string.
50865088
*/
50875089
function _wp_to_kebab_case( $input_string ) {
5088-
//phpcs:disable WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase
5089-
// ignore the camelCase names for variables so the names are the same as lodash
5090-
// so comparing and porting new changes is easier.
5090+
// Ignore the camelCase names for variables so the names are the same as lodash so comparing and porting new changes is easier.
5091+
// phpcs:disable WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase
50915092

50925093
/*
50935094
* Some notable things we've removed compared to the lodash version are:
@@ -6897,8 +6898,7 @@ function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = ar
68976898
$evanescent_hare = $start;
68986899
$return = array();
68996900

6900-
// Set evanescent_hare to one past hare.
6901-
// Increment hare two steps.
6901+
// Set evanescent_hare to one past hare. Increment hare two steps.
69026902
while (
69036903
$tortoise
69046904
&&
@@ -8349,8 +8349,10 @@ function wp_get_direct_update_https_url() {
83498349
*/
83508350
function get_dirsize( $directory, $max_execution_time = null ) {
83518351

8352-
// Exclude individual site directories from the total when checking the main site of a network,
8353-
// as they are subdirectories and should not be counted.
8352+
/*
8353+
* Exclude individual site directories from the total when checking the main site of a network,
8354+
* as they are subdirectories and should not be counted.
8355+
*/
83548356
if ( is_multisite() && is_main_site() ) {
83558357
$size = recurse_dirsize( $directory, $directory . '/sites', $max_execution_time );
83568358
} else {

‎src/wp-includes/https-detection.php‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,11 @@ function wp_is_home_url_using_https() {
4949
* @return bool True if using HTTPS, false otherwise.
5050
*/
5151
function wp_is_site_url_using_https() {
52-
// Use direct option access for 'siteurl' and manually run the 'site_url'
53-
// filter because `site_url()` will adjust the scheme based on what the
54-
// current request is using.
52+
/*
53+
* Use direct option access for 'siteurl' and manually run the 'site_url'
54+
* filter because `site_url()` will adjust the scheme based on what the
55+
* current request is using.
56+
*/
5557
/** This filter is documented in wp-includes/link-template.php */
5658
$site_url = apply_filters( 'site_url', get_option( 'siteurl' ), '', null, null );
5759

‎src/wp-includes/https-migration.php‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,8 +97,10 @@ function wp_update_urls_to_https() {
9797
update_option( 'siteurl', $siteurl );
9898

9999
if ( ! wp_is_using_https() ) {
100-
// If this did not result in the site recognizing HTTPS as being used,
101-
// revert the change and return false.
100+
/*
101+
* If this did not result in the site recognizing HTTPS as being used,
102+
* revert the change and return false.
103+
*/
102104
update_option( 'home', $orig_home );
103105
update_option( 'siteurl', $orig_siteurl );
104106
return false;

‎src/wp-includes/kses.php‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -791,8 +791,10 @@ function wp_kses_one_attr( $attr, $element ) {
791791
if ( count( $split ) === 2 ) {
792792
$value = $split[1];
793793

794-
// Remove quotes surrounding $value.
795-
// Also guarantee correct quoting in $attr for this one attribute.
794+
/*
795+
* Remove quotes surrounding $value.
796+
* Also guarantee correct quoting in $attr for this one attribute.
797+
*/
796798
if ( '' === $value ) {
797799
$quote = '';
798800
} else {
@@ -1442,8 +1444,10 @@ function wp_kses_hair( $attr, $allowed_protocols ) {
14421444
} // End while.
14431445

14441446
if ( 1 == $mode && false === array_key_exists( $attrname, $attrarr ) ) {
1445-
// Special case, for when the attribute list ends with a valueless
1446-
// attribute like "selected".
1447+
/*
1448+
* Special case, for when the attribute list ends with a valueless
1449+
* attribute like "selected".
1450+
*/
14471451
$attrarr[ $attrname ] = array(
14481452
'name' => $attrname,
14491453
'value' => '',
@@ -1546,8 +1550,10 @@ function wp_kses_hair_parse( $attr ) {
15461550
. '\s*'; // Trailing space is optional except as mentioned above.
15471551
// phpcs:enable
15481552

1549-
// Although it is possible to reduce this procedure to a single regexp,
1550-
// we must run that regexp twice to get exactly the expected result.
1553+
/*
1554+
* Although it is possible to reduce this procedure to a single regexp,
1555+
* we must run that regexp twice to get exactly the expected result.
1556+
*/
15511557

15521558
$validation = "%^($regex)+$%";
15531559
$extraction = "%$regex%";

‎src/wp-includes/link-template.php‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -249,8 +249,10 @@ function get_permalink( $post = 0, $leavename = false ) {
249249
$category = get_category_parents( $category_object->parent, false, '/', true ) . $category;
250250
}
251251
}
252-
// Show default category in permalinks,
253-
// without having to assign it explicitly.
252+
/*
253+
* Show default category in permalinks,
254+
* without having to assign it explicitly.
255+
*/
254256
if ( empty( $category ) ) {
255257
$default_category = get_term( get_option( 'default_category' ), 'category' );
256258
if ( $default_category && ! is_wp_error( $default_category ) ) {
@@ -265,8 +267,10 @@ function get_permalink( $post = 0, $leavename = false ) {
265267
$author = $authordata->user_nicename;
266268
}
267269

268-
// This is not an API call because the permalink is based on the stored post_date value,
269-
// which should be parsed as local time regardless of the default PHP timezone.
270+
/*
271+
* This is not an API call because the permalink is based on the stored post_date value,
272+
* which should be parsed as local time regardless of the default PHP timezone.
273+
*/
270274
$date = explode( ' ', str_replace( array( '-', ':' ), ' ', $post->post_date ) );
271275

272276
$rewritereplace = array(

0 commit comments

Comments
 (0)