WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add missing summaries and descriptions for various functions in wp-admin/includes/upgrade.php. 

Also generally improve existing parameter, return, and other documentation in various function DocBlocks.

Props morganestes.
Fixes #30825.

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


git-svn-id: http://core.svn.wordpress.org/trunk@31227 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2015-01-19 09:15:22 +00:00
parent e0b3db1e09
commit d95586e943
2 changed files with 83 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
wp-admin/includes/upgrade.php
View File

@ -2,7 +2,7 @@
/** /**
* WordPress Upgrade API * 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 * @package WordPress
* @subpackage Administration * @subpackage Administration
@ -20,9 +20,10 @@ require_once(ABSPATH . 'wp-admin/includes/schema.php');
if ( !function_exists('wp_install') ) : if ( !function_exists('wp_install') ) :
/** /**
* Installs the blog * Installs the site.
* *
* {@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 * @since 2.1.0
* *
@ -31,9 +32,9 @@ if ( !function_exists('wp_install') ) :
* @param string $user_email User's email. * @param string $user_email User's email.
* @param bool $public Whether blog is public. * @param bool $public Whether blog is public.
* @param string $deprecated Optional. Not used. * @param string $deprecated Optional. Not used.
* @param string $user_password Optional. User's chosen password. Will default to a random password. * @param string $user_password Optional. User's chosen password. Default empty (random password).
* @param string $language Optional. Language chosen. * @param string $language Optional. Language chosen. Default empty.
* @return array Array keys 'url', 'user_id', 'password', 'password_message'. * @return array Array keys 'url', 'user_id', 'password', and 'password_message'.
*/ */
function wp_install( $blog_title, $user_name, $user_email, $public, $deprecated = '', $user_password = '', $language = '' ) { function wp_install( $blog_title, $user_name, $user_email, $public, $deprecated = '', $user_password = '', $language = '' ) {
if ( !empty( $deprecated ) ) if ( !empty( $deprecated ) )
@ -110,9 +111,10 @@ endif;
if ( !function_exists('wp_install_defaults') ) : 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 * @since 2.1.0
* *
@ -333,9 +335,10 @@ function wp_install_maybe_enable_pretty_permalinks() {
if ( !function_exists('wp_new_blog_notification') ) : if ( !function_exists('wp_new_blog_notification') ) :
/** /**
* {@internal Missing Short Description}} * Notifies the site admin that the setup is complete.
* *
* {@internal Missing Long Description}} * Sends an email with 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 * @since 2.1.0
* *
@ -371,13 +374,13 @@ endif;
if ( !function_exists('wp_upgrade') ) : if ( !function_exists('wp_upgrade') ) :
/** /**
* Run WordPress Upgrade functions. * Runs WordPress Upgrade functions.
* *
* {@internal Missing Long Description}} * Upgrades the database if needed during a site update.
* *
* @since 2.1.0 * @since 2.1.0
* *
* @return null * @return null If no update is necessary or site isn't completely installed, null.
*/ */
function wp_upgrade() { function wp_upgrade() {
global $wp_current_db_version, $wp_db_version, $wpdb; global $wp_current_db_version, $wp_db_version, $wpdb;
@ -422,9 +425,12 @@ endif;
/** /**
* Functions to be called in install and upgrade scripts. * 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 being updated-to.
* *
* @since 1.0.1 * @since 1.0.1
*
* @return null If no update is necessary, null.
*/ */
function upgrade_all() { function upgrade_all() {
global $wp_current_db_version, $wp_db_version; global $wp_current_db_version, $wp_db_version;
@ -1401,7 +1407,7 @@ function upgrade_400() {
} }
/** /**
* Execute network level changes * Executes network-level upgrade routines.
* *
* @since 3.0.0 * @since 3.0.0
*/ */
@ -1498,14 +1504,16 @@ function upgrade_network() {
} }
} }
// The functions we use to actually do stuff //
// General functions we use to actually do stuff
// General //
/** /**
* {@internal Missing Short Description}} * Creates 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 * @since 1.0.0
* *
@ -1533,9 +1541,7 @@ function maybe_create_table($table_name, $create_ddl) {
} }
/** /**
* {@internal Missing Short Description}} * Drops a specified index from a table.
*
* {@internal Missing Long Description}}
* *
* @since 1.0.1 * @since 1.0.1
* *
@ -1556,9 +1562,7 @@ function drop_index($table, $index) {
} }
/** /**
* {@internal Missing Short Description}} * Adds an index to a specified table.
*
* {@internal Missing Long Description}}
* *
* @since 1.0.1 * @since 1.0.1
* *
@ -1574,10 +1578,14 @@ function add_clean_index($table, $index) {
} }
/** /**
** maybe_add_column() * Adds column to a database table if it doesn't already exist.
** Add column to db table if it doesn't exist. *
** Returns: true if already exists or on successful completion * @since 1.3.0
** false on error *
* @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) { function maybe_add_column($table_name, $column_name, $create_ddl) {
global $wpdb; global $wpdb;
@ -1620,8 +1628,9 @@ function get_alloptions_110() {
} }
/** /**
* Version of get_option that is private to install/upgrade. * Utility version of get_option that is private to install/upgrade.
* *
* @ignore
* @since 1.5.1 * @since 1.5.1
* @access private * @access private
* *
@ -1649,14 +1658,12 @@ function __get_option($setting) {
} }
/** /**
* {@internal Missing Short Description}} * Filters for content to remove unnecessary slashes.
*
* {@internal Missing Long Description}}
* *
* @since 1.5.0 * @since 1.5.0
* *
* @param string $content * @param string $content The content to modify.
* @return string * @return string The de-slashed content.
*/ */
function deslash($content) { function deslash($content) {
// Note: \\\ inside a regex denotes a single backslash. // Note: \\\ inside a regex denotes a single backslash.
@ -1680,15 +1687,18 @@ function deslash($content) {
} }
/** /**
* {@internal Missing Short Description}} * Modifies 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 * @since 1.5.0
* *
* @param string $queries * @param string|array $queries Optional. The query to run. Can be multiple queries
* @param bool $execute * in an array, or a string of queries separated by
* @return array * semicolons. Default empty.
* @param bool $execute Optional. Whether or not to execute the query right away.
* Default true.
* @return array Strings containing the results of the various update queries.
*/ */
function dbDelta( $queries = '', $execute = true ) { function dbDelta( $queries = '', $execute = true ) {
global $wpdb; global $wpdb;
@ -1931,11 +1941,16 @@ function dbDelta( $queries = '', $execute = true ) {
} }
/** /**
* {@internal Missing Short Description}} * Updates 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 wp_get_db_schema().
* *
* @since 1.5.0 * @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' ) { function make_db_current( $tables = 'all' ) {
$alterations = dbDelta( $tables ); $alterations = dbDelta( $tables );
@ -1945,25 +1960,30 @@ function make_db_current( $tables = 'all' ) {
} }
/** /**
* {@internal Missing Short Description}} * Updates 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 wp_get_db_schema().
* *
* @since 1.5.0 * @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' ) { function make_db_current_silent( $tables = 'all' ) {
dbDelta( $tables ); dbDelta( $tables );
} }
/** /**
* {@internal Missing Short Description}} * Creates a site theme from an existing theme.
* *
* {@internal Missing Long Description}} * {@internal Missing Long Description}}
* *
* @since 1.5.0 * @since 1.5.0
* *
* @param string $theme_name * @param string $theme_name The name of the theme.
* @param string $template * @param string $template The directory name of the theme.
* @return bool * @return bool
*/ */
function make_site_theme_from_oldschool($theme_name, $template) { function make_site_theme_from_oldschool($theme_name, $template) {
@ -2039,14 +2059,14 @@ function make_site_theme_from_oldschool($theme_name, $template) {
} }
/** /**
* {@internal Missing Short Description}} * Creates a site theme from the default theme.
* *
* {@internal Missing Long Description}} * {@internal Missing Long Description}}
* *
* @since 1.5.0 * @since 1.5.0
* *
* @param string $theme_name * @param string $theme_name The name of the theme.
* @param string $template * @param string $template The directory name of the theme.
* @return null|false * @return null|false
*/ */
function make_site_theme_from_default($theme_name, $template) { function make_site_theme_from_default($theme_name, $template) {
@ -2103,9 +2123,8 @@ function make_site_theme_from_default($theme_name, $template) {
@closedir($images_dir); @closedir($images_dir);
} }
// Create a site theme from the default theme.
/** /**
* {@internal Missing Short Description}} * Creates a site theme.
* *
* {@internal Missing Long Description}} * {@internal Missing Long Description}}
* *
@ -2184,9 +2203,7 @@ function translate_level_to_role($level) {
} }
/** /**
* {@internal Missing Short Description}} * Checks the version of the installed MySQL binary.
*
* {@internal Missing Long Description}}
* *
* @since 2.1.0 * @since 2.1.0
*/ */
@ -2215,7 +2232,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 * @since 3.5.0
*/ */

2
wp-includes/version.php
View File

@ -4,7 +4,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '4.2-alpha-31245'; $wp_version = '4.2-alpha-31246';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.