Ticket #30825: 30825.3.diff

src/wp-admin/includes/upgrade.php

@@ -2 +2 @@
 /**
  * WordPress Upgrade API
  *
- * Most of the functions are pluggable and can be overwritten
+ * Most of the functions are pluggable and can be overwritten.
  *
  * @package WordPress
  * @subpackage Administration
@@ -20 +20 @@
 
 if ( !function_exists('wp_install') ) :
 /**
- * Installs the blog
+ * Installs the blog.
  *
- * {@internal Missing Long Description}}
+ * Runs the required functions to set up and populate the database, 
+ * including primary admin user and initial options.
  *
  * @since 2.1.0
  *
@@ -108 +109 @@
 
 if ( !function_exists('wp_install_defaults') ) :
 /**
- * {@internal Missing Short Description}}
+ * Creates the initial content for a newly-installed site.
  *
- * {@internal Missing Long Description}}
+ * Adds the default "Uncategorized" category, the first post (with comment),
+ * first page, and default widgets for default theme for the current version.
  *
  * @since 2.1.0
  *
@@ -262 +264 @@
 
 if ( !function_exists('wp_new_blog_notification') ) :
 /**
- * {@internal Missing Short Description}}
+ * Notify the site admin that the setup is complete.
  *
- * {@internal Missing Long Description}}
+ * Sends an email with {@link wp_mail} to the new administrator that the site
+ * setup is complete, and provides them with a record of their login credentials.
  *
  * @since 2.1.0
  *
@@ -302 +305 @@
 /**
  * Run WordPress Upgrade functions.
  *
- * {@internal Missing Long Description}}
+ * Upgrades the database if needed during a site update.
  *
  * @since 2.1.0
  *
- * @return null
+ * @return null If no update is necessary or site isn't completely installed.
  */
 function wp_upgrade() {
         global $wp_current_db_version, $wp_db_version, $wpdb;
@@ -351 +354 @@
 /**
  * Functions to be called in install and upgrade scripts.
  *
- * {@internal Missing Long Description}}
+ * Contains conditional checks to determine which upgrade scripts to run, based on
+ * database version and WP version we're updating to.
  *
  * @since 1.0.1
+ * 
+ * @return null If no update is necessary.
  */
 function upgrade_all() {
         global $wp_current_db_version, $wp_db_version;
@@ -1290 +1296 @@
  * Execute changes made in WordPress 3.7.2.
  *
  * @since 3.7.2
- * @since 3.8.0
  */
 function upgrade_372() {
         global $wp_current_db_version;
@@ -1329 +1334 @@
 }
 
 /**
- * Execute network level changes
+ * Execute network level changes.
  *
  * @since 3.0.0
  */

src/wp-admin/includes/upgrade.php

@@ -1436 +1436 @@
 // General
 
 /**
- * {@internal Missing Short Description}}
+ * Create a table in the database if it doesn't already exist.
  *
- * {@internal Missing Long Description}}
+ * This method checks for an existing database and creates a new one if it's not
+ * already present. It doesn't rely on MySQL's "IF NOT EXISTS" statement, but chooses
+ * to query all tables first and then run the SQL statement creating the table.
  *
  * @since 1.0.0
  *
@@ -1466 +1468 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Drop a specified index from a table.
  *
  * {@internal Missing Long Description}}
  *
@@ -1489 +1491 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Add an index to a specified table.
  *
  * {@internal Missing Long Description}}
  *
@@ -1553 +1555 @@
 }
 
 /**
- * Version of get_option that is private to install/upgrade.
+ * Version of {@link get_option} that is private to install/upgrade.
  *
  * @since 1.5.1
  * @access private
@@ -1582 +1584 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Filter for content to remove unnecessary slashes.
  *
  * {@internal Missing Long Description}}
  *
  * @since 1.5.0
  *
- * @param string $content
- * @return string
+ * @param string $content The content to modify.
+ * @return string The de-slashed content.
  */
 function deslash($content) {
         // Note: \\\ inside a regex denotes a single backslash.
@@ -1613 +1615 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Modify the database based on specified SQL statements.
  *
- * {@internal Missing Long Description}}
+ * Useful for creating new tables, and updating existing tables to a new structure.
  *
  * @since 1.5.0
  *
- * @param string $queries
- * @param bool   $execute
- * @return array
+ * @param string|array $queries The query to run. Can be multiple queries in an array,
+ *                              or a string of queries separated by semicolons.
+ * @param bool         $execute Whether or not to execute the query right away.
+ * @return array Strings containing the results of the various update queries.
  */
 function dbDelta( $queries = '', $execute = true ) {
         global $wpdb;
@@ -1864 +1867 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Update the database tables to a new schema.
  *
- * {@internal Missing Long Description}}
+ * By default, updates all the tables to use the latest defined schema, but can also
+ * be used to update a specific set of tables in {@see wp_get_db_schema()}.
  *
  * @since 1.5.0
+ * @uses dbDelta
+ *
+ * @param string $tables Optional. Which set of tables to update. Default is 'all'.
  */
 function make_db_current( $tables = 'all' ) {
         $alterations = dbDelta( $tables );
@@ -1878 +1885 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Update the database tables to a new schema, but without displaying results.
  *
- * {@internal Missing Long Description}}
+ * By default, updates all the tables to use the latest defined schema, but can also
+ * be used to update a specific set of tables in {@see wp_get_db_schema()}.
  *
  * @since 1.5.0
+ * @see make_db_current()
+ *
+ * @param string $tables Optional. Which set of tables to update. Default is 'all'.
  */
 function make_db_current_silent( $tables = 'all' ) {
         dbDelta( $tables );
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Create a site theme from an existing theme.
  *
  * {@internal Missing Long Description}}
  *
  * @since 1.5.0
  *
- * @param string $theme_name
- * @param string $template
+ * @param string $theme_name The name of the theme.
+ * @param string $template The directory name of the theme.
  * @return bool
  */
 function make_site_theme_from_oldschool($theme_name, $template) {
@@ -1972 +1983 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Create a site theme from the default theme.
  *
  * {@internal Missing Long Description}}
  *
  * @since 1.5.0
  *
- * @param string $theme_name
- * @param string $template
+ * @param string $theme_name The name of the theme.
+ * @param string $template The directory name of the theme.
  * @return null|false
  */
 function make_site_theme_from_default($theme_name, $template) {
@@ -2036 +2047 @@
         @closedir($images_dir);
 }
 
-// Create a site theme from the default theme.
 /**
- * {@internal Missing Short Description}}
+ * Create a site theme.
  *
  * {@internal Missing Long Description}}
  *
@@ -2117 +2127 @@
 }
 
 /**
- * {@internal Missing Short Description}}
- *
- * {@internal Missing Long Description}}
+ * Check the version of the installed MySQL binary.
  *
  * @since 2.1.0
  */
@@ -2148 +2156 @@
 }
 
 /**
- * Disables the Link Manager on upgrade, if at the time of upgrade, no links exist in the DB.
+ * Disables the Link Manager on upgrade if, at the time of upgrade, no links exist in the DB.
  *
  * @since 3.5.0
  */

src/wp-admin/includes/upgrade.php

@@ -1509 +1509 @@
 }
 
 /**
- ** maybe_add_column()
- ** Add column to db table if it doesn't exist.
- ** Returns:  true if already exists or on successful completion
- **           false on error
+ * Add column to a database table if it doesn't already exist.
+ *
+ * @since 1.3.0
+ *
+ * @param string $table_name The table name to modify.
+ * @param string $column_name The column name to add to the table.
+ * @param string $create_ddl The SQL statement used to add the column.
+ * @return True if already exists or on successful completion, false on error.
  */
 function maybe_add_column($table_name, $column_name, $create_ddl) {
         global $wpdb;

src/wp-admin/includes/upgrade.php

@@ -1470 +1470 @@
 /**
  * Drop a specified index from a table.
  *
- * {@internal Missing Long Description}}
- *
  * @since 1.0.1
  *
  * @param string $table Database table name.
@@ -1493 +1491 @@
 /**
  * Add an index to a specified table.
  *
- * {@internal Missing Long Description}}
- *
  * @since 1.0.1
  *
  * @param string $table Database table name.
@@ -1510 +1506 @@
 
 /**
  * Add column to a database table if it doesn't already exist.
- *
+ * 
  * @since 1.3.0
- *
+ * 
  * @param string $table_name The table name to modify.
  * @param string $column_name The column name to add to the table.
  * @param string $create_ddl The SQL statement used to add the column.
@@ -1590 +1586 @@
 /**
  * Filter for content to remove unnecessary slashes.
  *
- * {@internal Missing Long Description}}
- *
  * @since 1.5.0
  *
  * @param string $content The content to modify.
@@ -1878 +1872 @@
  *
  * @since 1.5.0
  * @uses dbDelta
- *
+ * 
  * @param string $tables Optional. Which set of tables to update. Default is 'all'.
  */
 function make_db_current( $tables = 'all' ) {
@@ -1896 +1890 @@
  *
  * @since 1.5.0
  * @see make_db_current()
- *
+ * 
  * @param string $tables Optional. Which set of tables to update. Default is 'all'.
  */
 function make_db_current_silent( $tables = 'all' ) {