WordPress.org
Get WordPress

Make WordPress Core

Changeset 34227


Ignore:
Timestamp:
09/16/2015 10:02:20 AM (9 years ago)
Author:
DrewAPicture
Message:

Docs: Improve documentation for the WP_Object_Cache class.

Spaces out parameter documentation for readability, fixes some minor syntactical issues, and adds some missing @access tags or reorders tags according to the PHP docs standards.

Also, documents &$found, the fourth parameter for the get() method, and adds missing parameter and return descriptions for the _exists() utility method.

See #32246.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/cache.php

    r34226 r34227  
    273273
    274274/**
    275  * WordPress Object Cache
     275 * Core class that implements an object cache.
    276276 *
    277277 * The WordPress Object Cache is used to save on trips to the database. The
    … …  
    291291
    292292    /**
    293      * Holds the cached objects
    294      *
     293     * Holds the cached objects.
     294     *
     295     * @since 2.0.0
     296     * @access private
    295297     * @var array
    296      * @access private
    297      * @since 2.0.0
    298298     */
    299299    private $cache = array();
    … …  
    309309
    310310    /**
    311      * Amount of times the cache did not have the request in cache
    312      *
     311     * Amount of times the cache did not have the request in cache.
     312     *
     313     * @since 2.0.0
     314     * @access public
    313315     * @var int
    314      * @access public
    315      * @since 2.0.0
    316316     */
    317317    public $cache_misses = 0;
    318318
    319319    /**
    320      * List of global groups
    321      *
     320     * List of global cache groups.
     321     *
     322     * @since 3.0.0
     323     * @access protected
    322324     * @var array
    323      * @access protected
    324      * @since 3.0.0
    325325     */
    326326    protected $global_groups = array();
    … …  
    329329     * The blog prefix to prepend to keys in non-global groups.
    330330     *
     331     * @since 3.5.0
     332     * @access private
    331333     * @var int
     334     */
     335    private $blog_prefix;
     336
     337    /**
     338     * Holds the value of is_multisite().
     339     *
     340     * @since 3.5.0
    332341     * @access private
    333      * @since 3.5.0
    334      */
    335     private $blog_prefix;
    336 
    337     /**
    338      * Holds the value of `is_multisite()`
    339      *
    340342     * @var bool
    341      * @access private
    342      * @since 3.5.0
    343343     */
    344344    private $multisite;
    345345
    346346    /**
    347      * Make private properties readable for backwards compatibility.
     347     * Makes private properties readable for backwards compatibility.
    348348     *
    349349     * @since 4.0.0
    … …  
    358358
    359359    /**
    360      * Make private properties settable for backwards compatibility.
     360     * Makes private properties settable for backwards compatibility.
    361361     *
    362362     * @since 4.0.0
    … …  
    372372
    373373    /**
    374      * Make private properties checkable for backwards compatibility.
     374     * Makes private properties checkable for backwards compatibility.
    375375     *
    376376     * @since 4.0.0
    … …  
    385385
    386386    /**
    387      * Make private properties un-settable for backwards compatibility.
     387     * Makes private properties un-settable for backwards compatibility.
    388388     *
    389389     * @since 4.0.0
    … …  
    399399     * Adds data to the cache if it doesn't already exist.
    400400     *
    401      * @uses WP_Object_Cache::_exists Checks to see if the cache already has data.
    402      * @uses WP_Object_Cache::set Sets the data after the checking the cache
    403      *      contents existence.
    404      *
    405      * @since 2.0.0
    406      *
    407      * @param int|string $key What to call the contents in the cache
    408      * @param mixed $data The contents to store in the cache
    409      * @param string $group Where to group the cache contents
    410      * @param int $expire When to expire the cache contents
     401     * @since 2.0.0
     402     * @access public
     403     *
     404     * @uses WP_Object_Cache::_exists() Checks to see if the cache already has data.
     405     * @uses WP_Object_Cache::set()     Sets the data after the checking the cache
     406     *                                  contents existence.
     407     *
     408     * @param int|string $key    What to call the contents in the cache.
     409     * @param mixed      $data   The contents to store in the cache.
     410     * @param string     $group  Optional. Where to group the cache contents. Default 'default'.
     411     * @param int        $expire Optional. When to expire the cache contents. Default 0 (no expiration).
    411412     * @return bool False if cache key and group already exist, true on success
    412413     */
    … …  
    429430
    430431    /**
    431      * Sets the list of global groups.
     432     * Sets the list of global cache groups.
    432433     *
    433434     * @since 3.0.0
     435     * @access public
    434436     *
    435437     * @param array $groups List of groups that are global.
    … …  
    443445
    444446    /**
    445      * Decrement numeric cache item's value
     447     * Decrements numeric cache item's value.
    446448     *
    447449     * @since 3.3.0
    448      *
    449      * @param int|string $key The cache key to decrement.
    450      * @param int $offset The amount by which to decrement the item's value. Default is 1.
    451      * @param string $group The group the key is in.
     450     * @access public
     451     *
     452     * @param int|string $key    The cache key to decrement.
     453     * @param int        $offset Optional. The amount by which to decrement the item's value. Default 1.
     454     * @param string     $group  Optional. The group the key is in. Default 'default'.
    452455     * @return false|int False on failure, the item's new value on success.
    453456     */
    … …  
    476479
    477480    /**
    478      * Remove the contents of the cache key in the group
     481     * Removes the contents of the cache key in the group.
    479482     *
    480483     * If the cache key does not exist in the group, then nothing will happen.
    481484     *
    482485     * @since 2.0.0
    483      *
    484      * @param int|string $key What the contents in the cache are called
    485      * @param string $group Where the cache contents are grouped
    486      * @param bool $deprecated Deprecated.
    487      *
    488      * @return bool False if the contents weren't deleted and true on success
     486     * @access public
     487     *
     488     * @param int|string $key        What the contents in the cache are called.
     489     * @param string     $group      Optional. Where the cache contents are grouped. Default 'default'.
     490     * @param bool       $deprecated Optional. Unused. Default false.
     491     * @return bool False if the contents weren't deleted and true on success.
    489492     */
    490493    public function delete( $key, $group = 'default', $deprecated = false ) {
    … …  
    503506
    504507    /**
    505      * Clears the object cache of all data
    506      *
    507      * @since 2.0.0
    508      *
    509      * @return true Always returns true
     508     * Clears the object cache of all data.
     509     *
     510     * @since 2.0.0
     511     * @access public
     512     *
     513     * @return true Always returns true.
    510514     */
    511515    public function flush() {
    … …  
    516520
    517521    /**
    518      * Retrieves the cache contents, if it exists
     522     * Retrieves the cache contents, if it exists.
    519523     *
    520524     * The contents will be first attempted to be retrieved by searching by the
    … …  
    525529     *
    526530     * @since 2.0.0
    527      *
    528      * @param int|string $key What the contents in the cache are called
    529      * @param string $group Where the cache contents are grouped
    530      * @param string $force Whether to force a refetch rather than relying on the local cache (default is false)
    531      * @return false|mixed False on failure to retrieve contents or the cache
    532      *                     contents on success
     531     * @access public
     532     *
     533     * @param int|string $key    What the contents in the cache are called.
     534     * @param string     $group  Optional. Where the cache contents are grouped. Default 'default'.
     535     * @param string     $force  Optional. Unused. Whether to force a refetch rather than relying on the local
     536     *                           cache. Default false.
     537     * @param bool       &$found Optional. Whether the key was found in the cache. Disambiguates a return of
     538     *                           false, a storable value. Passed by reference. Default null.
     539     * @return false|mixed False on failure to retrieve contents or the cache contents on success.
    533540     */
    534541    public function get( $key, $group = 'default', $force = false, &$found = null ) {
    … …  
    554561
    555562    /**
    556      * Increment numeric cache item's value
     563     * Increments numeric cache item's value.
    557564     *
    558565     * @since 3.3.0
    559      *
    560      * @param int|string $key The cache key to increment
    561      * @param int $offset The amount by which to increment the item's value. Default is 1.
    562      * @param string $group The group the key is in.
     566     * @access public
     567     *
     568     * @param int|string $key    The cache key to increment
     569     * @param int        $offset Optional. The amount by which to increment the item's value. Default 1.
     570     * @param string     $group  Optional. The group the key is in. Default 'default'.
    563571     * @return false|int False on failure, the item's new value on success.
    564572     */
    … …  
    587595
    588596    /**
    589      * Replace the contents in the cache, if contents already exist
    590      *
    591      * @since 2.0.0
     597     * Replaces the contents in the cache, if contents already exist.
     598     *
     599     * @since 2.0.0
     600     * @access public
     601     *
    592602     * @see WP_Object_Cache::set()
    593603     *
    594      * @param int|string $key What to call the contents in the cache
    595      * @param mixed $data The contents to store in the cache
    596      * @param string $group Where to group the cache contents
    597      * @param int $expire When to expire the cache contents
    598      * @return bool False if not exists, true if contents were replaced
     604     * @param int|string $key    What to call the contents in the cache.
     605     * @param mixed      $data   The contents to store in the cache.
     606     * @param string     $group  Optional. Where to group the cache contents. Default 'default'.
     607     * @param int        $expire Optional. When to expire the cache contents. Default 0 (no expiration).
     608     * @return bool False if not exists, true if contents were replaced.
    599609     */
    600610    public function replace( $key, $data, $group = 'default', $expire = 0 ) {
    … …  
    613623
    614624    /**
    615      * Reset keys
     625     * Resets cache keys.
    616626     *
    617627     * @since 3.0.0
     628     * @access public
     629     *
    618630     * @deprecated 3.5.0 Use switch_to_blog()
    619631     * @see switch_to_blog()
    … …  
    630642
    631643    /**
    632      * Sets the data contents into the cache
     644     * Sets the data contents into the cache.
    633645     *
    634646     * The cache contents is grouped by the $group parameter followed by the
    … …  
    642654     *
    643655     * @since 2.0.0
    644      *
    645      * @param int|string $key What to call the contents in the cache
    646      * @param mixed $data The contents to store in the cache
    647      * @param string $group Where to group the cache contents
    648      * @param int $expire Not Used
    649      * @return true Always returns true
     656     * @access public
     657     *
     658     * @param int|string $key    What to call the contents in the cache.
     659     * @param mixed      $data   The contents to store in the cache.
     660     * @param string     $group  Optional. Where to group the cache contents. Default 'default'.
     661     * @param int        $expire Not Used.
     662     * @return true Always returns true.
    650663     */
    651664    public function set( $key, $data, $group = 'default', $expire = 0 ) {
    … …  
    670683     *
    671684     * @since 2.0.0
     685     * @access public
    672686     */
    673687    public function stats() {
    … …  
    684698
    685699    /**
    686      * Switch the interal blog id.
    687      *
    688      * This changes the blog id used to create keys in blog specific groups.
     700     * Switches the interal blog ID.
     701     *
     702     * This changes the blog ID used to create keys in blog specific groups.
    689703     *
    690704     * @since 3.5.0
    691      *
    692      * @param int $blog_id Blog ID
     705     * @access public
     706     *
     707     * @param int $blog_id Blog ID.
    693708     */
    694709    public function switch_to_blog( $blog_id ) {
    … …  
    698713
    699714    /**
    700      * Utility function to determine whether a key exists in the cache.
     715     * Serves as a utility function to determine whether a key exists in the cache.
    701716     *
    702717     * @since 3.4.0
    703      *
    704718     * @access protected
    705      * @param string $key
    706      * @param string $group
    707      * @return bool
     719     *
     720     * @param int|string $key   Cache key to check for existence.
     721     * @param string     $group Cache group for the key existence check.
     722     * @return bool Whether the key exists in the cache for the given group.
    708723     */
    709724    protected function _exists( $key, $group ) {
    … …  
    712727
    713728    /**
    714      * Sets up object properties; PHP 5 style constructor
     729     * Sets up object properties; PHP 5 style constructor.
    715730     *
    716731     * @since 2.0.8
    717732     *
    718      * @global int $blog_id
     733     * @global int $blog_id Global blog ID.
    719734     */
    720735    public function __construct() {
    … …  
    733748
    734749    /**
    735      * Will save the object cache before object is completely destroyed.
     750     * Saves the object cache before object is completely destroyed.
    736751     *
    737752     * Called upon object destruction, which should be when PHP ends.
    738753     *
    739      * @since  2.0.8
    740      *
    741      * @return true True value. Won't be used by PHP
     754     * @since 2.0.8
     755     *
     756     * @return true Always returns true.
    742757     */
    743758    public function __destruct() {
Note: See TracChangeset for help on using the changeset viewer.