From e0f5dfd91ba7e4fda8625ef455383f527ef1c301 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Wed, 22 Sep 2021 21:21:40 +0000 Subject: [PATCH] Docs: Miscellaneous docblock corrections and improvements. See #52217, #53399 git-svn-id: https://develop.svn.wordpress.org/trunk@51851 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/class-wp-http-cookie.php | 17 +++- src/wp-includes/class-wp-user.php | 1 + src/wp-includes/class.wp-dependencies.php | 35 ++++++--- .../widgets/class-wp-widget-media.php | 1 - src/wp-includes/wp-db.php | 77 +++++++++++++++++++ 5 files changed, 117 insertions(+), 14 deletions(-) diff --git a/src/wp-includes/class-wp-http-cookie.php b/src/wp-includes/class-wp-http-cookie.php index ec3425d83b..5fa2de7644 100644 --- a/src/wp-includes/class-wp-http-cookie.php +++ b/src/wp-includes/class-wp-http-cookie.php @@ -24,6 +24,7 @@ class WP_Http_Cookie { * Cookie name. * * @since 2.8.0 + * * @var string */ public $name; @@ -32,6 +33,7 @@ class WP_Http_Cookie { * Cookie value. * * @since 2.8.0 + * * @var string */ public $value; @@ -40,6 +42,7 @@ class WP_Http_Cookie { * When the cookie expires. Unix timestamp or formatted date. * * @since 2.8.0 + * * @var string|int|null */ public $expires; @@ -48,6 +51,7 @@ class WP_Http_Cookie { * Cookie URL path. * * @since 2.8.0 + * * @var string */ public $path; @@ -56,14 +60,25 @@ class WP_Http_Cookie { * Cookie Domain. * * @since 2.8.0 + * * @var string */ public $domain; + /** + * Cookie port or comma-separated list of ports. + * + * @since 2.8.0 + * + * @var int|string + */ + public $port; + /** * host-only flag. * * @since 5.2.0 + * * @var bool */ public $host_only; @@ -85,7 +100,7 @@ class WP_Http_Cookie { * @type string|int|null $expires Optional. Unix timestamp or formatted date. Default null. * @type string $path Optional. Path. Default '/'. * @type string $domain Optional. Domain. Default host of parsed $requested_url. - * @type int $port Optional. Port. Default null. + * @type int|string $port Optional. Port or comma-separated list of ports. Default null. * @type bool $host_only Optional. host-only storage flag. Default true. * } * @param string $requested_url The URL which the cookie was set on, used for default $domain diff --git a/src/wp-includes/class-wp-user.php b/src/wp-includes/class-wp-user.php index 195bc24341..b2f8687828 100644 --- a/src/wp-includes/class-wp-user.php +++ b/src/wp-includes/class-wp-user.php @@ -34,6 +34,7 @@ * @property string $locale * @property string $rich_editing * @property string $syntax_highlighting + * @property string $use_ssl */ class WP_User { /** diff --git a/src/wp-includes/class.wp-dependencies.php b/src/wp-includes/class.wp-dependencies.php index 9ed26568ed..e9f701b727 100644 --- a/src/wp-includes/class.wp-dependencies.php +++ b/src/wp-includes/class.wp-dependencies.php @@ -17,33 +17,37 @@ */ class WP_Dependencies { /** - * An array of registered handle objects. + * An array of all registered dependencies keyed by handle. * * @since 2.6.8 - * @var array + * + * @var _WP_Dependency[] */ public $registered = array(); /** - * An array of handles of queued objects. + * An array of handles of queued dependencies. * * @since 2.6.8 + * * @var string[] */ public $queue = array(); /** - * An array of handles of objects to queue. + * An array of handles of dependencies to queue. * * @since 2.6.0 + * * @var string[] */ public $to_do = array(); /** - * An array of handles of objects already queued. + * An array of handles of dependencies already queued. * * @since 2.6.0 + * * @var string[] */ public $done = array(); @@ -54,15 +58,20 @@ class WP_Dependencies { * Arguments are appended to the item query string. * * @since 2.6.0 + * * @var array */ public $args = array(); /** - * An array of handle groups to enqueue. + * An array of dependency groups to enqueue. + * + * Each entry is keyed by handle and represents the integer group level or boolean + * false if the handle has no group. * * @since 2.8.0 - * @var array + * + * @var (int|false)[] */ public $groups = array(); @@ -70,6 +79,7 @@ class WP_Dependencies { * A handle group to enqueue. * * @since 2.8.0 + * * @deprecated 4.5.0 * @var int */ @@ -79,6 +89,7 @@ class WP_Dependencies { * Cached lookup array of flattened queued items and dependencies. * * @since 5.4.0 + * * @var array */ private $all_queued_deps; @@ -94,7 +105,7 @@ class WP_Dependencies { * @param string|string[]|false $handles Optional. Items to be processed: queue (false), * single item (string), or multiple items (array of strings). * Default false. - * @param int|false $group Optional. Group level: level (int), no groups (false). + * @param int|false $group Optional. Group level: level (int), no group (false). * @return string[] Array of handles of items that have been processed. */ public function do_items( $handles = false, $group = false ) { @@ -131,7 +142,7 @@ class WP_Dependencies { * @since 5.5.0 Added the `$group` parameter. * * @param string $handle Name of the item. Should be unique. - * @param int|false $group Optional. Group level: level (int), no groups (false). + * @param int|false $group Optional. Group level: level (int), no group (false). * Default false. * @return bool True on success, false if not set. */ @@ -152,7 +163,7 @@ class WP_Dependencies { * @param string|string[] $handles Item handle (string) or item handles (array of strings). * @param bool $recursion Optional. Internal flag that function is calling itself. * Default false. - * @param int|false $group Optional. Group level: level (int), no groups (false). + * @param int|false $group Optional. Group level: level (int), no group (false). * Default false. * @return bool True on success, false on failure. */ @@ -354,7 +365,7 @@ class WP_Dependencies { } /** - * Recursively search the passed dependency tree for $handle. + * Recursively search the passed dependency tree for a handle. * * @since 4.0.0 * @@ -434,7 +445,7 @@ class WP_Dependencies { * * @param string $handle Name of the item. Should be unique. * @param bool $recursion Internal flag that calling function was called recursively. - * @param int|false $group Group level: level (int), no groups (false). + * @param int|false $group Group level: level (int), no group (false). * @return bool Not already in the group or a lower group. */ public function set_group( $handle, $recursion, $group ) { diff --git a/src/wp-includes/widgets/class-wp-widget-media.php b/src/wp-includes/widgets/class-wp-widget-media.php index b6eaff793e..cd633e2908 100644 --- a/src/wp-includes/widgets/class-wp-widget-media.php +++ b/src/wp-includes/widgets/class-wp-widget-media.php @@ -317,7 +317,6 @@ abstract class WP_Widget_Media extends WP_Widget { * @since 4.8.0 * * @param array $instance Widget instance props. - * @return string */ abstract public function render_media( $instance ); diff --git a/src/wp-includes/wp-db.php b/src/wp-includes/wp-db.php index 340a6f5861..13efeb0eaa 100644 --- a/src/wp-includes/wp-db.php +++ b/src/wp-includes/wp-db.php @@ -59,6 +59,7 @@ class wpdb { * Default is to show errors if both WP_DEBUG and WP_DEBUG_DISPLAY evaluate to true. * * @since 0.71 + * * @var bool */ public $show_errors = false; @@ -67,6 +68,7 @@ class wpdb { * Whether to suppress errors during the DB bootstrapping. Default false. * * @since 2.5.0 + * * @var bool */ public $suppress_errors = false; @@ -75,6 +77,7 @@ class wpdb { * The error encountered during the last query. * * @since 2.5.0 + * * @var string */ public $last_error = ''; @@ -83,6 +86,7 @@ class wpdb { * The number of queries made. * * @since 1.2.0 + * * @var int */ public $num_queries = 0; @@ -91,6 +95,7 @@ class wpdb { * Count of rows returned by the last query. * * @since 0.71 + * * @var int */ public $num_rows = 0; @@ -99,6 +104,7 @@ class wpdb { * Count of rows affected by the last query. * * @since 0.71 + * * @var int */ public $rows_affected = 0; @@ -107,6 +113,7 @@ class wpdb { * The ID generated for an AUTO_INCREMENT column by the last query (usually INSERT). * * @since 0.71 + * * @var int */ public $insert_id = 0; @@ -115,6 +122,7 @@ class wpdb { * The last query made. * * @since 0.71 + * * @var string */ public $last_query; @@ -123,6 +131,7 @@ class wpdb { * Results of the last query. * * @since 0.71 + * * @var array|null */ public $last_result; @@ -131,6 +140,7 @@ class wpdb { * MySQL result, which is either a resource or boolean. * * @since 0.71 + * * @var mixed */ protected $result; @@ -139,6 +149,7 @@ class wpdb { * Cached column info, for sanity checking data before inserting. * * @since 4.2.0 + * * @var array */ protected $col_meta = array(); @@ -147,6 +158,7 @@ class wpdb { * Calculated character sets on tables. * * @since 4.2.0 + * * @var array */ protected $table_charset = array(); @@ -155,6 +167,7 @@ class wpdb { * Whether text fields in the current query need to be sanity checked. Default false. * * @since 4.2.0 + * * @var bool */ protected $check_current_query = true; @@ -163,6 +176,7 @@ class wpdb { * Flag to ensure we don't run into recursion problems when checking the collation. * * @since 4.2.0 + * * @see wpdb::check_safe_collation() * @var bool */ @@ -172,6 +186,7 @@ class wpdb { * Saved info on the table column. * * @since 0.71 + * * @var array */ protected $col_info; @@ -204,6 +219,7 @@ class wpdb { * The number of times to retry reconnecting before dying. Default 5. * * @since 3.9.0 + * * @see wpdb::check_connection() * @var int */ @@ -216,6 +232,7 @@ class wpdb { * The second reason is for possible security precautions. * * @since 2.5.0 + * * @var string */ public $prefix = ''; @@ -224,6 +241,7 @@ class wpdb { * WordPress base table prefix. * * @since 3.0.0 + * * @var string */ public $base_prefix; @@ -232,6 +250,7 @@ class wpdb { * Whether the database queries are ready to start executing. * * @since 2.3.2 + * * @var bool */ public $ready = false; @@ -240,6 +259,7 @@ class wpdb { * Blog ID. * * @since 3.0.0 + * * @var int */ public $blogid = 0; @@ -248,6 +268,7 @@ class wpdb { * Site ID. * * @since 3.0.0 + * * @var int */ public $siteid = 0; @@ -256,6 +277,7 @@ class wpdb { * List of WordPress per-blog tables. * * @since 2.5.0 + * * @see wpdb::tables() * @var array */ @@ -278,6 +300,7 @@ class wpdb { * 'categories', 'post2cat', and 'link2cat' were deprecated in 2.3.0, db version 5539. * * @since 2.9.0 + * * @see wpdb::tables() * @var array */ @@ -287,6 +310,7 @@ class wpdb { * List of WordPress global tables. * * @since 3.0.0 + * * @see wpdb::tables() * @var array */ @@ -296,6 +320,7 @@ class wpdb { * List of Multisite global tables. * * @since 3.0.0 + * * @see wpdb::tables() * @var array */ @@ -313,6 +338,7 @@ class wpdb { * WordPress Comments table. * * @since 1.5.0 + * * @var string */ public $comments; @@ -321,6 +347,7 @@ class wpdb { * WordPress Comment Metadata table. * * @since 2.9.0 + * * @var string */ public $commentmeta; @@ -329,6 +356,7 @@ class wpdb { * WordPress Links table. * * @since 1.5.0 + * * @var string */ public $links; @@ -337,6 +365,7 @@ class wpdb { * WordPress Options table. * * @since 1.5.0 + * * @var string */ public $options; @@ -345,6 +374,7 @@ class wpdb { * WordPress Post Metadata table. * * @since 1.5.0 + * * @var string */ public $postmeta; @@ -353,6 +383,7 @@ class wpdb { * WordPress Posts table. * * @since 1.5.0 + * * @var string */ public $posts; @@ -361,6 +392,7 @@ class wpdb { * WordPress Terms table. * * @since 2.3.0 + * * @var string */ public $terms; @@ -369,6 +401,7 @@ class wpdb { * WordPress Term Relationships table. * * @since 2.3.0 + * * @var string */ public $term_relationships; @@ -377,6 +410,7 @@ class wpdb { * WordPress Term Taxonomy table. * * @since 2.3.0 + * * @var string */ public $term_taxonomy; @@ -385,6 +419,7 @@ class wpdb { * WordPress Term Meta table. * * @since 4.4.0 + * * @var string */ public $termmeta; @@ -397,6 +432,7 @@ class wpdb { * WordPress User Metadata table. * * @since 2.3.0 + * * @var string */ public $usermeta; @@ -405,6 +441,7 @@ class wpdb { * WordPress Users table. * * @since 1.5.0 + * * @var string */ public $users; @@ -413,6 +450,7 @@ class wpdb { * Multisite Blogs table. * * @since 3.0.0 + * * @var string */ public $blogs; @@ -421,6 +459,7 @@ class wpdb { * Multisite Blog Metadata table. * * @since 5.1.0 + * * @var string */ public $blogmeta; @@ -429,6 +468,7 @@ class wpdb { * Multisite Registration Log table. * * @since 3.0.0 + * * @var string */ public $registration_log; @@ -437,6 +477,7 @@ class wpdb { * Multisite Signups table. * * @since 3.0.0 + * * @var string */ public $signups; @@ -445,6 +486,7 @@ class wpdb { * Multisite Sites table. * * @since 3.0.0 + * * @var string */ public $site; @@ -453,6 +495,7 @@ class wpdb { * Multisite Sitewide Terms table. * * @since 3.0.0 + * * @var string */ public $sitecategories; @@ -461,6 +504,7 @@ class wpdb { * Multisite Site Metadata table. * * @since 3.0.0 + * * @var string */ public $sitemeta; @@ -472,6 +516,7 @@ class wpdb { * Keys are column names, values are format types: 'ID' => '%d'. * * @since 2.8.0 + * * @see wpdb::prepare() * @see wpdb::insert() * @see wpdb::update() @@ -485,6 +530,7 @@ class wpdb { * Database table columns charset. * * @since 2.2.0 + * * @var string */ public $charset; @@ -493,6 +539,7 @@ class wpdb { * Database table columns collate. * * @since 2.2.0 + * * @var string */ public $collate; @@ -501,6 +548,7 @@ class wpdb { * Database Username. * * @since 2.9.0 + * * @var string */ protected $dbuser; @@ -509,6 +557,7 @@ class wpdb { * Database Password. * * @since 3.1.0 + * * @var string */ protected $dbpassword; @@ -517,6 +566,7 @@ class wpdb { * Database Name. * * @since 3.1.0 + * * @var string */ protected $dbname; @@ -525,6 +575,7 @@ class wpdb { * Database Host. * * @since 3.1.0 + * * @var string */ protected $dbhost; @@ -533,6 +584,7 @@ class wpdb { * Database Handle. * * @since 0.71 + * * @var string */ protected $dbh; @@ -541,6 +593,7 @@ class wpdb { * A textual description of the last query/get_row/get_var call. * * @since 3.0.0 + * * @var string */ public $func_call; @@ -554,6 +607,7 @@ class wpdb { * will force the checks to occur. * * @since 3.3.0 + * * @var bool */ public $is_mysql = null; @@ -562,6 +616,7 @@ class wpdb { * A list of incompatible SQL modes. * * @since 3.9.0 + * * @var array */ protected $incompatible_modes = array( @@ -577,6 +632,7 @@ class wpdb { * Whether to use mysqli over mysql. Default false. * * @since 3.9.0 + * * @var bool */ private $use_mysqli = false; @@ -585,10 +641,31 @@ class wpdb { * Whether we've managed to successfully connect at some point. * * @since 3.9.0 + * * @var bool */ private $has_connected = false; + /** + * Time when the last query was performed. + * + * Only set when `SAVEQUERIES` is defined and truthy. + * + * @since 1.5.0 + * + * @var float + */ + public $time_start = null; + + /** + * The last SQL error that was encountered. + * + * @since 2.5.0 + * + * @var WP_Error|string + */ + public $error = null; + /** * Connects to the database server and selects a database. *