Make WordPress Core

Changeset 31246


Ignore:
Timestamp:
01/19/2015 09:14:39 AM (9 years ago)
Author:
DrewAPicture
Message:

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.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/upgrade.php

    r31225 r31246  
    33 * WordPress Upgrade API
    44 *
    5  * Most of the functions are pluggable and can be overwritten
     5 * Most of the functions are pluggable and can be overwritten.
    66 *
    77 * @package WordPress
     
    2121if ( !function_exists('wp_install') ) :
    2222/**
    23  * Installs the blog
    24  *
    25  * {@internal Missing Long Description}}
     23 * Installs the site.
     24 *
     25 * Runs the required functions to set up and populate the database,
     26 * including primary admin user and initial options.
    2627 *
    2728 * @since 2.1.0
    2829 *
    29  * @param string $blog_title Blog title.
    30  * @param string $user_name User's username.
    31  * @param string $user_email User's email.
    32  * @param bool $public Whether blog is public.
    33  * @param string $deprecated Optional. Not used.
    34  * @param string $user_password Optional. User's chosen password. Will default to a random password.
    35  * @param string $language Optional. Language chosen.
    36  * @return array Array keys 'url', 'user_id', 'password', 'password_message'.
     30 * @param string $blog_title    Blog title.
     31 * @param string $user_name     User's username.
     32 * @param string $user_email    User's email.
     33 * @param bool   $public        Whether blog is public.
     34 * @param string $deprecated    Optional. Not used.
     35 * @param string $user_password Optional. User's chosen password. Default empty (random password).
     36 * @param string $language      Optional. Language chosen. Default empty.
     37 * @return array Array keys 'url', 'user_id', 'password', and 'password_message'.
    3738 */
    3839function wp_install( $blog_title, $user_name, $user_email, $public, $deprecated = '', $user_password = '', $language = '' ) {
     
    111112if ( !function_exists('wp_install_defaults') ) :
    112113/**
    113  * {@internal Missing Short Description}}
    114  *
    115  * {@internal Missing Long Description}}
     114 * Creates the initial content for a newly-installed site.
     115 *
     116 * Adds the default "Uncategorized" category, the first post (with comment),
     117 * first page, and default widgets for default theme for the current version.
    116118 *
    117119 * @since 2.1.0
     
    334336if ( !function_exists('wp_new_blog_notification') ) :
    335337/**
    336  * {@internal Missing Short Description}}
    337  *
    338  * {@internal Missing Long Description}}
     338 * Notifies the site admin that the setup is complete.
     339 *
     340 * Sends an email with wp_mail to the new administrator that the site setup is complete,
     341 * and provides them with a record of their login credentials.
    339342 *
    340343 * @since 2.1.0
    341344 *
    342345 * @param string $blog_title Blog title.
    343  * @param string $blog_url Blog url.
    344  * @param int $user_id User ID.
    345  * @param string $password User's Password.
     346 * @param string $blog_url   Blog url.
     347 * @param int    $user_id    User ID.
     348 * @param string $password   User's Password.
    346349 */
    347350function wp_new_blog_notification($blog_title, $blog_url, $user_id, $password) {
     
    372375if ( !function_exists('wp_upgrade') ) :
    373376/**
    374  * Run WordPress Upgrade functions.
    375  *
    376  * {@internal Missing Long Description}}
     377 * Runs WordPress Upgrade functions.
     378 *
     379 * Upgrades the database if needed during a site update.
    377380 *
    378381 * @since 2.1.0
    379382 *
    380  * @return null
     383 * @return null If no update is necessary or site isn't completely installed, null.
    381384 */
    382385function wp_upgrade() {
     
    423426 * Functions to be called in install and upgrade scripts.
    424427 *
    425  * {@internal Missing Long Description}}
     428 * Contains conditional checks to determine which upgrade scripts to run,
     429 * based on database version and WP version being updated-to.
    426430 *
    427431 * @since 1.0.1
     432 *
     433 * @return null If no update is necessary, null.
    428434 */
    429435function upgrade_all() {
     
    14021408
    14031409/**
    1404  * Execute network level changes
     1410 * Executes network-level upgrade routines.
    14051411 *
    14061412 * @since 3.0.0
     
    14991505}
    15001506
    1501 // The functions we use to actually do stuff
    1502 
    1503 // General
    1504 
    1505 /**
    1506  * {@internal Missing Short Description}}
    1507  *
    1508  * {@internal Missing Long Description}}
     1507//
     1508// General functions we use to actually do stuff
     1509//
     1510
     1511/**
     1512 * Creates a table in the database if it doesn't already exist.
     1513 *
     1514 * This method checks for an existing database and creates a new one if it's not
     1515 * already present. It doesn't rely on MySQL's "IF NOT EXISTS" statement, but chooses
     1516 * to query all tables first and then run the SQL statement creating the table.
    15091517 *
    15101518 * @since 1.0.0
     
    15341542
    15351543/**
    1536  * {@internal Missing Short Description}}
    1537  *
    1538  * {@internal Missing Long Description}}
     1544 * Drops a specified index from a table.
    15391545 *
    15401546 * @since 1.0.1
     
    15571563
    15581564/**
    1559  * {@internal Missing Short Description}}
    1560  *
    1561  * {@internal Missing Long Description}}
     1565 * Adds an index to a specified table.
    15621566 *
    15631567 * @since 1.0.1
     
    15751579
    15761580/**
    1577  ** maybe_add_column()
    1578  ** Add column to db table if it doesn't exist.
    1579  ** Returns:  true if already exists or on successful completion
    1580  **           false on error
     1581 * Adds column to a database table if it doesn't already exist.
     1582 *
     1583 * @since 1.3.0
     1584 *
     1585 * @param string $table_name  The table name to modify.
     1586 * @param string $column_name The column name to add to the table.
     1587 * @param string $create_ddl  The SQL statement used to add the column.
     1588 * @return True if already exists or on successful completion, false on error.
    15811589 */
    15821590function maybe_add_column($table_name, $column_name, $create_ddl) {
     
    16211629
    16221630/**
    1623  * Version of get_option that is private to install/upgrade.
    1624  *
     1631 * Utility version of get_option that is private to install/upgrade.
     1632 *
     1633 * @ignore
    16251634 * @since 1.5.1
    16261635 * @access private
     
    16501659
    16511660/**
    1652  * {@internal Missing Short Description}}
    1653  *
    1654  * {@internal Missing Long Description}}
     1661 * Filters for content to remove unnecessary slashes.
    16551662 *
    16561663 * @since 1.5.0
    16571664 *
    1658  * @param string $content
    1659  * @return string
     1665 * @param string $content The content to modify.
     1666 * @return string The de-slashed content.
    16601667 */
    16611668function deslash($content) {
     
    16811688
    16821689/**
    1683  * {@internal Missing Short Description}}
    1684  *
    1685  * {@internal Missing Long Description}}
     1690 * Modifies the database based on specified SQL statements.
     1691 *
     1692 * Useful for creating new tables and updating existing tables to a new structure.
    16861693 *
    16871694 * @since 1.5.0
    16881695 *
    1689  * @param string $queries
    1690  * @param bool   $execute
    1691  * @return array
     1696 * @param string|array $queries Optional. The query to run. Can be multiple queries
     1697 *                              in an array, or a string of queries separated by
     1698 *                              semicolons. Default empty.
     1699 * @param bool         $execute Optional. Whether or not to execute the query right away.
     1700 *                              Default true.
     1701 * @return array Strings containing the results of the various update queries.
    16921702 */
    16931703function dbDelta( $queries = '', $execute = true ) {
     
    19321942
    19331943/**
    1934  * {@internal Missing Short Description}}
    1935  *
    1936  * {@internal Missing Long Description}}
     1944 * Updates the database tables to a new schema.
     1945 *
     1946 * By default, updates all the tables to use the latest defined schema, but can also
     1947 * be used to update a specific set of tables in wp_get_db_schema().
    19371948 *
    19381949 * @since 1.5.0
     1950 *
     1951 * @uses dbDelta
     1952 *
     1953 * @param string $tables Optional. Which set of tables to update. Default is 'all'.
    19391954 */
    19401955function make_db_current( $tables = 'all' ) {
     
    19461961
    19471962/**
    1948  * {@internal Missing Short Description}}
    1949  *
    1950  * {@internal Missing Long Description}}
     1963 * Updates the database tables to a new schema, but without displaying results.
     1964 *
     1965 * By default, updates all the tables to use the latest defined schema, but can
     1966 * also be used to update a specific set of tables in wp_get_db_schema().
    19511967 *
    19521968 * @since 1.5.0
     1969 *
     1970 * @see make_db_current()
     1971 *
     1972 * @param string $tables Optional. Which set of tables to update. Default is 'all'.
    19531973 */
    19541974function make_db_current_silent( $tables = 'all' ) {
     
    19571977
    19581978/**
    1959  * {@internal Missing Short Description}}
     1979 * Creates a site theme from an existing theme.
    19601980 *
    19611981 * {@internal Missing Long Description}}
     
    19631983 * @since 1.5.0
    19641984 *
    1965  * @param string $theme_name
    1966  * @param string $template
     1985 * @param string $theme_name The name of the theme.
     1986 * @param string $template   The directory name of the theme.
    19671987 * @return bool
    19681988 */
     
    20402060
    20412061/**
    2042  * {@internal Missing Short Description}}
     2062 * Creates a site theme from the default theme.
    20432063 *
    20442064 * {@internal Missing Long Description}}
     
    20462066 * @since 1.5.0
    20472067 *
    2048  * @param string $theme_name
    2049  * @param string $template
     2068 * @param string $theme_name The name of the theme.
     2069 * @param string $template   The directory name of the theme.
    20502070 * @return null|false
    20512071 */
     
    21042124}
    21052125
    2106 // Create a site theme from the default theme.
    2107 /**
    2108  * {@internal Missing Short Description}}
     2126/**
     2127 * Creates a site theme.
    21092128 *
    21102129 * {@internal Missing Long Description}}
     
    21852204
    21862205/**
    2187  * {@internal Missing Short Description}}
    2188  *
    2189  * {@internal Missing Long Description}}
     2206 * Checks the version of the installed MySQL binary.
    21902207 *
    21912208 * @since 2.1.0
     
    22162233
    22172234/**
    2218  * Disables the Link Manager on upgrade, if at the time of upgrade, no links exist in the DB.
     2235 * Disables the Link Manager on upgrade if, at the time of upgrade, no links exist in the DB.
    22192236 *
    22202237 * @since 3.5.0
Note: See TracChangeset for help on using the changeset viewer.