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

Improve various `@param` docs for `src/wp-includes/*`. 

See #30224.

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


git-svn-id: http://core.svn.wordpress.org/trunk@30671 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Scott Taylor 2014-12-01 01:34:24 +00:00
parent 2c32752abd
commit e619abda6e
23 changed files with 111 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
wp-includes/bookmark.php
View File

@ -13,7 +13,7 @@
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param mixed $bookmark
* @param int|stdClass $bookmark
* @param string $output Optional. Either OBJECT, ARRAY_N, or ARRAY_A constant
* @param string $filter Optional, default is 'raw'.
* @return array|object Type returned depends on $output value.

3
wp-includes/cache.php
View File

@ -664,6 +664,9 @@ class WP_Object_Cache {
* @since 3.4.0
*
* @access protected
* @param string $key
* @param string $group
* @return bool
*/
protected function _exists( $key, $group ) {
return isset( $this->cache[ $group ] ) && ( isset( $this->cache[ $group ][ $key ] ) || array_key_exists( $key, $this->cache[ $group ] ) );

3
wp-includes/canonical.php
View File

@ -492,6 +492,9 @@ function redirect_canonical( $requested_url = null, $do_redirect = true ) {
* @since 3.4.0
* @access private
*
* @param string $query_string
* @param array $args_to_check
* @param string $url
* @return string The altered query string
*/
function _remove_qs_args_if_not_in_url( $query_string, Array $args_to_check, $url ) {

4
wp-includes/capabilities.php
View File

@ -611,6 +611,8 @@ class WP_User {
* Magic method for checking the existence of a certain custom field
*
* @since 3.3.0
* @param string $key
* @return bool
*/
public function __isset( $key ) {
if ( 'id' == $key ) {
@ -631,6 +633,8 @@ class WP_User {
* Magic method for accessing custom fields
*
* @since 3.3.0
* @param string $key
* @return mixed
*/
public function __get( $key ) {
if ( 'id' == $key ) {

8
wp-includes/category-template.php
View File

@ -458,7 +458,7 @@ function wp_dropdown_categories( $args = '' ) {
* @since 2.1.0
*
* @param string|array $args Optional. Override default arguments.
* @return string HTML content only if 'echo' argument is 0.
* @return false|null|string HTML content only if 'echo' argument is 0.
*/
function wp_list_categories( $args = '' ) {
$defaults = array(
@ -586,8 +586,8 @@ function wp_list_categories( $args = '' ) {
*
* @since 2.3.0
*
* @param array|string $args Optional. Override default arguments.
* @return array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
* @param array|string|null $args Optional. Override default arguments.
* @return null|false Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
*/
function wp_tag_cloud( $args = '' ) {
$defaults = array(
@ -1321,7 +1321,7 @@ function get_the_term_list( $id, $taxonomy, $before = '', $sep = '', $after = ''
* @param string $before Optional. Before list.
* @param string $sep Optional. Separate items using this.
* @param string $after Optional. After list.
* @return null|bool False on WordPress error. Returns null when displaying.
* @return false|null False on WordPress error. Returns null when displaying.
*/
function the_terms( $id, $taxonomy, $before = '', $sep = ', ', $after = '' ) {
$term_list = get_the_term_list( $id, $taxonomy, $before, $sep, $after );

6
wp-includes/class-http.php
View File

@ -299,7 +299,7 @@ class WP_Http {
* @param array $args Request arguments
* @param string $url URL to Request
*
* @return string|bool Class name for the first transport that claims to support the request. False if no transport claims to support the request.
* @return string|false Class name for the first transport that claims to support the request. False if no transport claims to support the request.
*/
public function _get_first_available_transport( $args, $url = null ) {
/**
@ -2080,7 +2080,7 @@ class WP_Http_Encoding {
* @param string $raw String to compress.
* @param int $level Optional, default is 9. Compression level, 9 is highest.
* @param string $supports Optional, not used. When implemented it will choose the right compression based on what the server supports.
* @return string|bool False on failure.
* @return string|false False on failure.
*/
public static function compress( $raw, $level = 9, $supports = null ) {
return gzdeflate( $raw, $level );
@ -2180,6 +2180,8 @@ class WP_Http_Encoding {
*
* @since 2.8.0
*
* @param string $url
* @param array $args
* @return string Types of encoding to accept.
*/
public static function accept_encoding( $url, $args ) {

4
wp-includes/class-oembed.php
View File

@ -270,7 +270,7 @@ class WP_oEmbed {
*
* @param string $url The URL to the content that should be attempted to be embedded.
* @param array $args Optional arguments. Usually passed from a shortcode.
* @return bool|string False on failure, otherwise the UNSANITIZED (and potentially unsafe) HTML that should be used to embed.
* @return false|string False on failure, otherwise the UNSANITIZED (and potentially unsafe) HTML that should be used to embed.
*/
function get_html( $url, $args = '' ) {
$provider = $this->get_provider( $url, $args );
@ -496,7 +496,7 @@ class WP_oEmbed {
*
* @param object $data A data object result from an oEmbed provider.
* @param string $url The URL to the content that is desired to be embedded.
* @return bool|string False on error, otherwise the HTML needed to embed.
* @return false|string False on error, otherwise the HTML needed to embed.
*/
public function data2html( $data, $url ) {
if ( ! is_object( $data ) || empty( $data->type ) )

8
wp-includes/class-wp-editor.php
View File

@ -250,6 +250,10 @@ final class _WP_Editors {
self::editor_settings($editor_id, $set);
}
/**
* @param string $editor_id
* @param array $set
*/
public static function editor_settings($editor_id, $set) {
$first_run = false;
@ -756,7 +760,7 @@ final class _WP_Editors {
*
* @param string $mce_locale The locale used for the editor.
* @param bool $json_only optional Whether to include the Javascript calls to tinymce.addI18n() and tinymce.ScriptLoader.markDone().
* @return The translation object, JSON encoded.
* @return string Translation object, JSON encoded.
*/
public static function wp_mce_translation( $mce_locale = '', $json_only = false ) {
@ -1328,7 +1332,7 @@ final class _WP_Editors {
* @since 3.1.0
*
* @param array $args Optional. Accepts 'pagenum' and 's' (search) arguments.
* @return array Results.
* @return false|array Results.
*/
public static function wp_link_query( $args = array() ) {
$pts = get_post_types( array( 'public' => true ), 'objects' );

2
wp-includes/class-wp-embed.php
View File

@ -334,7 +334,7 @@ class WP_Embed {
* Conditionally makes a hyperlink based on an internal class variable.
*
* @param string $url URL to potentially be linked.
* @return string|bool Linked URL or the original URL. False if 'return_false_on_fail' is true.
* @return false|string Linked URL or the original URL. False if 'return_false_on_fail' is true.
*/
public function maybe_make_link( $url ) {
if ( $this->return_false_on_fail ) {

2
wp-includes/class-wp-error.php
View File

@ -242,7 +242,7 @@ class WP_Error {
$this->error_data[$code] = $data;
}
/**
* Removes the specified error.
*

6
wp-includes/class-wp-http-ixr-client.php
View File

@ -13,6 +13,12 @@ class WP_HTTP_IXR_Client extends IXR_Client {
*/
public $error;
/**
* @param string $server
* @param string|bool $path
* @param int|bool $port
* @param int $timeout
*/
public function __construct($server, $path = false, $port = false, $timeout = 15) {
if ( ! $path ) {
// Assume we have been given a URL instead

11
wp-includes/class-wp-image-editor-gd.php
View File

@ -255,7 +255,6 @@ class WP_Image_Editor_GD extends WP_Image_Editor {
* @since 3.5.0
* @access public
*
* @param string|int $src The source file or Attachment ID.
* @param int $src_x The start x position to crop from.
* @param int $src_y The start y position to crop from.
* @param int $src_w The width to crop.
@ -355,8 +354,8 @@ class WP_Image_Editor_GD extends WP_Image_Editor {
* @since 3.5.0
* @access public
*
* @param string $destfilename
* @param string $mime_type
* @param string|null $filename
* @param string|null $mime_type
* @return array|WP_Error {'path'=>string, 'file'=>string, 'width'=>int, 'height'=>int, 'mime-type'=>string}
*/
public function save( $filename = null, $mime_type = null ) {
@ -370,6 +369,12 @@ class WP_Image_Editor_GD extends WP_Image_Editor {
return $saved;
}
/**
* @param resource $image
* @param string|null $filename
* @param string|null $mime_type
* @return WP_Error|array
*/
protected function _save( $image, $filename = null, $mime_type = null ) {
list( $filename, $extension, $mime_type ) = $this->get_output_format( $filename, $mime_type );

2
wp-includes/class-wp-theme.php
View File

@ -1033,7 +1033,7 @@ final class WP_Theme implements ArrayAccess {
* @since 3.4.0
* @access public
*
* @return True if the textdomain was successfully loaded or has already been loaded. False if
* @return bool If the textdomain was successfully loaded or has already been loaded. False if
* no textdomain was specified in the file headers, or if the domain could not be loaded.
*/
public function load_textdomain() {

8
wp-includes/class-wp-xmlrpc-server.php
View File

@ -4630,6 +4630,10 @@ class wp_xmlrpc_server extends IXR_Server {
return strval($post_ID);
}
/**
* @param integer $post_ID
* @param array $enclosure
*/
public function add_enclosure_if_new( $post_ID, $enclosure ) {
if ( is_array( $enclosure ) && isset( $enclosure['url'] ) && isset( $enclosure['length'] ) && isset( $enclosure['type'] ) ) {
$encstring = $enclosure['url'] . "\n" . $enclosure['length'] . "\n" . $enclosure['type'] . "\n";
@ -5914,6 +5918,10 @@ class wp_xmlrpc_server extends IXR_Server {
return $pingbacks;
}
/**
* @param integer $code
* @param string $message
*/
protected function pingback_error( $code, $message ) {
/**
* Filter the XML-RPC pingback error return.

29
wp-includes/class.wp-styles.php
View File

@ -39,6 +39,10 @@ class WP_Styles extends WP_Dependencies {
do_action_ref_array( 'wp_default_styles', array(&$this) );
}
/**
* @param string $handle
* @return bool
*/
public function do_item( $handle ) {
if ( !parent::do_item($handle) )
return false;
@ -119,6 +123,10 @@ class WP_Styles extends WP_Dependencies {
return true;
}
/**
* @param string $handle
* @param string $code
*/
public function add_inline_style( $handle, $code ) {
if ( ! $code ) {
return false;
@ -134,6 +142,11 @@ class WP_Styles extends WP_Dependencies {
return $this->add_data( $handle, 'after', $after );
}
/**
* @param string $handle
* @param bool $echo
* @return bool
*/
public function print_inline_style( $handle, $echo = true ) {
$output = $this->get_data( $handle, 'after' );
@ -152,6 +165,12 @@ class WP_Styles extends WP_Dependencies {
return true;
}
/**
* @param mixed $handles
* @param bool $recursion
* @param mixed $group
* @return bool
*/
public function all_deps( $handles, $recursion = false, $group = false ) {
$r = parent::all_deps( $handles, $recursion );
if ( !$recursion ) {
@ -167,6 +186,12 @@ class WP_Styles extends WP_Dependencies {
return $r;
}
/**
* @param string $src
* @param string $ver
* @param string $handle
* @return string
*/
public function _css_href( $src, $ver, $handle ) {
if ( !is_bool($src) && !preg_match('|^(https?:)?//|', $src) && ! ( $this->content_url && 0 === strpos($src, $this->content_url) ) ) {
$src = $this->base_url . $src;
@ -187,6 +212,10 @@ class WP_Styles extends WP_Dependencies {
return esc_url( $src );
}
/**
* @param string $src
* @return bool
*/
public function in_default_dir($src) {
if ( ! $this->default_dirs )
return true;

6
wp-includes/comment-template.php
View File

@ -707,7 +707,7 @@ function get_comments_link( $post_id = 0 ) {
* @since 0.71
*
* @param string $deprecated Not Used.
* @param bool $deprecated_2 Not Used.
* @param string $deprecated_2 Not Used.
*/
function comments_link( $deprecated = '', $deprecated_2 = '' ) {
if ( !empty( $deprecated ) )
@ -1353,7 +1353,7 @@ function comments_popup_link( $zero = false, $one = false, $more = false, $css_c
* @param int $comment Comment being replied to. Default current comment.
* @param int|WP_Post $post Post ID or WP_Post object the comment is going to be displayed on.
* Default current post.
* @return mixed Link to show comment form, if successful. False, if comments are closed.
* @return null|false|string Link to show comment form, if successful. False, if comments are closed.
*/
function get_comment_reply_link( $args = array(), $comment = null, $post = null ) {
@ -1466,7 +1466,7 @@ function comment_reply_link($args = array(), $comment = null, $post = null) {
* }
* @param int|WP_Post $post Optional. Post ID or WP_Post object the comment is going to be displayed on.
* Default current post.
* @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
* @return false|null|string Link to show comment form, if successful. False, if comments are closed.
*/
function get_post_reply_link($args = array(), $post = null) {
$defaults = array(

6
wp-includes/comment.php
View File

@ -1745,7 +1745,7 @@ function wp_unspam_comment($comment_id) {
* @since 1.0.0
*
* @param int $comment_id Comment ID
* @return string|bool Status might be 'trash', 'approved', 'unapproved', 'spam'. False on failure.
* @return false|string Status might be 'trash', 'approved', 'unapproved', 'spam'. False on failure.
*/
function wp_get_comment_status($comment_id) {
$comment = get_comment($comment_id);
@ -2298,7 +2298,7 @@ function wp_defer_comment_counting($defer=null) {
*
* @param int $post_id Post ID
* @param bool $do_deferred Whether to process previously deferred post comment counts
* @return bool True on success, false on failure
* @return bool|null True on success, false on failure
*/
function wp_update_comment_count($post_id, $do_deferred=false) {
static $_deferred = array();
@ -2376,7 +2376,7 @@ function wp_update_comment_count_now($post_id) {
*
* @param string $url URL to ping.
* @param int $deprecated Not Used.
* @return bool|string False on failure, string containing URI on success.
* @return false|string False on failure, string containing URI on success.
*/
function discover_pingback_server_uri( $url, $deprecated = '' ) {
if ( !empty( $deprecated ) )

4
wp-includes/cron.php
View File

@ -66,7 +66,7 @@ function wp_schedule_single_event( $timestamp, $hook, $args = array()) {
* @param string $recurrence How often the event should recur.
* @param string $hook Action hook to execute when cron is run.
* @param array $args Optional. Arguments to pass to the hook's callback function.
* @return bool|null False on failure, null when complete with scheduling event.
* @return false|null False on failure, null when complete with scheduling event.
*/
function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array()) {
$crons = _get_cron_array();
@ -99,7 +99,7 @@ function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array()) {
* @param string $recurrence How often the event should recur.
* @param string $hook Action hook to execute when cron is run.
* @param array $args Optional. Arguments to pass to the hook's callback function.
* @return bool|null False on failure. Null when event is rescheduled.
* @return false|null False on failure. Null when event is rescheduled.
*/
function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array() ) {
$crons = _get_cron_array();

6
wp-includes/date.php
View File

@ -185,7 +185,9 @@ class WP_Date_Query {
* @since 4.1.0
* @access public
*
* @param array $query A tax_query query clause.
* @param array $queries
* @param array $parent_query
*
* @return array Sanitized queries.
*/
public function sanitize_query( $queries, $parent_query = null ) {
@ -777,7 +779,7 @@ class WP_Date_Query {
*
* @param string $compare The compare operator to use
* @param string|array $value The value
* @return string|int|false The value to be used in SQL or false on error.
* @return string|false|int The value to be used in SQL or false on error.
*/
public function build_value( $compare, $value ) {
if ( ! isset( $value ) )

26
wp-includes/deprecated.php
View File

@ -427,7 +427,7 @@ function get_linksbyname($cat_name = "noname", $before = '', $after = '<br />',
*
* @param string $category The category to use.
* @param string $args
* @return bool|null
* @return string|null
*/
function wp_get_linksbyname($category, $args = '') {
_deprecated_function(__FUNCTION__, '2.1', 'wp_list_bookmarks()');
@ -578,7 +578,7 @@ function get_linksbyname_withrating($cat_name = "noname", $before = '', $after =
* underscore the order will be reversed. You can also specify 'rand' as the
* order which will return links in a random order.
* @param bool $show_description Whether to show the description if show_images=false/not defined.
* @param string $limit Limit to X entries. If not specified, all entries are shown.
* @param int $limit Limit to X entries. If not specified, all entries are shown.
* @param int $show_updated Whether to show last updated timestamp
*/
function get_links_withrating($category = -1, $before = '', $after = '<br />', $between = " ", $show_images = true,
@ -627,7 +627,7 @@ function get_autotoggle($id = 0) {
* @param string $feed_image
* @param string $exclude
* @param bool $hierarchical
* @return string
* @return false|null
*/
function list_cats($optionall = 1, $all = 'All', $sort_column = 'ID', $sort_order = 'asc', $file = '', $list = true, $optiondates = 0,
$optioncount = 0, $hide_empty = 1, $use_desc_for_title = 1, $children=false, $child_of=0, $categories=0,
@ -646,7 +646,7 @@ function list_cats($optionall = 1, $all = 'All', $sort_column = 'ID', $sort_orde
* @see wp_list_categories()
*
* @param string|array $args
* @return string
* @return false|null|string
*/
function wp_list_cats($args = '') {
_deprecated_function( __FUNCTION__, '2.1', 'wp_list_categories()' );
@ -1156,7 +1156,7 @@ function comments_rss_link($link_text = 'Comments RSS') {
*
* @param bool $echo
* @param int $cat_ID
* @return string|null
* @return string
*/
function get_category_rss_link($echo = false, $cat_ID = 1) {
_deprecated_function( __FUNCTION__, '2.5', 'get_category_feed_link()' );
@ -1178,7 +1178,7 @@ function get_category_rss_link($echo = false, $cat_ID = 1) {
*
* @param bool $echo
* @param int $author_id
* @return string|null
* @return string
*/
function get_author_rss_link($echo = false, $author_id = 1) {
_deprecated_function( __FUNCTION__, '2.5', 'get_author_feed_link()' );
@ -1657,7 +1657,7 @@ function the_author_url() {
* @deprecated Use get_the_author_meta('ID')
* @see get_the_author_meta()
*
* @return int The author's ID.
* @return string|int The author's ID.
*/
function get_the_author_ID() {
_deprecated_function( __FUNCTION__, '2.8', 'get_the_author_meta(\'ID\')' );
@ -1701,7 +1701,7 @@ function the_author_ID() {
* @see the_content_feed()
*
* @param string $more_link_text Optional. Text to display when more content is available but not displayed.
* @param int|bool $stripteaser Optional. Default is 0.
* @param int $stripteaser Optional. Default is 0.
* @param string $more_file Optional.
* @param int $cut Optional. Amount of words to keep for the content.
* @param int $encode_html Optional. How to encode the content.
@ -1960,7 +1960,7 @@ function get_attachment_icon_src( $id = 0, $fullsize = false ) {
* @param int $id Optional. Post ID.
* @param bool $fullsize Optional, default to false. Whether to have full size image.
* @param array $max_dims Optional. Dimensions of image.
* @return string HTML content.
* @return false|string HTML content.
*/
function get_attachment_icon( $id = 0, $fullsize = false, $max_dims = false ) {
_deprecated_function( __FUNCTION__, '2.5', 'wp_get_attachment_image()' );
@ -2017,7 +2017,7 @@ function get_attachment_icon( $id = 0, $fullsize = false, $max_dims = false ) {
* @param int $id Optional. Post ID.
* @param bool $fullsize Optional, default to false. Whether to have full size image.
* @param array $max_dims Optional. Dimensions of image.
* @return string
* @return false|string
*/
function get_attachment_innerHTML($id = 0, $fullsize = false, $max_dims = false) {
_deprecated_function( __FUNCTION__, '2.5', 'wp_get_attachment_image()' );
@ -3041,7 +3041,7 @@ function add_custom_image_header( $wp_head_callback, $admin_head_callback, $admi
* @deprecated Use remove_theme_support('custom-header')
* @see remove_theme_support()
*
* @return bool Whether support was removed.
* @return null|bool Whether support was removed.
*/
function remove_custom_image_header() {
_deprecated_function( __FUNCTION__, '3.4', 'remove_theme_support( \'custom-header\' )' );
@ -3078,7 +3078,7 @@ function add_custom_background( $wp_head_callback = '', $admin_head_callback = '
* @since 3.1.0
* @see add_custom_background()
*
* @return bool Whether support was removed.
* @return null|bool Whether support was removed.
*/
function remove_custom_background() {
_deprecated_function( __FUNCTION__, '3.4', 'remove_theme_support( \'custom-background\' )' );
@ -3292,7 +3292,7 @@ function image_resize( $file, $max_w, $max_h, $crop = false, $suffix = null, $de
*
* @param int $postid Post ID.
* @param string $mode How to return result, either OBJECT, ARRAY_N, or ARRAY_A.
* @return object|array Post object or array holding post contents and information
* @return WP_Post|null Post object or array holding post contents and information
*/
function wp_get_single_post( $postid = 0, $mode = OBJECT ) {
_deprecated_function( __FUNCTION__, '3.5', 'get_post()' );

2
wp-includes/feed.php
View File

@ -276,7 +276,7 @@ function comment_guid($comment_id = null) {
* @since 2.5.0
*
* @param int|object $comment_id Optional comment object or id. Defaults to global comment object.
* @return bool|string false on failure or guid for comment on success.
* @return false|string false on failure or guid for comment on success.
*/
function get_comment_guid($comment_id = null) {
$comment = get_comment($comment_id);

6
wp-includes/formatting.php
View File

@ -577,7 +577,7 @@ function seems_utf8($str) {
* @access private
*
* @param string $string The text which is to be encoded.
* @param mixed $quote_style Optional. Converts double quotes if set to ENT_COMPAT, both single and double if set to ENT_QUOTES or none if set to ENT_NOQUOTES. Also compatible with old values; converting single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default is ENT_NOQUOTES.
* @param int $quote_style Optional. Converts double quotes if set to ENT_COMPAT, both single and double if set to ENT_QUOTES or none if set to ENT_NOQUOTES. Also compatible with old values; converting single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default is ENT_NOQUOTES.
* @param string $charset Optional. The character encoding of the string. Default is false.
* @param boolean $double_encode Optional. Whether to encode existing html entities. Default is false.
* @return string The encoded text with HTML entities.
@ -1317,7 +1317,7 @@ function sanitize_title_with_dashes( $title, $raw_title = '', $context = 'displa
* @since 2.5.1
*
* @param string $orderby Order by string to be checked.
* @return string|bool Returns the order by clause if it is a match, false otherwise.
* @return false|string Returns the order by clause if it is a match, false otherwise.
*/
function sanitize_sql_orderby( $orderby ){
preg_match('/^\s*([a-z0-9_]+(\s+(ASC|DESC))?(\s*,\s*|\s*$))+|^\s*RAND\(\s*\)\s*$/i', $orderby, $obmatches);
@ -2219,7 +2219,7 @@ function wp_iso_descrambler($string) {
* @access private
*
* @param array $match The preg_replace_callback matches array
* @return array Converted chars
* @return string Converted chars
*/
function _wp_iso_convert( $match ) {
return chr( hexdec( strtolower( $match[1] ) ) );

2
wp-includes/version.php
View File

@ -4,7 +4,7 @@
*
* @global string $wp_version
*/
$wp_version = '4.1-beta2-30680';
$wp_version = '4.1-beta2-30681';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.