WordPress.org
Get WordPress

Make WordPress Core

Changeset 28891


Ignore:
Timestamp:
06/29/2014 09:18:41 AM (12 years ago)
Author:
DrewAPicture
Message:

General phpDoc fixes in wp-includes/plugin.php.

See #28516.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r28889 r28891  
    3636
    3737/**
    38  * Hooks a function or method to a specific filter action.
     38 * Hook a function or method to a specific filter action.
    3939 *
    4040 * WordPress offers filter hooks to allow plugins to modify
    … …  
    6464 * so everything is as quick as possible.
    6565 *
     66 * @since 0.71
     67 *
    6668 * @global array $wp_filter      A multidimensional array of all hooks and the callbacks hooked to them.
    67  * @global array $merged_filters Tracks the tags that need to be merged for later. If the hook is added, it doesn't need to run through that process.
    68  *
    69  * @since 0.71
     69 * @global array $merged_filters Tracks the tags that need to be merged for later. If the hook is added,
     70 *                               it doesn't need to run through that process.
    7071 *
    7172 * @param string   $tag             The name of the filter to hook the $function_to_add callback to.
    … …  
    9394 * @since 2.5.0
    9495 *
    95  * @global array $wp_filter Stores all of the filters
     96 * @global array $wp_filter Stores all of the filters.
    9697 *
    9798 * @param string        $tag               The name of the filter hook.
    9899 * @param callback|bool $function_to_check Optional. The callback to check for. Default false.
    99  * @return mixed If $function_to_check is omitted, returns boolean for whether the hook has anything registered.
    100  *  When checking a specific function, the priority of that hook is returned, or false if the function is not attached.
    101  *  When using the $function_to_check argument, this function may return a non-boolean value that evaluates to false
    102  *  (e.g.) 0, so use the === operator for testing the return value.
     100 * @return bool|int If $function_to_check is omitted, returns boolean for whether the hook has
     101 *                  anything registered. When checking a specific function, the priority of that
     102 *                  hook is returned, or false if the function is not attached. When using the
     103 *                  $function_to_check argument, this function may return a non-boolean value
     104 *                  that evaluates to false (e.g.) 0, so use the === operator for testing the
     105 *                  return value.
    103106 */
    104107function has_filter($tag, $function_to_check = false) {
    … …  
    145148 * </code>
    146149 *
     150 * @since 0.71
     151 *
    147152 * @global array $wp_filter         Stores all of the filters.
    148153 * @global array $merged_filters    Merges the filter hooks using this function.
    149154 * @global array $wp_current_filter Stores the list of current filters with the current one last.
    150  *
    151  * @since 0.71
    152155 *
    153156 * @param string $tag   The name of the filter hook.
    … …  
    161164    $args = array();
    162165
    163     // Do 'all' actions first
     166    // Do 'all' actions first.
    164167    if ( isset($wp_filter['all']) ) {
    165168        $wp_current_filter[] = $tag;
    … …  
    177180        $wp_current_filter[] = $tag;
    178181
    179     // Sort
     182    // Sort.
    180183    if ( !isset( $merged_filters[ $tag ] ) ) {
    181184        ksort($wp_filter[$tag]);
    … …  
    209212 *
    210213 * @since 3.0.0
    211  * @global array $wp_filter Stores all of the filters
    212  * @global array $merged_filters Merges the filter hooks using this function.
    213  * @global array $wp_current_filter stores the list of current filters with the current one last
     214 *
     215 * @global array $wp_filter         Stores all of the filters
     216 * @global array $merged_filters    Merges the filter hooks using this function.
     217 * @global array $wp_current_filter Stores the list of current filters with the current one last
    214218 *
    215219 * @param string $tag  The name of the filter hook.
    216  * @param array  $args The arguments supplied to the functions hooked to <tt>$tag</tt>.
     220 * @param array  $args The arguments supplied to the functions hooked to $tag.
    217221 * @return mixed The filtered value after all hooked functions are applied to it.
    218222 */
    … …  
    350354 * The function current_filter() only returns the most recent filter or action
    351355 * being executed. did_action() returns true once the action is initially
    352  * processed. This function allows detection for any filter currently being
     356 * processed.
     357 *
     358 * This function allows detection for any filter currently being
    353359 * executed (despite not being the most recent filter to fire, in the case of
    354360 * hooks called from hook callbacks) to be verified.
    … …  
    362368 * @param null|string $filter Optional. Filter to check. Defaults to null, which
    363369 *                            checks if any filter is currently being run.
    364  * @return bool Whether the filter is currently in the stack
     370 * @return bool Whether the filter is currently in the stack.
    365371 */
    366372function doing_filter( $filter = null ) {
    … …  
    397403 * Action API.
    398404 *
     405 * @since 1.2.0
     406 *
    399407 * @uses add_filter() Adds an action. Parameter list and functionality are the same.
    400  *
    401  * @since 1.2.0
    402408 *
    403409 * @param string   $tag             The name of the action to which the $function_to_add is hooked.
    … …  
    425431 * apply_filters().
    426432 *
    427  * @see apply_filters() This function works similar with the exception that
    428  * nothing is returned and only the functions or methods are called.
    429  *
    430433 * @since 1.2.0
    431434 *
    432  * @global array $wp_filter Stores all of the filters
     435 * @see apply_filters() This function works similar with the exception that nothing
     436 *                      is returned and only the functions or methods are called.
     437 * @global array $wp_filter  Stores all of the filters
    433438 * @global array $wp_actions Increments the amount of times action was triggered.
    434439 *
    435  * @param string $tag      The name of the action to be executed.
    436  * @param mixed  $arg, ... Optional. Additional arguments which are passed on to the functions hooked to the action.
    437  * @return null Will return null if $tag does not exist in $wp_filter array
     440 * @param string $tag The name of the action to be executed.
     441 * @param mixed  $arg Optional. Additional arguments which are passed on to the
     442 *                    functions hooked to the action. Default empty.
     443 * @return null Will return null if $tag does not exist in $wp_filter array.
    438444 */
    439445function do_action($tag, $arg = '') {
    … …  
    495501 *
    496502 * @param string $tag The name of the action hook.
    497  * @return int The number of times action hook <tt>$tag</tt> is fired
     503 * @return int The number of times action hook $tag is fired.
    498504 */
    499505function did_action($tag) {
    … …  
    509515 * Execute functions hooked on a specific action hook, specifying arguments in an array.
    510516 *
     517 * @since 2.1.0
     518 *
    511519 * @see do_action() This function is identical, but the arguments passed to the
    512  * functions hooked to <tt>$tag</tt> are supplied using an array.
    513  *
    514  * @since 2.1.0
    515  *
    516  * @global array $wp_filter Stores all of the filters
     520 *                  functions hooked to $tag< are supplied using an array.
     521 * @global array $wp_filter  Stores all of the filters
    517522 * @global array $wp_actions Increments the amount of times action was triggered.
    518523 *
    … …  
    572577 * @param string        $tag               The name of the action hook.
    573578 * @param callback|bool $function_to_check Optional. The callback to check for. Default false.
    574  * @return mixed If $function_to_check is omitted, returns boolean for whether the hook has anything registered.
    575  *  When checking a specific function, the priority of that hook is returned, or false if the function is not attached.
    576  *  When using the $function_to_check argument, this function may return a non-boolean value that evaluates to false
    577  *  (e.g.) 0, so use the === operator for testing the return value.
     579 * @return bool|int If $function_to_check is omitted, returns boolean for whether the hook has
     580 *                  anything registered. When checking a specific function, the priority of that
     581 *                  hook is returned, or false if the function is not attached. When using the
     582 *                  $function_to_check argument, this function may return a non-boolean value
     583 *                  that evaluates to false (e.g.) 0, so use the === operator for testing the
     584 *                  return value.
    578585 */
    579586function has_action($tag, $function_to_check = false) {
    … …  
    623630 * @since 1.5.0
    624631 *
    625  * @access private
     632 * @uses WP_PLUGIN_DIR, WPMU_PLUGIN_DIR
    626633 *
    627634 * @param string $file The filename of plugin.
    628635 * @return string The name of a plugin.
    629  * @uses WP_PLUGIN_DIR
    630636 */
    631637function plugin_basename( $file ) {
    … …  
    684690
    685691/**
    686  * Gets the filesystem directory path (with trailing slash) for the plugin __FILE__ passed in
     692 * Get the filesystem directory path (with trailing slash) for the plugin __FILE__ passed in.
    687693 *
    688694 * @since 2.8.0
    689695 *
    690  * @param string $file The filename of the plugin (__FILE__)
    691  * @return string the filesystem path of the directory that contains the plugin
     696 * @param string $file The filename of the plugin (__FILE__).
     697 * @return string the filesystem path of the directory that contains the plugin.
    692698 */
    693699function plugin_dir_path( $file ) {
    … …  
    696702
    697703/**
    698  * Gets the URL directory path (with trailing slash) for the plugin __FILE__ passed in
     704 * Get the URL directory path (with trailing slash) for the plugin __FILE__ passed in.
    699705 *
    700706 * @since 2.8.0
    701707 *
    702  * @param string $file The filename of the plugin (__FILE__)
    703  * @return string the URL path of the directory that contains the plugin
     708 * @param string $file The filename of the plugin (__FILE__).
     709 * @return string the URL path of the directory that contains the plugin.
    704710 */
    705711function plugin_dir_url( $file ) {
    … …  
    722728 * @since 2.0.0
    723729 *
    724  * @param string $file The filename of the plugin including the path.
    725  * @param callback $function the function hooked to the 'activate_PLUGIN' action.
     730 * @param string   $file    The filename of the plugin including the path.
     731 * @param callback $function The function hooked to the 'activate_PLUGIN' action.
    726732 */
    727733function register_activation_hook($file, $function) {
    … …  
    745751 * @since 2.0.0
    746752 *
    747  * @param string $file The filename of the plugin including the path.
    748  * @param callback $function the function hooked to the 'deactivate_PLUGIN' action.
     753 * @param string   $file    The filename of the plugin including the path.
     754 * @param callback $function The function hooked to the 'deactivate_PLUGIN' action.
    749755 */
    750756function register_deactivation_hook($file, $function) {
    … …  
    775781 * @since 2.7.0
    776782 *
    777  * @param string $file
    778  * @param callback $callback The callback to run when the hook is called. Must be a static method or function.
     783 * @param string   $file     Plugin file.
     784 * @param callback $callback The callback to run when the hook is called. Must be
     785 *                           a static method or function.
    779786 */
    780787function register_uninstall_hook( $file, $callback ) {
    … …  
    784791    }
    785792
    786     // The option should not be autoloaded, because it is not needed in most
    787     // cases. Emphasis should be put on using the 'uninstall.php' way of
    788     // uninstalling the plugin.
     793    /*
     794     * The option should not be autoloaded, because it is not needed in most
     795     * cases. Emphasis should be put on using the 'uninstall.php' way of
     796     * uninstalling the plugin.
     797     */
    789798    $uninstallable_plugins = (array) get_option('uninstall_plugins');
    790799    $uninstallable_plugins[plugin_basename($file)] = $callback;
     800
    791801    update_option('uninstall_plugins', $uninstallable_plugins);
    792802}
    793803
    794804/**
    795  * Calls the 'all' hook, which will process the functions hooked into it.
     805 * Call the 'all' hook, which will process the functions hooked into it.
    796806 *
    797807 * The 'all' hook passes all of the arguments or parameters that were used for
    … …  
    806816 * @access private
    807817 *
    808  * @uses $wp_filter Used to process all of the functions in the 'all' hook
     818 * @uses $wp_filter Used to process all of the functions in the 'all' hook.
    809819 *
    810820 * @param array $args The collected parameters from the hook that was called.
    … …  
    839849 * shouldn't have any speed penalty.
    840850 *
     851 * @link http://trac.wordpress.org/ticket/3875
     852 *
     853 * @since 2.2.3
    841854 * @access private
    842  * @since 2.2.3
    843  * @link http://trac.wordpress.org/ticket/3875
    844  *
    845  * @global array $wp_filter Storage for all of the filters and actions
    846  * @param string $tag Used in counting how many hooks were applied
     855 *
     856 * @global array $wp_filter Storage for all of the filters and actions.
     857 *
     858 * @param string   $tag      Used in counting how many hooks were applied
    847859 * @param callback $function Used for creating unique id
    848  * @param int|bool $priority Used in counting how many hooks were applied. If === false and $function is an object reference, we return the unique id only if it already has one, false otherwise.
    849  * @return string|bool Unique ID for usage as array key or false if $priority === false and $function is an object reference, and it does not already have a unique id.
     860 * @param int|bool $priority Used in counting how many hooks were applied. If === false
     861 *                           and $function is an object reference, we return the unique
     862 *                           id only if it already has one, false otherwise.
     863 * @return string|bool Unique ID for usage as array key or false if $priority === false
     864 *                     and $function is an object reference, and it does not already have
     865 *                     a unique id.
    850866 */
    851867function _wp_filter_build_unique_id($tag, $function, $priority) {
Note: See TracChangeset for help on using the changeset viewer.