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 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