From 683acd8245d47fd667b8f5cb8a844769c8fd5a36 Mon Sep 17 00:00:00 2001 From: ryan Date: Sun, 22 Jun 2008 20:23:23 +0000 Subject: [PATCH] phpdoc updates from jacobsantos. see #7038 git-svn-id: http://svn.automattic.com/wordpress/trunk@8164 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/comment-template.php | 132 ++++---- wp-includes/pluggable.php | 262 ++++++++-------- wp-includes/taxonomy.php | 487 +++++++++++++++++------------ wp-includes/wp-db.php | 515 +++++++++++++++++++++++++++---- 4 files changed, 944 insertions(+), 452 deletions(-) diff --git a/wp-includes/comment-template.php b/wp-includes/comment-template.php index 2cb3e6b6d8..a04741739b 100644 --- a/wp-includes/comment-template.php +++ b/wp-includes/comment-template.php @@ -9,10 +9,10 @@ */ /** - * get_comment_author() - Retrieve the author of the current comment + * Retrieve the author of the current comment. * - * If the comment has an empty comment_author field, then 'Anonymous' person - * is assumed. + * If the comment has an empty comment_author field, then 'Anonymous' person is + * assumed. * * @since 1.5 * @uses apply_filters() Calls 'get_comment_author' hook on the comment author @@ -29,7 +29,7 @@ function get_comment_author() { } /** - * comment_author() - Displays the author of the current comment + * Displays the author of the current comment. * * @since 0.71 * @uses apply_filters() Calls 'comment_author' on comment author before displaying @@ -40,7 +40,7 @@ function comment_author() { } /** - * get_comment_author_email() - Retrieve the email of the author of the current comment + * Retrieve the email of the author of the current comment. * * @since 1.5 * @uses apply_filters() Calls the 'get_comment_author_email' hook on the comment author email @@ -54,12 +54,13 @@ function get_comment_author_email() { } /** - * comment_author_email() - Display the email of the author of the current global $comment + * Display the email of the author of the current global $comment. * - * Care should be taken to protect the email address and assure that email harvesters - * do not capture your commentors' email address. Most assume that their email address will - * not appear in raw form on the blog. Doing so will enable anyone, including those that - * people don't want to get the email address and use it for their own means good and bad. + * Care should be taken to protect the email address and assure that email + * harvesters do not capture your commentors' email address. Most assume that + * their email address will not appear in raw form on the blog. Doing so will + * enable anyone, including those that people don't want to get the email + * address and use it for their own means good and bad. * * @since 0.71 * @uses apply_filters() Calls 'author_email' hook on the author email @@ -69,12 +70,13 @@ function comment_author_email() { } /** - * comment_author_email_link() - Display the html email link to the author of the current comment + * Display the html email link to the author of the current comment. * - * Care should be taken to protect the email address and assure that email harvesters - * do not capture your commentors' email address. Most assume that their email address will - * not appear in raw form on the blog. Doing so will enable anyone, including those that - * people don't want to get the email address and use it for their own means good and bad. + * Care should be taken to protect the email address and assure that email + * harvesters do not capture your commentors' email address. Most assume that + * their email address will not appear in raw form on the blog. Doing so will + * enable anyone, including those that people don't want to get the email + * address and use it for their own means good and bad. * * @since 0.71 * @uses apply_filters() Calls 'comment_email' hook for the display of the comment author's email @@ -96,7 +98,7 @@ function comment_author_email_link($linktext='', $before='', $after='') { } /** - * get_comment_author_link() - Retrieve the html link to the url of the author of the current comment + * Retrieve the html link to the url of the author of the current comment. * * @since 1.5 * @uses apply_filters() Calls 'get_comment_author_link' hook on the complete link HTML or author @@ -116,7 +118,7 @@ function get_comment_author_link() { } /** - * comment_author_link() - Display the html link to the url of the author of the current comment + * Display the html link to the url of the author of the current comment. * * @since 0.71 * @see get_comment_author_link() Echos result @@ -126,7 +128,7 @@ function comment_author_link() { } /** - * get_comment_author_IP() - Retrieve the IP address of the author of the current comment + * Retrieve the IP address of the author of the current comment. * * @since 1.5 * @uses $comment @@ -140,7 +142,7 @@ function get_comment_author_IP() { } /** - * comment_author_IP() - Displays the IP address of the author of the current comment + * Display the IP address of the author of the current comment. * * @since 0.71 * @see get_comment_author_IP() Echos Result @@ -150,7 +152,7 @@ function comment_author_IP() { } /** - * get_comment_author_url() - Returns the url of the author of the current comment + * Retrieve the url of the author of the current comment. * * @since 1.5 * @uses apply_filters() Calls 'get_comment_author_url' hook on the comment author's URL @@ -163,7 +165,7 @@ function get_comment_author_url() { } /** - * comment_author_url() - Display the url of the author of the current comment + * Display the url of the author of the current comment. * * @since 0.71 * @uses apply_filters() @@ -174,13 +176,14 @@ function comment_author_url() { } /** - * get_comment_author_url_link() - Retrieves the HTML link of the url of the author of the current comment + * Retrieves the HTML link of the url of the author of the current comment. * - * $linktext parameter is only used if the URL does not exist for the comment author. If the URL does - * exist then the URL will be used and the $linktext will be ignored. + * $linktext parameter is only used if the URL does not exist for the comment + * author. If the URL does exist then the URL will be used and the $linktext + * will be ignored. * - * Encapsulate the HTML link between the $before and $after. So it will appear in the order of $before, - * link, and finally $after. + * Encapsulate the HTML link between the $before and $after. So it will appear + * in the order of $before, link, and finally $after. * * @since 1.5 * @uses apply_filters() Calls the 'get_comment_author_url_link' on the complete HTML before returning. @@ -202,7 +205,7 @@ function get_comment_author_url_link( $linktext = '', $before = '', $after = '' } /** - * comment_author_url_link() - Displays the HTML link of the url of the author of the current comment + * Displays the HTML link of the url of the author of the current comment. * * @since 0.71 * @see get_comment_author_url_link() Echos result @@ -216,7 +219,7 @@ function comment_author_url_link( $linktext = '', $before = '', $after = '' ) { } /** - * get_comment_date() - Retrieve the comment date of the current comment + * Retrieve the comment date of the current comment. * * @since 1.5 * @uses apply_filters() Calls 'get_comment_date' hook with the formated date and the $d parameter respectively @@ -235,7 +238,7 @@ function get_comment_date( $d = '' ) { } /** - * comment_date() - Display the comment date of the current comment + * Display the comment date of the current comment. * * @since 0.71 * @@ -246,7 +249,7 @@ function comment_date( $d = '' ) { } /** - * get_comment_excerpt() - Retrieve the excerpt of the current comment + * Retrieve the excerpt of the current comment. * * Will cut each word and only output the first 20 words with '...' at the end. * If the word count is less than 20, then no truncating is done and no '...' @@ -278,7 +281,7 @@ function get_comment_excerpt() { } /** - * comment_excerpt() - Returns the excerpt of the current comment + * Display the excerpt of the current comment. * * @since 1.2 * @uses apply_filters() Calls 'comment_excerpt' hook before displaying excerpt @@ -288,7 +291,7 @@ function comment_excerpt() { } /** - * get_comment_ID() - Retrieve the comment id of the current comment + * Retrieve the comment id of the current comment. * * @since 1.5 * @uses $comment @@ -302,7 +305,7 @@ function get_comment_ID() { } /** - * comment_ID() - Displays the comment id of the current comment + * Displays the comment id of the current comment. * * @since 0.71 * @see get_comment_ID() Echos Result @@ -312,7 +315,7 @@ function comment_ID() { } /** - * get_comment_link() - Retrieve the link to the current comment + * Retrieve the link to the current comment. * * @since 1.5 * @uses $comment @@ -325,7 +328,7 @@ function get_comment_link() { } /** - * get_comments_link() - Retrieves the link to the current post comments + * Retrieves the link to the current post comments. * * @since 1.5 * @@ -336,7 +339,7 @@ function get_comments_link() { } /** - * comments_link() - Displays the link to the current post comments + * Displays the link to the current post comments. * * @since 0.71 * @@ -348,7 +351,7 @@ function comments_link( $deprecated = '', $deprecated = '' ) { } /** - * get_comments_number() - Retrieve the amount of comments a post has + * Retrieve the amount of comments a post has. * * @since 1.5 * @uses apply_filters() Calls the 'get_comments_number' hook on the number of comments @@ -373,7 +376,7 @@ function get_comments_number( $post_id = 0 ) { } /** - * comments_number() - Display the language string for the number of comments the current post has + * Display the language string for the number of comments the current post has. * * @since 0.71 * @uses $id @@ -399,7 +402,7 @@ function comments_number( $zero = false, $one = false, $more = false, $deprecate } /** - * get_comment_text() - Retrieve the text of the current comment + * Retrieve the text of the current comment. * * @since 1.5 * @uses $comment @@ -412,7 +415,7 @@ function get_comment_text() { } /** - * comment_text() - Displays the text of the current comment + * Displays the text of the current comment. * * @since 0.71 * @uses apply_filters() Passes the comment content through the 'comment_text' hook before display @@ -423,7 +426,7 @@ function comment_text() { } /** - * get_comment_time() - Retrieve the comment time of the current comment + * Retrieve the comment time of the current comment. * * @since 1.5 * @uses $comment @@ -444,7 +447,7 @@ function get_comment_time( $d = '', $gmt = false ) { } /** - * comment_time() - Display the comment time of the current comment + * Display the comment time of the current comment. * * @since 0.71 * @@ -455,7 +458,7 @@ function comment_time( $d = '' ) { } /** - * get_comment_type() - Retrieve the comment type of the current comment + * Retrieve the comment type of the current comment. * * @since 1.5 * @uses $comment @@ -473,7 +476,7 @@ function get_comment_type() { } /** - * comment_type() - Display the comment type of the current comment + * Display the comment type of the current comment. * * @since 0.71 * @@ -496,11 +499,11 @@ function comment_type($commenttxt = 'Comment', $trackbacktxt = 'Trackback', $pin } /** - * get_trackback_url() - Retrieve The current post's trackback URL + * Retrieve The current post's trackback URL. * - * There is a check to see if permalink's have been enabled and if so, will retrieve - * the pretty path. If permalinks weren't enabled, the ID of the current post is used - * and appended to the correct page to go to. + * There is a check to see if permalink's have been enabled and if so, will + * retrieve the pretty path. If permalinks weren't enabled, the ID of the + * current post is used and appended to the correct page to go to. * * @since 1.5 * @uses apply_filters() Calls 'trackback_url' on the resulting trackback URL @@ -519,7 +522,7 @@ function get_trackback_url() { } /** - * trackback_url() - Displays the current post's trackback URL + * Displays the current post's trackback URL. * * @since 0.71 * @uses get_trackback_url() Gets the trackback url for the current post @@ -533,7 +536,7 @@ function trackback_url($deprecated = true) { } /** - * trackback_rdf() - Generates and displays the RDF for the trackback information of current post + * Generates and displays the RDF for the trackback information of current post. * * @since 0.71 * @@ -557,7 +560,7 @@ function trackback_rdf($deprecated = '') { } /** - * comments_open() - Whether the current post is open for comments + * Whether the current post is open for comments. * * @since 1.5 * @uses $post @@ -574,7 +577,7 @@ function comments_open( $post_id=NULL ) { } /** - * pings_open() - Whether the current post is open for pings + * Whether the current post is open for pings. * * @since 1.5 * @uses $post @@ -591,14 +594,14 @@ function pings_open( $post_id = NULL ) { } /** - * wp_comment_form_unfiltered_html_nonce() - Displays form token for unfiltered comments + * Displays form token for unfiltered comments. * - * Will only display nonce token if the current user has permissions for unfiltered html. - * Won't display the token for other users. + * Will only display nonce token if the current user has permissions for + * unfiltered html. Won't display the token for other users. * - * The function was backported to 2.0.10 and was added to versions 2.1.3 and above. Does not - * exist in versions prior to 2.0.10 in the 2.0 branch and in the 2.1 branch, prior to 2.1.3. - * Technically added in 2.2.0. + * The function was backported to 2.0.10 and was added to versions 2.1.3 and + * above. Does not exist in versions prior to 2.0.10 in the 2.0 branch and in + * the 2.1 branch, prior to 2.1.3. Technically added in 2.2.0. * * @since 2.0.10 Backported to 2.0 branch * @since 2.1.3 @@ -611,10 +614,10 @@ function wp_comment_form_unfiltered_html_nonce() { } /** - * comments_template() - Loads the comment template specified in $file + * Loads the comment template specified in $file. * - * Will not display the comments template if not on single post or page, or - * if the post does not have comments. + * Will not display the comments template if not on single post or page, or if + * the post does not have comments. * * Uses the WordPress database object to query for the comments. The comments * are passed through the 'comments_array' filter hook with the list of comments @@ -669,7 +672,7 @@ function comments_template( $file = '/comments.php' ) { } /** - * comments_popup_script() - Displays the JS popup script to show a comment + * Displays the JS popup script to show a comment. * * If the $file parameter is empty, then the home page is assumed. The defaults * for the window are 400px by 400px. @@ -700,9 +703,10 @@ function comments_popup_script($width=400, $height=400, $file='') { } /** - * comments_popup_link() - Displays the link to the comments popup window for the current post ID. + * Displays the link to the comments popup window for the current post ID. * - * Is not meant to be displayed on single posts and pages. Should be used on the lists of posts + * Is not meant to be displayed on single posts and pages. Should be used on the + * lists of posts * * @since 0.71 * @uses $id diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php index 4141ec3490..b390a3a418 100644 --- a/wp-includes/pluggable.php +++ b/wp-includes/pluggable.php @@ -1,16 +1,16 @@ ' - * when both are set. If just 'wp_mail_from' is set, then just - * the email address will be used with no name. + * Using the two 'wp_mail_from' and 'wp_mail_from_name' hooks allow from + * creating a from address like 'Name ' when both are set. If + * just 'wp_mail_from' is set, then just the email address will be used with no + * name. * - * The default content type is 'text/plain' which does not - * allow using HTML. However, you can set the content type - * of the email by using the 'wp_mail_content_type' filter. + * The default content type is 'text/plain' which does not allow using HTML. + * However, you can set the content type of the email by using the + * 'wp_mail_content_type' filter. * - * The default charset is based on the charset used on the - * blog. The charset can be set using the 'wp_mail_charset' - * filter. + * The default charset is based on the charset used on the blog. The charset can + * be set using the 'wp_mail_charset' filter. * * @since 1.2.1 * @uses apply_filters() Calls 'wp_mail' hook on an array of all of the parameters. @@ -419,7 +416,8 @@ function wp_mail( $to, $subject, $message, $headers = '' ) { endif; /** - * wp_authenticate() - Checks a user's login information and logs them in if it checks out + * Checks a user's login information and logs them in if it checks out. + * * @since 2.5 * * @param string $username User's username @@ -459,9 +457,9 @@ function wp_authenticate($username, $password) { endif; /** - * wp_logout() - Log the current user out - * @since 2.5 + * Log the current user out. * + * @since 2.5 */ if ( !function_exists('wp_logout') ) : function wp_logout() { @@ -472,13 +470,13 @@ endif; if ( !function_exists('wp_validate_auth_cookie') ) : /** - * wp_validate_auth_cookie() - Validates authentication cookie + * Validates authentication cookie. * - * The checks include making sure that the authentication cookie - * is set and pulling in the contents (if $cookie is not used). + * The checks include making sure that the authentication cookie is set and + * pulling in the contents (if $cookie is not used). * - * Makes sure the cookie is not expired. Verifies the hash in - * cookie is what is should be and compares the two. + * Makes sure the cookie is not expired. Verifies the hash in cookie is what is + * should be and compares the two. * * @since 2.5 * @@ -533,7 +531,7 @@ endif; if ( !function_exists('wp_generate_auth_cookie') ) : /** - * wp_generate_auth_cookie() - Generate authentication cookie contents + * Generate authentication cookie contents. * * @since 2.5 * @uses apply_filters() Calls 'auth_cookie' hook on $cookie contents, User ID @@ -558,12 +556,11 @@ endif; if ( !function_exists('wp_set_auth_cookie') ) : /** - * wp_set_auth_cookie() - Sets the authentication cookies based User ID + * Sets the authentication cookies based User ID. * - * The $remember parameter increases the time that the cookie will - * be kept. The default the cookie is kept without remembering is - * two days. When $remember is set, the cookies will be kept for - * 14 days or two weeks. + * The $remember parameter increases the time that the cookie will be kept. The + * default the cookie is kept without remembering is two days. When $remember is + * set, the cookies will be kept for 14 days or two weeks. * * @since 2.5 * @@ -604,7 +601,7 @@ endif; if ( !function_exists('wp_clear_auth_cookie') ) : /** - * wp_clear_auth_cookie() - Deletes all of the cookies associated with authentication + * Removes all of the cookies associated with authentication. * * @since 2.5 */ @@ -626,7 +623,7 @@ endif; if ( !function_exists('is_user_logged_in') ) : /** - * is_user_logged_in() - Checks if the current visitor is a logged in user + * Checks if the current visitor is a logged in user. * * @since 2.0.0 * @@ -644,7 +641,7 @@ endif; if ( !function_exists('auth_redirect') ) : /** - * auth_redirect() - Checks if a user is logged in, if not it redirects them to the login page + * Checks if a user is logged in, if not it redirects them to the login page. * * @since 1.5 */ @@ -687,7 +684,9 @@ endif; if ( !function_exists('check_admin_referer') ) : /** - * check_admin_referer() - Makes sure that a user was referred from another admin page, to avoid security exploits + * Makes sure that a user was referred from another admin page. + * + * To avoid security exploits. * * @since 1.2.0 * @uses do_action() Calls 'check_admin_referer' on $action. @@ -709,7 +708,7 @@ function check_admin_referer($action = -1, $query_arg = '_wpnonce') { if ( !function_exists('check_ajax_referer') ) : /** - * check_ajax_referer() - Verifies the AJAX request to prevent processing requests external of the blog. + * Verifies the AJAX request to prevent processing requests external of the blog. * * @since 2.0.4 * @@ -735,7 +734,7 @@ endif; if ( !function_exists('wp_redirect') ) : /** - * wp_redirect() - Redirects to another page, with a workaround for the IIS Set-Cookie bug + * Redirects to another page, with a workaround for the IIS Set-Cookie bug. * * @link http://support.microsoft.com/kb/q176113/ * @since 1.5.1 @@ -768,7 +767,7 @@ endif; if ( !function_exists('wp_sanitize_redirect') ) : /** - * wp_sanitize_redirect() - Sanitizes a URL for use in a redirect + * Sanitizes a URL for use in a redirect. * * @since 2.3 * @@ -796,14 +795,15 @@ endif; if ( !function_exists('wp_safe_redirect') ) : /** - * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect() + * Performs a safe (local) redirect, using wp_redirect(). * * Checks whether the $location is using an allowed host, if it has an absolute - * path. A plugin can therefore set or remove allowed host(s) to or from the list. + * path. A plugin can therefore set or remove allowed host(s) to or from the + * list. * * If the host is not allowed, then the redirect is to wp-admin on the siteurl - * instead. This prevents malicious redirects which redirect to another host, but - * only used in a few places. + * instead. This prevents malicious redirects which redirect to another host, + * but only used in a few places. * * @since 2.3 * @uses apply_filters() Calls 'allowed_redirect_hosts' on an array containing @@ -834,7 +834,7 @@ endif; if ( ! function_exists('wp_notify_postauthor') ) : /** - * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts + * Notify an author of a comment/trackback/pingback to one of their posts. * * @since 1.0.0 * @@ -913,7 +913,7 @@ endif; if ( !function_exists('wp_notify_moderator') ) : /** - * wp_notify_moderator() - Notifies the moderator of the blog about a new comment that is awaiting approval + * Notifies the moderator of the blog about a new comment that is awaiting approval. * * @since 1.0 * @uses $wpdb @@ -982,7 +982,7 @@ endif; if ( !function_exists('wp_new_user_notification') ) : /** - * wp_new_user_notification() - Notify the blog admin of a new user, normally via email + * Notify the blog admin of a new user, normally via email. * * @since 2.0 * @@ -1015,9 +1015,10 @@ endif; if ( !function_exists('wp_nonce_tick') ) : /** - * wp_nonce_tick() - Get the time-dependent variable for nonce creation + * Get the time-dependent variable for nonce creation. * - * A nonce has a lifespan of two ticks. Nonces in their second tick may be updated, e.g. by autosave. + * A nonce has a lifespan of two ticks. Nonces in their second tick may be + * updated, e.g. by autosave. * * @since 2.5 * @@ -1032,10 +1033,10 @@ endif; if ( !function_exists('wp_verify_nonce') ) : /** - * wp_verify_nonce() - Verify that correct nonce was used with time limit + * Verify that correct nonce was used with time limit. * - * The user is given an amount of time to use the token, so therefore, since - * the UID and $action remain the same, the independent variable is the time. + * The user is given an amount of time to use the token, so therefore, since the + * UID and $action remain the same, the independent variable is the time. * * @since 2.0.4 * @@ -1062,7 +1063,7 @@ endif; if ( !function_exists('wp_create_nonce') ) : /** - * wp_create_nonce() - Creates a random, one time use token + * Creates a random, one time use token. * * @since 2.0.4 * @@ -1081,35 +1082,38 @@ endif; if ( !function_exists('wp_salt') ) : /** - * wp_salt() - Get salt to add to hashes to help prevent attacks + * Get salt to add to hashes to help prevent attacks. * - * You can set the salt by defining two areas. One is in the database and - * the other is in your wp-config.php file. The database location is defined - * in the option named 'secret', but most likely will not need to be changed. + * The secret key is located in two places: the database in case the secret key + * isn't defined in the second place, which is in the wp-config.php file. If you + * are going to set the secret key, then you must do so in the wp-config.php + * file. * - * The second, located in wp-config.php, is a constant named 'SECRET_KEY', but - * is not required. If the constant is not defined then the database constants - * will be used, since they are most likely given to be unique. However, given - * that the salt will be added to the password and can be seen, the constant - * is recommended to be set manually. + * The secret key in the database is randomly generated and will be appended to + * the secret key that is in wp-config.php file in some instances. It is + * important to have the secret key defined or changed in wp-config.php. + * + * If you have installed WordPress 2.5 or later, then you will have the + * SECRET_KEY defined in the wp-config.php already. You will want to change the + * value in it because hackers will know what it is. If you have upgraded to + * WordPress 2.5 or later version from a version before WordPress 2.5, then you + * should add the constant to your wp-config.php file. + * + * Below is an example of how the SECRET_KEY constant is defined with a value. + * You must not copy the below example and paste into your wp-config.php. If you + * need an example, then you can have a + * {@link http://api.wordpress.org/secret-key/1.0/ secret key created} for you. * * * define('SECRET_KEY', 'mAry1HadA15|\/|b17w55w1t3asSn09w'); * * - * Attention: Do not use above example! - * - * Salting passwords helps against tools which has stored hashed values - * of common dictionary strings. The added values makes it harder to crack - * if given salt string is not weak. - * - * Salting only helps if the string is not predictable and should be - * made up of various characters. Think of the salt as a password for - * securing your passwords, but common among all of your passwords. - * Therefore the salt should be as long as possible as as difficult as - * possible, because you will not have to remember it. + * Salting passwords helps against tools which has stored hashed values of + * common dictionary strings. The added values makes it harder to crack if given + * salt string is not weak. * * @since 2.5 + * @link http://api.wordpress.org/secret-key/1.0/ Create a Secret Key for wp-config.php * * @return string Salt value from either 'SECRET_KEY' or 'secret' option */ @@ -1168,7 +1172,7 @@ endif; if ( !function_exists('wp_hash') ) : /** - * wp_hash() - Get hash of given string + * Get hash of given string. * * @since 2.0.4 * @uses wp_salt() Get WordPress salt @@ -1185,11 +1189,10 @@ endif; if ( !function_exists('wp_hash_password') ) : /** - * wp_hash_password() - Create a hash (encrypt) of a plain text password + * Create a hash (encrypt) of a plain text password. * - * For integration with other applications, this function can be - * overwritten to instead use the other package password checking - * algorithm. + * For integration with other applications, this function can be overwritten to + * instead use the other package password checking algorithm. * * @since 2.5 * @global object $wp_hasher PHPass object @@ -1213,17 +1216,15 @@ endif; if ( !function_exists('wp_check_password') ) : /** - * wp_check_password() - Checks the plaintext password against the encrypted Password + * Checks the plaintext password against the encrypted Password. * - * Maintains compatibility between old version and the new cookie - * authentication protocol using PHPass library. The $hash parameter - * is the encrypted password and the function compares the plain text - * password when encypted similarly against the already encrypted - * password to see if they match. + * Maintains compatibility between old version and the new cookie authentication + * protocol using PHPass library. The $hash parameter is the encrypted password + * and the function compares the plain text password when encypted similarly + * against the already encrypted password to see if they match. * - * For integration with other applications, this function can be - * overwritten to instead use the other package password checking - * algorithm. + * For integration with other applications, this function can be overwritten to + * instead use the other package password checking algorithm. * * @since 2.5 * @global object $wp_hasher PHPass object used for checking the password @@ -1265,7 +1266,7 @@ endif; if ( !function_exists('wp_generate_password') ) : /** - * wp_generate_password() - Generates a random password drawn from the defined set of characters + * Generates a random password drawn from the defined set of characters. * * @since 2.5 * @@ -1285,11 +1286,10 @@ endif; if ( !function_exists('wp_set_password') ) : /** - * wp_set_password() - Updates the user's password with a new encrypted one + * Updates the user's password with a new encrypted one. * - * For integration with other applications, this function can be - * overwritten to instead use the other package password checking - * algorithm. + * For integration with other applications, this function can be overwritten to + * instead use the other package password checking algorithm. * * @since 2.5 * @uses $wpdb WordPress database object for queries @@ -1310,9 +1310,7 @@ endif; if ( !function_exists( 'get_avatar' ) ) : /** - * get_avatar() - Get avatar for a user - * - * Retrieve the avatar for a user provided a user ID or email address + * Retrieve the avatar for a user who provided a user ID or email address. * * @since 2.5 * @param int|string|object $id_or_email A user ID, email address, or comment object @@ -1388,7 +1386,7 @@ endif; if ( !function_exists('wp_setcookie') ) : /** - * wp_setcookie() - Sets a cookie for a user who just logged in + * Sets a cookie for a user who just logged in. * * @since 1.5 * @deprecated Use wp_set_auth_cookie() @@ -1410,7 +1408,7 @@ endif; if ( !function_exists('wp_clearcookie') ) : /** - * wp_clearcookie() - Clears the authentication cookie, logging the user out + * Clears the authentication cookie, logging the user out. * * @since 1.5 * @deprecated Use wp_clear_auth_cookie() @@ -1424,10 +1422,10 @@ endif; if ( !function_exists('wp_get_cookie_login') ): /** - * wp_get_cookie_login() - Gets the user cookie login + * Gets the user cookie login. * - * This function is deprecated and should no longer be extended as it won't - * be used anywhere in WordPress. Also, plugins shouldn't use it either. + * This function is deprecated and should no longer be extended as it won't be + * used anywhere in WordPress. Also, plugins shouldn't use it either. * * @since 2.0.4 * @deprecated No alternative @@ -1442,15 +1440,14 @@ endif; if ( !function_exists('wp_login') ) : /** - * wp_login() - Checks a users login information and logs them in if it checks out + * Checks a users login information and logs them in if it checks out. * - * Use the global $error to get the reason why the login failed. - * If the username is blank, no error will be set, so assume - * blank username on that case. + * Use the global $error to get the reason why the login failed. If the username + * is blank, no error will be set, so assume blank username on that case. * - * Plugins extending this function should also provide the global - * $error and set what the error is, so that those checking the - * global for why there was a failure can utilize it later. + * Plugins extending this function should also provide the global $error and set + * what the error is, so that those checking the global for why there was a + * failure can utilize it later. * * @since 1.2.2 * @deprecated Use wp_signon() @@ -1476,23 +1473,30 @@ endif; if ( !function_exists( 'wp_text_diff' ) ) : /** - * wp_text_diff() - compares two strings and outputs a human readable HTML representation of their difference + * Displays a human readable HTML representation of the difference between two strings. * - * Basically a wrapper for man diff(1) + * The Diff is available for getting the changes between versions. The output is + * HTML, so the primary use is for displaying the changes. If the two strings + * are equivalent, then an empty string will be returned. * - * Must accept an optional third parameter, $args @see wp_parse_args() - * (string) title: optional. If present, titles the diff in a manner compatible with the output + * The arguments supported and can be changed are listed below. * - * Must return the empty string if the two compared strings are found to be equivalent according to whatever metric + * 'title' : Default is an empty string. Titles the diff in a manner compatible + * with the output. + * 'title_left' : Default is an empty string. Change the HTML to the left of the + * title. + * 'title_right' : Default is an empty string. Change the HTML to the right of + * the title. * * @since 2.6 + * @see wp_parse_args() Used to change defaults to user defined settings. * @uses Text_Diff * @uses WP_Text_Diff_Renderer_Table * * @param string $left_string "old" (left) version of string * @param string $right_string "new" (right) version of string - * @param string|array $args @see wp_parse_args() - * @return string human readable HTML of string differences. Empty string if strings are equivalent + * @param string|array $args Optional. Change 'title', 'title_left', and 'title_right' defaults. + * @return string Empty string if strings are equivalent or HTML with differences. */ function wp_text_diff( $left_string, $right_string, $args = null ) { $defaults = array( 'title' => '', 'title_left' => '', 'title_right' => '' ); diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index dcc0d34209..59b98047e2 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -20,13 +20,13 @@ $wp_taxonomies['post_tag'] = (object) array('name' => 'post_tag', 'object_type' $wp_taxonomies['link_category'] = (object) array('name' => 'link_category', 'object_type' => 'link', 'hierarchical' => false); /** - * get_object_taxonomies() - Return all of the taxonomy names that are of $object_type + * Return all of the taxonomy names that are of $object_type. * * It appears that this function can be used to find all of the names inside of * $wp_taxonomies global variable. * - * - * Should result in Array('category', 'post_tag') + * Should + * result in Array('category', 'post_tag') * * @package WordPress * @subpackage Taxonomy @@ -58,7 +58,7 @@ function get_object_taxonomies($object) { } /** - * get_taxonomy() - Returns the taxonomy object of $taxonomy. + * Retrieves the taxonomy object of $taxonomy. * * The get_taxonomy function will first check that the parameter string given * is a taxonomy object and if it is, it will return it. @@ -83,7 +83,7 @@ function get_taxonomy( $taxonomy ) { } /** - * is_taxonomy() - Checks that the taxonomy name exists + * Checks that the taxonomy name exists. * * @package WordPress * @subpackage Taxonomy @@ -101,10 +101,10 @@ function is_taxonomy( $taxonomy ) { } /** - * is_taxonomy_hierarchical() - Whether the taxonomy object is hierarchical + * Whether the taxonomy object is hierarchical. * - * Checks to make sure that the taxonomy is an object first. Then Gets the object, and finally - * returns the hierarchical value in the object. + * Checks to make sure that the taxonomy is an object first. Then Gets the + * object, and finally returns the hierarchical value in the object. * * A false return value might also mean that the taxonomy does not exist. * @@ -127,19 +127,29 @@ function is_taxonomy_hierarchical($taxonomy) { } /** - * register_taxonomy() - Create or modify a taxonomy object. Do not use before init. + * Create or modify a taxonomy object. Do not use before init. * - * A simple function for creating or modifying a taxonomy object based on the parameters given. - * The function will accept an array (third optional parameter), along with strings for the - * taxonomy name and another string for the object type. + * A simple function for creating or modifying a taxonomy object based on the + * parameters given. The function will accept an array (third optional + * parameter), along with strings for the taxonomy name and another string for + * the object type. * - * Nothing is returned, so expect error maybe or use is_taxonomy() to check whether taxonomy exists. + * Nothing is returned, so expect error maybe or use is_taxonomy() to check + * whether taxonomy exists. * * Optional $args contents: - * hierarachical - has some defined purpose at other parts of the API and is a boolean value. - * update_count_callback - works much like a hook, in that it will be called when the count is updated. - * rewrite - false to prevent rewrite, or array('slug'=>$slug) to customize permastruct; default will use $taxonomy as slug - * query_var - false to prevent queries, or string to customize query var (?$query_var=$term); default will use $taxonomy as query var + * + * hierarachical - has some defined purpose at other parts of the API and is a + * boolean value. + * + * update_count_callback - works much like a hook, in that it will be called + * when the count is updated. + * + * rewrite - false to prevent rewrite, or array('slug'=>$slug) to customize + * permastruct; default will use $taxonomy as slug. + * + * query_var - false to prevent queries, or string to customize query var + * (?$query_var=$term); default will use $taxonomy as query var. * * @package WordPress * @subpackage Taxonomy @@ -184,18 +194,19 @@ function register_taxonomy( $taxonomy, $object_type, $args = array() ) { // /** - * get_objects_in_term() - Return object_ids of valid taxonomy and term + * Retrieve object_ids of valid taxonomy and term. * - * The strings of $taxonomies must exist before this function will continue. On failure of finding - * a valid taxonomy, it will return an WP_Error class, kind of like Exceptions in PHP 5, except you - * can't catch them. Even so, you can still test for the WP_Error class and get the error message. + * The strings of $taxonomies must exist before this function will continue. On + * failure of finding a valid taxonomy, it will return an WP_Error class, kind + * of like Exceptions in PHP 5, except you can't catch them. Even so, you can + * still test for the WP_Error class and get the error message. * - * The $terms aren't checked the same as $taxonomies, but still need to exist for $object_ids to - * be returned. + * The $terms aren't checked the same as $taxonomies, but still need to exist + * for $object_ids to be returned. * - * It is possible to change the order that object_ids is returned by either using PHP sort family - * functions or using the database by using $args with either ASC or DESC array. The value should - * be in the key named 'order'. + * It is possible to change the order that object_ids is returned by either + * using PHP sort family functions or using the database by using $args with + * either ASC or DESC array. The value should be in the key named 'order'. * * @package WordPress * @subpackage Taxonomy @@ -244,26 +255,29 @@ function get_objects_in_term( $terms, $taxonomies, $args = array() ) { } /** - * get_term() - Get all Term data from database by Term ID. + * Get all Term data from database by Term ID. * - * The usage of the get_term function is to apply filters to a term object. - * It is possible to get a term object from the database before applying the + * The usage of the get_term function is to apply filters to a term object. It + * is possible to get a term object from the database before applying the * filters. * - * $term ID must be part of $taxonomy, to get from the database. Failure, might be - * able to be captured by the hooks. Failure would be the same value as $wpdb returns for the - * get_row method. + * $term ID must be part of $taxonomy, to get from the database. Failure, might + * be able to be captured by the hooks. Failure would be the same value as $wpdb + * returns for the get_row method. * - * There are two hooks, one is specifically for each term, named 'get_term', and the second is - * for the taxonomy name, 'term_$taxonomy'. Both hooks gets the term object, and the taxonomy - * name as parameters. Both hooks are expected to return a Term object. + * There are two hooks, one is specifically for each term, named 'get_term', and + * the second is for the taxonomy name, 'term_$taxonomy'. Both hooks gets the + * term object, and the taxonomy name as parameters. Both hooks are expected to + * return a Term object. * - * 'get_term' hook - Takes two parameters the term Object and the taxonomy name. Must return - * term object. Used in get_term() as a catch-all filter for every $term. + * 'get_term' hook - Takes two parameters the term Object and the taxonomy name. + * Must return term object. Used in get_term() as a catch-all filter for every + * $term. * - * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy name. Must return - * term object. $taxonomy will be the taxonomy name, so for example, if 'category', it would be - * 'get_category' as the filter name. Useful for custom taxonomies or plugging into default taxonomies. + * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy + * name. Must return term object. $taxonomy will be the taxonomy name, so for + * example, if 'category', it would be 'get_category' as the filter name. Useful + * for custom taxonomies or plugging into default taxonomies. * * @package WordPress * @subpackage Taxonomy @@ -316,15 +330,16 @@ function &get_term($term, $taxonomy, $output = OBJECT, $filter = 'raw') { } /** - * get_term_by() - Get all Term data from database by Term field and data. + * Get all Term data from database by Term field and data. * - * Warning: $value is not escaped for 'name' $field. You must do it yourself, if required. + * Warning: $value is not escaped for 'name' $field. You must do it yourself, if + * required. * - * The default $field is 'id', therefore it is possible to also use null for field, but not - * recommended that you do so. + * The default $field is 'id', therefore it is possible to also use null for + * field, but not recommended that you do so. * - * If $value does not exist, the return value will be false. If $taxonomy exists and $field - * and $value combinations exist, the Term will be returned. + * If $value does not exist, the return value will be false. If $taxonomy exists + * and $field and $value combinations exist, the Term will be returned. * * @package WordPress * @subpackage Taxonomy @@ -380,10 +395,10 @@ function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw } /** - * get_term_children() - Merge all term children into a single array. + * Merge all term children into a single array. * - * This recursive function will merge all of the children of $term into - * the same array. Only useful for taxonomies which are hierarchical. + * This recursive function will merge all of the children of $term into the same + * array. Only useful for taxonomies which are hierarchical. * * Will return an empty array if $term does not exist in $taxonomy. * @@ -419,11 +434,11 @@ function get_term_children( $term, $taxonomy ) { } /** - * get_term_field() - Get sanitized Term field + * Get sanitized Term field. * - * Does checks for $term, based on the $taxonomy. The function is for - * contextual reasons and for simplicity of usage. See sanitize_term_field() for - * more information. + * Does checks for $term, based on the $taxonomy. The function is for contextual + * reasons and for simplicity of usage. See sanitize_term_field() for more + * information. * * @package WordPress * @subpackage Taxonomy @@ -453,10 +468,10 @@ function get_term_field( $field, $term, $taxonomy, $context = 'display' ) { } /** - * get_term_to_edit() - Sanitizes Term for editing + * Sanitizes Term for editing. * - * Return value is sanitize_term() and usage is for sanitizing the term - * for editing. Function is for contextual and simplicity. + * Return value is sanitize_term() and usage is for sanitizing the term for + * editing. Function is for contextual and simplicity. * * @package WordPress * @subpackage Taxonomy @@ -481,20 +496,24 @@ function get_term_to_edit( $id, $taxonomy ) { } /** - * get_terms() - Retrieve the terms in taxonomy or list of taxonomies. + * Retrieve the terms in taxonomy or list of taxonomies. * - * You can fully inject any customizations to the query before it is sent, as well as control - * the output with a filter. + * You can fully inject any customizations to the query before it is sent, as + * well as control the output with a filter. * - * The 'get_terms' filter will be called when the cache has the term and will pass the found - * term along with the array of $taxonomies and array of $args. This filter is also called - * before the array of terms is passed and will pass the array of terms, along with the $taxonomies - * and $args. + * The 'get_terms' filter will be called when the cache has the term and will + * pass the found term along with the array of $taxonomies and array of $args. + * This filter is also called before the array of terms is passed and will pass + * the array of terms, along with the $taxonomies and $args. * - * The 'list_terms_exclusions' filter passes the compiled exclusions along with the $args. + * The 'list_terms_exclusions' filter passes the compiled exclusions along with + * the $args. * * The list that $args can contain, which will overwrite the defaults. - * orderby - Default is 'name'. Can be name, count, or nothing (will use term_id). + * + * orderby - Default is 'name'. Can be name, count, or nothing (will use + * term_id). + * * order - Default is ASC. Can use DESC. * hide_empty - Default is true. Will not return empty $terms. * fields - Default is all. @@ -502,19 +521,21 @@ function get_term_to_edit( $id, $taxonomy ) { * hierarchical - Whether to return hierarchical taxonomy. Default is true. * name__like - Default is empty string. * - * The argument 'pad_counts' will count all of the children along with the $terms. + * The argument 'pad_counts' will count all of the children along with the + * $terms. * - * The 'get' argument allows for overwriting 'hide_empty' and 'child_of', which can be done by - * setting the value to 'all', instead of its default empty string value. + * The 'get' argument allows for overwriting 'hide_empty' and 'child_of', which + * can be done by setting the value to 'all', instead of its default empty + * string value. * - * The 'child_of' argument will be used if you use multiple taxonomy or the first $taxonomy - * isn't hierarchical or 'parent' isn't used. The default is 0, which will be translated to - * a false value. If 'child_of' is set, then 'child_of' value will be tested against - * $taxonomy to see if 'child_of' is contained within. Will return an empty array if test - * fails. + * The 'child_of' argument will be used if you use multiple taxonomy or the + * first $taxonomy isn't hierarchical or 'parent' isn't used. The default is 0, + * which will be translated to a false value. If 'child_of' is set, then + * 'child_of' value will be tested against $taxonomy to see if 'child_of' is + * contained within. Will return an empty array if test fails. * - * If 'parent' is set, then it will be used to test against the first taxonomy. Much like - * 'child_of'. Will return an empty array if the test fails. + * If 'parent' is set, then it will be used to test against the first taxonomy. + * Much like 'child_of'. Will return an empty array if the test fails. * * @package WordPress * @subpackage Taxonomy @@ -523,7 +544,6 @@ function get_term_to_edit( $id, $taxonomy ) { * @uses $wpdb * @uses wp_parse_args() Merges the defaults with those defined by $args and allows for strings. * - * * @param string|array Taxonomy name or list of Taxonomy names * @param string|array $args The values of what to search for when returning terms * @return array|WP_Error List of Term Objects and their children. Will return WP_Error, if any of $taxonomies do not exist. @@ -723,7 +743,7 @@ function &get_terms($taxonomies, $args = '') { } /** - * is_term() - Check if Term exists + * Check if Term exists. * * Returns the index of a defined term, or 0 (false) if the term doesn't exist. * @@ -757,11 +777,11 @@ function is_term($term, $taxonomy = '') { } /** - * sanitize_term() - Sanitize Term all fields + * Sanitize Term all fields. * - * Relys on sanitize_term_field() to sanitize the term. The difference - * is that this function will sanitize all fields. The context - * is based on sanitize_term_field(). + * Relys on sanitize_term_field() to sanitize the term. The difference is that + * this function will sanitize all fields. The context is based + * on sanitize_term_field(). * * The $term is expected to be either an array or an object. * @@ -798,15 +818,17 @@ function sanitize_term($term, $taxonomy, $context = 'display') { } /** - * sanitize_term_field() - Cleanse the field value in the term based on the context + * Cleanse the field value in the term based on the context. * - * Passing a term field value through the function should be assumed to have cleansed - * the value for whatever context the term field is going to be used. + * Passing a term field value through the function should be assumed to have + * cleansed the value for whatever context the term field is going to be used. * - * If no context or an unsupported context is given, then default filters will be applied. + * If no context or an unsupported context is given, then default filters will + * be applied. * - * There are enough filters for each context to support a custom filtering without creating - * your own filter function. Simply create a function that hooks into the filter you need. + * There are enough filters for each context to support a custom filtering + * without creating your own filter function. Simply create a function that + * hooks into the filter you need. * * @package WordPress * @subpackage Taxonomy @@ -863,10 +885,10 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) { } /** - * wp_count_terms() - Count how many terms are in Taxonomy + * Count how many terms are in Taxonomy. * - * Default $args is 'ignore_empty' which can be 'ignore_empty=true' or - * array('ignore_empty' => true);. + * Default $args is 'ignore_empty' which can be 'ignore_empty=true' + * or array('ignore_empty' => true);. * * @package WordPress * @subpackage Taxonomy @@ -894,11 +916,11 @@ function wp_count_terms( $taxonomy, $args = array() ) { } /** - * wp_delete_object_term_relationships() - Will unlink the term from the taxonomy + * Will unlink the term from the taxonomy. * - * Will remove the term's relationship to the taxonomy, not the term or taxonomy itself. - * The term and taxonomy will still exist. Will require the term's object ID to perform - * the operation. + * Will remove the term's relationship to the taxonomy, not the term or taxonomy + * itself. The term and taxonomy will still exist. Will require the term's + * object ID to perform the operation. * * @package WordPress * @subpackage Taxonomy @@ -925,10 +947,10 @@ function wp_delete_object_term_relationships( $object_id, $taxonomies ) { } /** - * wp_delete_term() - Removes a term from the database. + * Removes a term from the database. * - * If the term is a parent of other terms, then the children will be updated - * to that term's parent. + * If the term is a parent of other terms, then the children will be updated to + * that term's parent. * * The $args 'default' will only override the terms found, if there is only one * term found. Any other and the found terms are used. @@ -938,9 +960,9 @@ function wp_delete_object_term_relationships( $object_id, $taxonomies ) { * @since 2.3 * * @uses $wpdb - * @uses do_action() Calls both 'delete_term' and 'delete_$taxonomy' action hooks, - * passing term object, term id. 'delete_term' gets an additional parameter with - * the $taxonomy parameter. + * @uses do_action() Calls both 'delete_term' and 'delete_$taxonomy' action + * hooks, passing term object, term id. 'delete_term' gets an additional + * parameter with the $taxonomy parameter. * * @param int $term Term ID * @param string $taxonomy Taxonomy Name @@ -1006,24 +1028,26 @@ function wp_delete_term( $term, $taxonomy, $args = array() ) { } /** - * wp_get_object_terms() - Retrieves the terms associated with the given object(s), in the supplied taxonomies. + * Retrieves the terms associated with the given object(s), in the supplied taxonomies. * - * The following information has to do the $args parameter and for what can be contained in the string - * or array of that parameter, if it exists. + * The following information has to do the $args parameter and for what can be + * contained in the string or array of that parameter, if it exists. * - * The first argument is called, 'orderby' and has the default value of 'name'. The other value that is - * supported is 'count'. + * The first argument is called, 'orderby' and has the default value of 'name'. + * The other value that is supported is 'count'. * - * The second argument is called, 'order' and has the default value of 'ASC'. The only other value that - * will be acceptable is 'DESC'. + * The second argument is called, 'order' and has the default value of 'ASC'. + * The only other value that will be acceptable is 'DESC'. * - * The final argument supported is called, 'fields' and has the default value of 'all'. There are - * multiple other options that can be used instead. Supported values are as follows: 'all', 'ids', - * 'names', and finally 'all_with_object_id'. + * The final argument supported is called, 'fields' and has the default value of + * 'all'. There are multiple other options that can be used instead. Supported + * values are as follows: 'all', 'ids', 'names', and finally + * 'all_with_object_id'. * - * The fields argument also decides what will be returned. If 'all' or 'all_with_object_id' is choosen or - * the default kept intact, then all matching terms objects will be returned. If either 'ids' or 'names' - * is used, then an array of all matching term ids or term names will be returned respectively. + * The fields argument also decides what will be returned. If 'all' or + * 'all_with_object_id' is choosen or the default kept intact, then all matching + * terms objects will be returned. If either 'ids' or 'names' is used, then an + * array of all matching term ids or term names will be returned respectively. * * @package WordPress * @subpackage Taxonomy @@ -1114,34 +1138,40 @@ function wp_get_object_terms($object_ids, $taxonomies, $args = array()) { } /** - * wp_insert_term() - Adds a new term to the database. Optionally marks it as an alias of an existing term. + * Adds a new term to the database. Optionally marks it as an alias of an existing term. * - * Error handling is assigned for the nonexistance of the $taxonomy and $term parameters before inserting. - * If both the term id and taxonomy exist previously, then an array will be returned that contains the term - * id and the contents of what is returned. The keys of the array are 'term_id' and 'term_taxonomy_id' containing - * numeric values. + * Error handling is assigned for the nonexistance of the $taxonomy and $term + * parameters before inserting. If both the term id and taxonomy exist + * previously, then an array will be returned that contains the term id and the + * contents of what is returned. The keys of the array are 'term_id' and + * 'term_taxonomy_id' containing numeric values. * - * It is assumed that the term does not yet exist or the above will apply. The term will be first added to the term - * table and then related to the taxonomy if everything is well. If everything is correct, then several actions - * will be run prior to a filter and then several actions will be run after the filter is run. + * It is assumed that the term does not yet exist or the above will apply. The + * term will be first added to the term table and then related to the taxonomy + * if everything is well. If everything is correct, then several actions will be + * run prior to a filter and then several actions will be run after the filter + * is run. * - * The arguments decide how the term is handled based on the $args parameter. The following - * is a list of the available overrides and the defaults. + * The arguments decide how the term is handled based on the $args parameter. + * The following is a list of the available overrides and the defaults. * - * 'alias_of'. There is no default, but if added, expected is the slug that the term will be an alias of. - * Expected to be a string. + * 'alias_of'. There is no default, but if added, expected is the slug that the + * term will be an alias of. Expected to be a string. * - * 'description'. There is no default. If exists, will be added to the database along with the term. Expected - * to be a string. + * 'description'. There is no default. If exists, will be added to the database + * along with the term. Expected to be a string. * - * 'parent'. Expected to be numeric and default is 0 (zero). Will assign value of 'parent' to the term. + * 'parent'. Expected to be numeric and default is 0 (zero). Will assign value + * of 'parent' to the term. * * 'slug'. Expected to be a string. There is no default. * - * If 'slug' argument exists then the slug will be checked to see if it is not a valid term. If that check - * succeeds (it is not a valid term), then it is added and the term id is given. If it fails, then a check - * is made to whether the taxonomy is hierarchical and the parent argument is not empty. If the second check - * succeeds, the term will be inserted and the term id will be given. + * If 'slug' argument exists then the slug will be checked to see if it is not + * a valid term. If that check succeeds (it is not a valid term), then it is + * added and the term id is given. If it fails, then a check is made to whether + * the taxonomy is hierarchical and the parent argument is not empty. If the + * second check succeeds, the term will be inserted and the term id will be + * given. * * @package WordPress * @subpackage Taxonomy @@ -1235,13 +1265,15 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) { } /** - * wp_set_object_terms() - Create Term and Taxonomy Relationships + * Create Term and Taxonomy Relationships. * - * Relates an object (post, link etc) to a term and taxonomy type. Creates the term and taxonomy - * relationship if it doesn't already exist. Creates a term if it doesn't exist (using the slug). + * Relates an object (post, link etc) to a term and taxonomy type. Creates the + * term and taxonomy relationship if it doesn't already exist. Creates a term if + * it doesn't exist (using the slug). * - * A relationship means that the term is grouped in or belongs to the taxonomy. A term has no - * meaning until it is given context by defining which taxonomy it exists under. + * A relationship means that the term is grouped in or belongs to the taxonomy. + * A term has no meaning until it is given context by defining which taxonomy it + * exists under. * * @package WordPress * @subpackage Taxonomy @@ -1315,17 +1347,17 @@ function wp_set_object_terms($object_id, $terms, $taxonomy, $append = false) { } /** - * wp_unique_term_slug() - Will make slug unique, if it isn't already + * Will make slug unique, if it isn't already. * - * The $slug has to be unique global to every taxonomy, meaning that one taxonomy - * term can't have a matching slug with another taxonomy term. Each slug has to be - * globally unique for every taxonomy. + * The $slug has to be unique global to every taxonomy, meaning that one + * taxonomy term can't have a matching slug with another taxonomy term. Each + * slug has to be globally unique for every taxonomy. * - * The way this works is that if the taxonomy that the term belongs to is heirarchical - * and has a parent, it will append that parent to the $slug. + * The way this works is that if the taxonomy that the term belongs to is + * heirarchical and has a parent, it will append that parent to the $slug. * - * If that still doesn't return an unique slug, then it try to append a number until - * it finds a number that is truely unique. + * If that still doesn't return an unique slug, then it try to append a number + * until it finds a number that is truely unique. * * The only purpose for $term is for appending a parent, if one exists. * @@ -1376,25 +1408,25 @@ function wp_unique_term_slug($slug, $term) { } /** - * wp_update_term() - Update term based on arguments provided + * Update term based on arguments provided. * - * The $args will indiscriminately override all values with the same field name. Care - * must be taken to not override important information need to update or update will - * fail (or perhaps create a new term, neither would be acceptable). + * The $args will indiscriminately override all values with the same field name. + * Care must be taken to not override important information need to update or + * update will fail (or perhaps create a new term, neither would be acceptable). * - * Defaults will set 'alias_of', 'description', 'parent', and 'slug' if not defined - * in $args already. + * Defaults will set 'alias_of', 'description', 'parent', and 'slug' if not + * defined in $args already. * - * 'alias_of' will create a term group, if it doesn't already exist, and update it for - * the $term. + * 'alias_of' will create a term group, if it doesn't already exist, and update + * it for the $term. * - * If the 'slug' argument in $args is missing, then the 'name' in $args will be used. - * It should also be noted that if you set 'slug' and it isn't unique then a WP_Error - * will be passed back. If you don't pass any slug, then a unique one will be created - * for you. + * If the 'slug' argument in $args is missing, then the 'name' in $args will be + * used. It should also be noted that if you set 'slug' and it isn't unique then + * a WP_Error will be passed back. If you don't pass any slug, then a unique one + * will be created for you. * - * For what can be overrode in $args, check the term scheme can contain and stay away - * from the term keys. + * For what can be overrode in $args, check the term scheme can contain and stay + * away from the term keys. * * @package WordPress * @subpackage Taxonomy @@ -1402,8 +1434,8 @@ function wp_unique_term_slug($slug, $term) { * * @uses $wpdb * @uses do_action() Will call both 'edit_term' and 'edit_$taxonomy' twice. - * @uses apply_filters() Will call the 'term_id_filter' filter and pass the term id and - * taxonomy id. + * @uses apply_filters() Will call the 'term_id_filter' filter and pass the term + * id and taxonomy id. * * @param int $term The ID of the term * @param string $taxonomy The context in which to relate the term to the object. @@ -1489,8 +1521,14 @@ function wp_update_term( $term, $taxonomy, $args = array() ) { return array('term_id' => $term_id, 'term_taxonomy_id' => $tt_id); } -// enable or disable term count deferring -// if no value is supplied, the current value of the defer setting is returned +/** + * Enable or disable term counting. + * + * @since 2.6 + * + * @param bool $defer Optional. + * @return bool + */ function wp_defer_term_counting($defer=NULL) { static $_defer = false; @@ -1505,12 +1543,13 @@ function wp_defer_term_counting($defer=NULL) { } /** - * wp_update_term_count() - Updates the amount of terms in taxonomy + * Updates the amount of terms in taxonomy. * - * If there is a taxonomy callback applyed, then it will be called for updating the count. + * If there is a taxonomy callback applyed, then it will be called for updating + * the count. * - * The default action is to count what the amount of terms have the relationship of term ID. - * Once that is done, then update the database. + * The default action is to count what the amount of terms have the relationship + * of term ID. Once that is done, then update the database. * * @package WordPress * @subpackage Taxonomy @@ -1547,6 +1586,15 @@ function wp_update_term_count( $terms, $taxonomy, $do_deferred=false ) { return wp_update_term_count_now( $terms, $taxonomy ); } +/** + * Perform term count update immediately. + * + * @since 2.6 + * + * @param array $terms IDs of Terms to update. + * @param string $taxonomy The context of the term. + * @return bool Always true when complete. + */ function wp_update_term_count_now( $terms, $taxonomy ) { global $wpdb; @@ -1573,11 +1621,13 @@ function wp_update_term_count_now( $terms, $taxonomy ) { // Cache // + /** - * clean_object_term_cache() - Removes the taxonomy relationship to terms from the cache. + * Removes the taxonomy relationship to terms from the cache. * - * Will remove the entire taxonomy relationship containing term $object_id. The term IDs - * have to exist within the taxonomy $object_type for the deletion to take place. + * Will remove the entire taxonomy relationship containing term $object_id. The + * term IDs have to exist within the taxonomy $object_type for the deletion to + * take place. * * @package WordPress * @subpackage Taxonomy @@ -1601,8 +1651,9 @@ function clean_object_term_cache($object_ids, $object_type) { do_action('clean_object_term_cache', $object_ids, $object_type); } + /** - * clean_term_cache() - Will remove all of the term ids from the cache + * Will remove all of the term ids from the cache. * * @package WordPress * @subpackage Taxonomy @@ -1646,8 +1697,9 @@ function clean_term_cache($ids, $taxonomy = '') { do_action('clean_term_cache', $ids, $taxonomy); } + /** - * get_object_term_cache() - Retrieves the taxonomy relationship to the term object id. + * Retrieves the taxonomy relationship to the term object id. * * @package WordPress * @subpackage Taxonomy @@ -1664,19 +1716,19 @@ function &get_object_term_cache($id, $taxonomy) { return $cache; } + /** - * update_object_term_cache() - Updates the cache for Term ID(s) + * Updates the cache for Term ID(s). * * Will only update the cache for terms not already cached. * - * The $object_ids expects that the ids be separated by commas, if it is - * a string. + * The $object_ids expects that the ids be separated by commas, if it is a + * string. * - * It should be noted that update_object_term_cache() is very time extensive. - * It is advised that the function is not called very often or at least not - * for a lot of terms that exist in a lot of taxonomies. The amount of time - * increases for each term and it also increases for each taxonomy the term - * belongs to. + * It should be noted that update_object_term_cache() is very time extensive. It + * is advised that the function is not called very often or at least not for a + * lot of terms that exist in a lot of taxonomies. The amount of time increases + * for each term and it also increases for each taxonomy the term belongs to. * * @package WordPress * @subpackage Taxonomy @@ -1734,8 +1786,9 @@ function update_object_term_cache($object_ids, $object_type) { } } + /** - * update_term_cache() - Updates Terms to Taxonomy in cache. + * Updates Terms to Taxonomy in cache. * * @package WordPress * @subpackage Taxonomy @@ -1758,16 +1811,17 @@ function update_term_cache($terms, $taxonomy = '') { // Private // + /** - * _get_term_hierarchy() - Retrieves children of taxonomy + * Retrieves children of taxonomy. * * @package WordPress * @subpackage Taxonomy * @access private * @since 2.3 * - * @uses update_option() Stores all of the children in "$taxonomy_children" option. - * That is the name of the taxonomy, immediately followed by '_children'. + * @uses update_option() Stores all of the children in "$taxonomy_children" + * option. That is the name of the taxonomy, immediately followed by '_children'. * * @param string $taxonomy Taxonomy Name * @return array Empty if $taxonomy isn't hierarachical or returns children. @@ -1790,11 +1844,13 @@ function _get_term_hierarchy($taxonomy) { return $children; } + /** - * _get_term_children() - Get array of child terms + * Get array of child terms. * - * If $terms is an array of objects, then objects will returned from the function. - * If $terms is an array of IDs, then an array of ids of children will be returned. + * If $terms is an array of objects, then objects will returned from the + * function. If $terms is an array of IDs, then an array of ids of children will + * be returned. * * @package WordPress * @subpackage Taxonomy @@ -1846,11 +1902,12 @@ function &_get_term_children($term_id, $terms, $taxonomy) { return $term_list; } + /** - * _pad_term_counts() - Add count of children to parent count + * Add count of children to parent count. * - * Recalculates term counts by including items from child terms. - * Assumes all relevant children are already in the $terms argument + * Recalculates term counts by including items from child terms. Assumes all + * relevant children are already in the $terms argument. * * @package WordPress * @subpackage Taxonomy @@ -1910,9 +1967,10 @@ function _pad_term_counts(&$terms, $taxonomy) { // /** - * _update_post_term_count() - Will update term count based on posts + * Will update term count based on posts. * - * Private function for the default callback for post_tag and category taxonomies. + * Private function for the default callback for post_tag and category + * taxonomies. * * @package WordPress * @subpackage Taxonomy @@ -1931,8 +1989,11 @@ function _update_post_term_count( $terms ) { } } + /** - * get_term_link() - Generates a permalink for a taxonomy term archive + * Generates a permalink for a taxonomy term archive. + * + * @since 2.6 * * @param object|int|string $term * @param string $taxonomy @@ -1975,6 +2036,24 @@ function get_term_link( $term, $taxonomy ) { return apply_filters('term_link', $termlink, $term, $taxonomy); } +/** + * Display the taxonomies of a post with available options. + * + * This function can be used within the loop to display the taxonomies for a + * post without specifying the Post ID. You can also use it outside the Loop to + * display the taxonomies for a specific post. + * + * The available defaults are: + * 'post' : default is 0. The post ID to get taxonomies of. + * 'before' : default is empty string. Display before taxonomies list. + * 'sep' : default is empty string. Separate every taxonomy with value in this. + * 'after' : default is empty string. Display this after the taxonomies list. + * + * @since 2.6 + * @uses get_the_taxonomies() + * + * @param array $args Override the defaults. + */ function the_taxonomies($args = array()) { $defaults = array( 'post' => 0, @@ -1989,6 +2068,17 @@ function the_taxonomies($args = array()) { echo $before . join($sep, get_the_taxonomies($post)) . $after; } +/** + * Retrieve all taxonomies associated with a post. + * + * This function can be used within the loop. It will also return an array of + * the taxonomies with links to the taxonomy and name. + * + * @since 2.6 + * + * @param int $post Optional. Post ID or will use Global Post ID (in loop). + * @return array + */ function get_the_taxonomies($post = 0) { if ( is_int($post) ) $post =& get_post($post); @@ -2026,10 +2116,19 @@ function get_the_taxonomies($post = 0) { return $taxonomies; } +/** + * Retrieve all taxonomies of a post with just the names. + * + * @since 2.6 + * @uses get_object_taxonomies() + * + * @param int $post Optional. Post ID + * @return array + */ function get_post_taxonomies($post = 0) { $post =& get_post($post); return get_object_taxonomies($post); } -?> +?> \ No newline at end of file diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php index de53738d5d..8eaa5391c3 100644 --- a/wp-includes/wp-db.php +++ b/wp-includes/wp-db.php @@ -1,57 +1,308 @@ __construct($dbuser, $dbpassword, $dbname, $dbhost); } + /** + * Connects to the database server and selects a database + * + * PHP5 style constructor for compatibility with PHP5. Does + * the actual setting up of the class properties and connection + * to the database. + * + * @since 2.0.8 + * + * @param string $dbuser MySQL database user + * @param string $dbpassword MySQL database password + * @param string $dbname MySQL database name + * @param string $dbhost MySQL database host + */ function __construct($dbuser, $dbpassword, $dbname, $dbhost) { register_shutdown_function(array(&$this, "__destruct")); @@ -97,10 +348,28 @@ class wpdb { $this->select($dbname); } + /** + * PHP5 style destructor and will run when database object is destroyed. + * + * @since 2.0.8 + * + * @return bool Always true + */ function __destruct() { return true; } + /** + * Sets the table prefix for the WordPress tables. + * + * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to + * override the WordPress users and usersmeta tables. + * + * @since 2.5.0 + * + * @param string $prefix Alphanumeric name for the new prefix. + * @return string Old prefix + */ function set_prefix($prefix) { if ( preg_match('|[^a-z0-9_]|i', $prefix) ) @@ -122,8 +391,15 @@ class wpdb { } /** - * Selects a database using the current class's $this->dbh - * @param string $db name + * Selects a database using the current database connection. + * + * The database name will be changed based on the current database + * connection. On failure, the execution will bail and display an DB error. + * + * @since 0.71 + * + * @param string $db MySQL database name + * @return null Always null. */ function select($db) { if (!@mysql_select_db($db, $this->dbh)) { @@ -144,6 +420,8 @@ class wpdb { /** * Escapes content for insertion into the database, for security * + * @since 0.71 + * * @param string $string * @return string query safe string */ @@ -160,6 +438,9 @@ class wpdb { /** * Escapes content by reference for insertion into the database, for security + * + * @since 2.3.0 + * * @param string $s */ function escape_by_ref(&$s) { @@ -167,10 +448,17 @@ class wpdb { } /** - * Prepares a SQL query for safe use, using sprintf() syntax + * Prepares a SQL query for safe use, using sprintf() syntax. + * + * @link http://php.net/sprintf See for syntax to use for query string. + * @since 2.3.0 + * + * @param null|string $args If string, first parameter must be query statement + * @param mixed $args,... If additional parameters, they will be set inserted into the query. + * @return null|string Sanitized query string */ - function prepare($args=NULL) { - if ( NULL === $args ) + function prepare($args=null) { + if ( is_null( $args ) ) return; $args = func_get_args(); $query = array_shift($args); @@ -181,15 +469,20 @@ class wpdb { return @vsprintf($query, $args); } - // ================================================================== - // Print SQL/DB error. - + /** + * Print SQL/DB error. + * + * @since 0.71 + * @global array $EZSQL_ERROR Stores error information of query and error string + * + * @param string $str The error to display + * @return bool False if the showing of errors is disabled. + */ function print_error($str = '') { global $EZSQL_ERROR; if (!$str) $str = mysql_error($this->dbh); - $EZSQL_ERROR[] = - array ('query' => $this->last_query, 'error_str' => $str); + $EZSQL_ERROR[] = array ('query' => $this->last_query, 'error_str' => $str); if ( $this->suppress_errors ) return false; @@ -223,39 +516,71 @@ class wpdb { "; } - // ================================================================== - // Turn error handling on or off.. - + /** + * Enables showing of database errors. + * + * This function should be used only to enable showing of errors. + * wpdb::hide_errors() should be used instead for hiding of errors. However, + * this function can be used to enable and disable showing of database + * errors. + * + * @since 0.71 + * + * @param bool $show Whether to show or hide errors + * @return bool Old value for showing errors. + */ function show_errors( $show = true ) { $errors = $this->show_errors; $this->show_errors = $show; return $errors; } + /** + * Disables showing of database errors. + * + * @since 0.71 + * + * @return bool Whether showing of errors was active or not + */ function hide_errors() { $show = $this->show_errors; $this->show_errors = false; return $show; } + /** + * Whether to suppress database errors. + * + * @param unknown_type $suppress + * @return unknown + */ function suppress_errors( $suppress = true ) { $errors = $this->suppress_errors; $this->suppress_errors = $suppress; return $errors; } - // ================================================================== - // Kill cached query results - + /** + * Kill cached query results. + * + * @since 0.71 + */ function flush() { $this->last_result = array(); $this->col_info = null; $this->last_query = null; } - // ================================================================== - // Basic Query - see docs for more detail - + /** + * Perform a MySQL database query, using current database connection. + * + * More information can be found on the codex page. + * + * @since 0.71 + * + * @param string $query + * @return unknown + */ function query($query) { if ( ! $this->ready ) return false; @@ -324,10 +649,13 @@ class wpdb { } /** - * Insert an array of data into a table + * Insert an array of data into a table. + * + * @since 2.5.0 + * * @param string $table WARNING: not sanitized! - * @param array $data should not already be SQL-escaped - * @return mixed results of $this->query() + * @param array $data Should not already be SQL-escaped + * @return mixed Results of $this->query() */ function insert($table, $data) { $data = add_magic_quotes($data); @@ -336,11 +664,14 @@ class wpdb { } /** - * Update a row in the table with an array of data + * Update a row in the table with an array of data. + * + * @since 2.5.0 + * * @param string $table WARNING: not sanitized! - * @param array $data should not already be SQL-escaped - * @param array $where a named array of WHERE column => value relationships. Multiple member pairs will be joined with ANDs. WARNING: the column names are not currently sanitized! - * @return mixed results of $this->query() + * @param array $data Should not already be SQL-escaped + * @param array $where A named array of WHERE column => value relationships. Multiple member pairs will be joined with ANDs. WARNING: the column names are not currently sanitized! + * @return mixed Results of $this->query() */ function update($table, $data, $where){ $data = add_magic_quotes($data); @@ -357,11 +688,21 @@ class wpdb { } /** - * Get one variable from the database - * @param string $query (can be null as well, for caching, see codex) - * @param int $x = 0 row num to return - * @param int $y = 0 col num to return - * @return mixed results + * Retrieve one variable from the database. + * + * This combines the functionality of wpdb::get_row() and wpdb::get_col(), + * so both the column and row can be picked. + * + * It is possible to use this function without executing more queries. If + * you already made a query, you can set the $query to 'null' value and just + * retrieve either the column and row of the last query result. + * + * @since 0.71 + * + * @param string $query Can be null as well, for caching + * @param int $x Column num to return + * @param int $y Row num to return + * @return mixed Database query results */ function get_var($query=null, $x = 0, $y = 0) { $this->func_call = "\$db->get_var(\"$query\",$x,$y)"; @@ -378,11 +719,14 @@ class wpdb { } /** - * Get one row from the database - * @param string $query + * Retrieve one row from the database. + * + * @since 0.71 + * + * @param string $query SQL query * @param string $output ARRAY_A | ARRAY_N | OBJECT - * @param int $y row num to return - * @return mixed results + * @param int $y Row num to return + * @return mixed Database query results */ function get_row($query = null, $output = OBJECT, $y = 0) { $this->func_call = "\$db->get_row(\"$query\",$output,$y)"; @@ -406,10 +750,13 @@ class wpdb { } /** - * Gets one column from the database - * @param string $query (can be null as well, for caching, see codex) - * @param int $x col num to return - * @return array results + * Retrieve one column from the database. + * + * @since 0.71 + * + * @param string $query Can be null as well, for caching + * @param int $x Col num to return. Starts from 0. + * @return array Column results */ function get_col($query = null , $x = 0) { if ( $query ) @@ -424,10 +771,13 @@ class wpdb { } /** - * Return an entire result set from the database - * @param string $query (can also be null to pull from the cache) + * Retrieve an entire result set from the database. + * + * @since 0.71 + * + * @param string|null $query Can also be null to pull from the cache * @param string $output ARRAY_A | ARRAY_N | OBJECT_K | OBJECT - * @return mixed results + * @return mixed Database query results */ function get_results($query = null, $output = OBJECT) { $this->func_call = "\$db->get_results(\"$query\", $output)"; @@ -469,10 +819,13 @@ class wpdb { } /** - * Grabs column metadata from the last query + * Retrieve column metadata from the last query. + * + * @since 0.71 + * * @param string $info_type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill * @param int $col_offset 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type - * @return mixed results + * @return mixed Column Results */ function get_col_info($info_type = 'name', $col_offset = -1) { if ( $this->col_info ) { @@ -490,7 +843,11 @@ class wpdb { } /** - * Starts the timer, for debugging purposes + * Starts the timer, for debugging purposes. + * + * @since 1.5.0 + * + * @return bool Always returns true */ function timer_start() { $mtime = microtime(); @@ -500,8 +857,11 @@ class wpdb { } /** - * Stops the debugging timer - * @return int total time spent on the query, in milliseconds + * Stops the debugging timer. + * + * @since 1.5.0 + * + * @return int Total time spent on the query, in milliseconds */ function timer_stop() { $mtime = microtime(); @@ -513,9 +873,13 @@ class wpdb { /** * Wraps fatal errors in a nice header and footer and dies. + * + * @since 1.5.0 + * * @param string $message + * @return unknown */ - function bail($message) { // Just wraps errors in a nice header and footer + function bail($message) { if ( !$this->show_errors ) { if ( class_exists('WP_Error') ) $this->error = new WP_Error('500', $message); @@ -527,8 +891,12 @@ class wpdb { } /** - * Checks wether of not the database version is high enough to support the features WordPress uses - * @global $wp_version + * Whether or not MySQL database is minimal required version. + * + * @since 2.5.0 + * @uses $wp_version + * + * @return WP_Error */ function check_database_version() { @@ -540,8 +908,13 @@ class wpdb { } /** - * This function is called when WordPress is generating the table schema to determine wether or not the current database - * supports or needs the collation statements. + * Whether of not the database version supports collation. + * + * Called when WordPress is generating the table scheme. + * + * @since 2.5.0 + * + * @return bool True if collation is supported, false if version does not */ function supports_collation() { @@ -549,8 +922,14 @@ class wpdb { } /** - * Get the name of the function that called wpdb. - * @return string the name of the calling function + * Retrieve the name of the function that called wpdb. + * + * Requires PHP 4.3 and searches up the list of functions until it reaches + * the one that would most logically had called this method. + * + * @since 2.5.0 + * + * @return string The name of the calling function */ function get_caller() { // requires PHP 4.3+ @@ -578,6 +957,12 @@ class wpdb { } -if ( ! isset($wpdb) ) +if ( ! isset($wpdb) ) { + /** + * WordPress Database Object, if it isn't set already in wp-content/wpdb.php + * @global object $wpdb Creates a new wpdb object based on wp-config.php Constants for the database + * @since 0.71 + */ $wpdb = new wpdb(DB_USER, DB_PASSWORD, DB_NAME, DB_HOST); +} ?>