From 6c66b1b24d581d1fa11fb7c65fde922b1deb404e Mon Sep 17 00:00:00 2001
From: Morgan Estes <morgan.estes@gmail.com>
Date: Mon, 22 Dec 2014 22:30:12 -0500
Subject: [PATCH] Update PHP docblocks for upgrade methods.

- Add short and long descriptions where missing.
- Remove an extra "@since" in a block.
- Punctuation added where required.
---
 src/wp-admin/includes/upgrade.php | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/src/wp-admin/includes/upgrade.php b/src/wp-admin/includes/upgrade.php
index b72303a..608cde2 100644
--- a/src/wp-admin/includes/upgrade.php
+++ b/src/wp-admin/includes/upgrade.php
@@ -2,7 +2,7 @@
 /**
  * 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,9 +20,10 @@ require_once(ABSPATH . 'wp-admin/includes/schema.php');
 
 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,9 +109,10 @@ endif;
 
 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,9 +264,10 @@ endif;
 
 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,11 +305,11 @@ if ( !function_exists('wp_upgrade') ) :
 /**
  * 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,9 +354,12 @@ endif;
 /**
  * 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,7 +1296,6 @@ function upgrade_370() {
  * 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,7 +1334,7 @@ function upgrade_400() {
 }
 
 /**
- * Execute network level changes
+ * Execute network level changes.
  *
  * @since 3.0.0
  */
-- 
2.2.1

From ef1cc4e4faa26edcbc0872e279651d80e1aa1d23 Mon Sep 17 00:00:00 2001
From: Morgan Estes <morgan.estes@gmail.com>
Date: Mon, 22 Dec 2014 23:35:28 -0500
Subject: [PATCH] Update docblocks with descriptions and updated parameter and
 return info.

---
 src/wp-admin/includes/upgrade.php | 66 ++++++++++++++++++++++-----------------
 1 file changed, 37 insertions(+), 29 deletions(-)

diff --git a/src/wp-admin/includes/upgrade.php b/src/wp-admin/includes/upgrade.php
index 608cde2..a983c57 100644
--- a/src/wp-admin/includes/upgrade.php
+++ b/src/wp-admin/includes/upgrade.php
@@ -1436,9 +1436,11 @@ function upgrade_network() {
 // 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,7 +1468,7 @@ function maybe_create_table($table_name, $create_ddl) {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Drop a specified index from a table.
  *
  * {@internal Missing Long Description}}
  *
@@ -1489,7 +1491,7 @@ function drop_index($table, $index) {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Add an index to a specified table.
  *
  * {@internal Missing Long Description}}
  *
@@ -1553,7 +1555,7 @@ function get_alloptions_110() {
 }
 
 /**
- * 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,14 +1584,14 @@ function __get_option($setting) {
 }
 
 /**
- * {@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,15 +1615,16 @@ function deslash($content) {
 }
 
 /**
- * {@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,11 +1867,15 @@ function dbDelta( $queries = '', $execute = true ) {
 }
 
 /**
- * {@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,25 +1885,29 @@ function make_db_current( $tables = 'all' ) {
 }
 
 /**
- * {@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,14 +1983,14 @@ function make_site_theme_from_oldschool($theme_name, $template) {
 }
 
 /**
- * {@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,9 +2047,8 @@ function make_site_theme_from_default($theme_name, $template) {
 	@closedir($images_dir);
 }
 
-// Create a site theme from the default theme.
 /**
- * {@internal Missing Short Description}}
+ * Create a site theme.
  *
  * {@internal Missing Long Description}}
  *
@@ -2117,9 +2127,7 @@ function translate_level_to_role($level) {
 }
 
 /**
- * {@internal Missing Short Description}}
- *
- * {@internal Missing Long Description}}
+ * Check the version of the installed MySQL binary.
  *
  * @since 2.1.0
  */
@@ -2148,7 +2156,7 @@ function maybe_disable_automattic_widgets() {
 }
 
 /**
- * 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
  */
-- 
2.2.1

From bee03fa40602c85701a0820b24030162a3c9c473 Mon Sep 17 00:00:00 2001
From: Morgan Estes <morgan.estes@gmail.com>
Date: Mon, 22 Dec 2014 23:36:35 -0500
Subject: [PATCH] Added docblock for a method that existed since 1.3, but
 didn't have inline documentation consistent with current standards.

---
 src/wp-admin/includes/upgrade.php | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/wp-admin/includes/upgrade.php b/src/wp-admin/includes/upgrade.php
index a983c57..595b426 100644
--- a/src/wp-admin/includes/upgrade.php
+++ b/src/wp-admin/includes/upgrade.php
@@ -1509,10 +1509,14 @@ function add_clean_index($table, $index) {
 }
 
 /**
- ** 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;
-- 
2.2.1

From 9dc70fff031667e64811569f1d8dfd257b661b2c Mon Sep 17 00:00:00 2001
From: Morgan Estes <morgan.estes@gmail.com>
Date: Mon, 22 Dec 2014 23:38:25 -0500
Subject: [PATCH] Removed long description stubs where no long description is
 needed for a method.

---
 src/wp-admin/includes/upgrade.php | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/src/wp-admin/includes/upgrade.php b/src/wp-admin/includes/upgrade.php
index 595b426..325c7ed 100644
--- a/src/wp-admin/includes/upgrade.php
+++ b/src/wp-admin/includes/upgrade.php
@@ -1470,8 +1470,6 @@ function maybe_create_table($table_name, $create_ddl) {
 /**
  * Drop a specified index from a table.
  *
- * {@internal Missing Long Description}}
- *
  * @since 1.0.1
  *
  * @param string $table Database table name.
@@ -1493,8 +1491,6 @@ function drop_index($table, $index) {
 /**
  * Add an index to a specified table.
  *
- * {@internal Missing Long Description}}
- *
  * @since 1.0.1
  *
  * @param string $table Database table name.
@@ -1510,9 +1506,9 @@ function add_clean_index($table, $index) {
 
 /**
  * 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,8 +1586,6 @@ function __get_option($setting) {
 /**
  * Filter for content to remove unnecessary slashes.
  *
- * {@internal Missing Long Description}}
- *
  * @since 1.5.0
  *
  * @param string $content The content to modify.
@@ -1878,7 +1872,7 @@ function dbDelta( $queries = '', $execute = true ) {
  *
  * @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,7 +1890,7 @@ function make_db_current( $tables = 'all' ) {
  *
  * @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' ) {
-- 
2.2.1