Bootstrap/Load: Ensure uses of set_time_limit are documented why.

`set_time_limit` can cause unexpected behavior so it general should be avoided. There are instances though where they should be used so those instances should be properly documented.

Props Rcrayno, ryan, kurtpayne, jorbin.
Fixes #21521. See #19487.

Built from https://develop.svn.wordpress.org/trunk@59039


git-svn-id: http://core.svn.wordpress.org/trunk@58435 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/includes/ajax-actions.php

@@ -3556,6 +3556,7 @@ function wp_ajax_get_revision_diffs() {
 
 	$return = array();
 
+	// Removes the script timeout limit by setting it to 0 allowing ample time for diff UI setup.
 	if ( function_exists( 'set_time_limit' ) ) {
 		set_time_limit( 0 );
 	}

wp-admin/includes/class-wp-upgrader.php

@@ -524,6 +524,7 @@ class WP_Upgrader {
 		$destination       = $args['destination'];
 		$clear_destination = $args['clear_destination'];
 
+		// Give the upgrade an additional 300 seconds(5 minutes) to ensure the install doesn't prematurely timeout having used up the maximum script execution time upacking and downloading in WP_Upgrader->run.
 		if ( function_exists( 'set_time_limit' ) ) {
 			set_time_limit( 300 );
 		}

wp-admin/includes/update-core.php

@@ -962,6 +962,7 @@ function update_core( $from, $to ) {
 	global $wp_filesystem, $_old_files, $_old_requests_files, $_new_bundled_files, $wpdb;
 
 	if ( function_exists( 'set_time_limit' ) ) {
+		// Gives core update script time an additional 300 seconds(5 minutes) to finish updating large files or run on slower servers.
 		set_time_limit( 300 );
 	}
 

wp-includes/class-pop3.php

@@ -60,6 +60,7 @@ class POP3 {
             settype($timeout,"integer");
             $this->TIMEOUT = $timeout;
             if(function_exists("set_time_limit")){
+                // Extends POP3 request timeout to specified TIMEOUT property.
                 set_time_limit($timeout);
             }
         }
@@ -75,6 +76,7 @@ class POP3 {
 
     function update_timer () {
         if(function_exists("set_time_limit")){
+            // Allows additional extension of POP3 request timeout to specified TIMEOUT property when update_timer is called.
             set_time_limit($this->TIMEOUT);
         }
         return true;

wp-includes/comment.php

@@ -3116,6 +3116,7 @@ function pingback( $content, $post ) {
 
 		if ( $pingback_server_url ) {
 			if ( function_exists( 'set_time_limit' ) ) {
+				// Allows an additional 60 seconds for each pingback to complete.
 				set_time_limit( 60 );
 			}
 

wp-includes/deprecated.php

@@ -3673,6 +3673,7 @@ function post_permalink( $post = 0 ) {
 function wp_get_http( $url, $file_path = false, $red = 1 ) {
 	_deprecated_function( __FUNCTION__, '4.4.0', 'WP_Http' );
 
+	// Adds an additional 60 seconds to the script timeout to ensure the remote request has enough time.
 	if ( function_exists( 'set_time_limit' ) ) {
 		@set_time_limit( 60 );
 	}

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.7-alpha-59038';
+$wp_version = '6.7-alpha-59039';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.