Changeset 8164

Show
Ignore:
Timestamp:
06/22/08 20:23:23 (2 months ago)
Author:
ryan
Message:

phpdoc updates from jacobsantos. see #7038

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/wp-includes/comment-template.php

    r7999 r8164  
    1010 
    1111/** 
    12  * get_comment_author() - Retrieve the author of the current comment 
    13  * 
    14  * If the comment has an empty comment_author field, then 'Anonymous' person 
    15  * is assumed. 
     12 * Retrieve the author of the current comment. 
     13 * 
     14 * If the comment has an empty comment_author field, then 'Anonymous' person is 
     15 * assumed. 
    1616 * 
    1717 * @since 1.5 
    …… 
    3030 
    3131/** 
    32  * comment_author() - Displays the author of the current comment 
     32 * Displays the author of the current comment. 
    3333 * 
    3434 * @since 0.71 
    …… 
    4141 
    4242/** 
    43  * get_comment_author_email() - Retrieve the email of the author of the current comment 
     43 * Retrieve the email of the author of the current comment. 
    4444 * 
    4545 * @since 1.5 
    …… 
    5555 
    5656/** 
    57  * comment_author_email() - Display the email of the author of the current global $comment 
    58  * 
    59  * Care should be taken to protect the email address and assure that email harvesters 
    60  * do not capture your commentors' email address. Most assume that their email address will 
    61  * not appear in raw form on the blog. Doing so will enable anyone, including those that 
    62  * people don't want to get the email address and use it for their own means good and bad. 
     57 * Display the email of the author of the current global $comment. 
     58 * 
     59 * Care should be taken to protect the email address and assure that email 
     60 * harvesters do not capture your commentors' email address. Most assume that 
     61 * their email address will not appear in raw form on the blog. Doing so will 
     62 * enable anyone, including those that people don't want to get the email 
     63 * address and use it for their own means good and bad. 
    6364 * 
    6465 * @since 0.71 
    …… 
    7071 
    7172/** 
    72  * comment_author_email_link() - Display the html email link to the author of the current comment 
    73  * 
    74  * Care should be taken to protect the email address and assure that email harvesters 
    75  * do not capture your commentors' email address. Most assume that their email address will 
    76  * not appear in raw form on the blog. Doing so will enable anyone, including those that 
    77  * people don't want to get the email address and use it for their own means good and bad. 
     73 * Display the html email link to the author of the current comment. 
     74 * 
     75 * Care should be taken to protect the email address and assure that email 
     76 * harvesters do not capture your commentors' email address. Most assume that 
     77 * their email address will not appear in raw form on the blog. Doing so will 
     78 * enable anyone, including those that people don't want to get the email 
     79 * address and use it for their own means good and bad. 
    7880 * 
    7981 * @since 0.71 
    …… 
    9799 
    98100/** 
    99  * get_comment_author_link() - Retrieve the html link to the url of the author of the current comment 
     101 * Retrieve the html link to the url of the author of the current comment. 
    100102 * 
    101103 * @since 1.5 
    …… 
    117119 
    118120/** 
    119  * comment_author_link() - Display the html link to the url of the author of the current comment 
     121 * Display the html link to the url of the author of the current comment. 
    120122 * 
    121123 * @since 0.71 
    …… 
    127129 
    128130/** 
    129  * get_comment_author_IP() - Retrieve the IP address of the author of the current comment 
     131 * Retrieve the IP address of the author of the current comment. 
    130132 * 
    131133 * @since 1.5 
    …… 
    141143 
    142144/** 
    143  * comment_author_IP() - Displays the IP address of the author of the current comment 
     145 * Display the IP address of the author of the current comment. 
    144146 * 
    145147 * @since 0.71 
    …… 
    151153 
    152154/** 
    153  * get_comment_author_url() - Returns the url of the author of the current comment 
     155 * Retrieve the url of the author of the current comment. 
    154156 * 
    155157 * @since 1.5 
    …… 
    164166 
    165167/** 
    166  * comment_author_url() - Display the url of the author of the current comment 
     168 * Display the url of the author of the current comment. 
    167169 * 
    168170 * @since 0.71 
    …… 
    175177 
    176178/** 
    177  * get_comment_author_url_link() - Retrieves the HTML link of the url of the author of the current comment 
    178  * 
    179  * $linktext parameter is only used if the URL does not exist for the comment author. If the URL does 
    180  * exist then the URL will be used and the $linktext will be ignored. 
    181  * 
    182  * Encapsulate the HTML link between the $before and $after. So it will appear in the order of $before, 
    183  * link, and finally $after. 
     179 * Retrieves the HTML link of the url of the author of the current comment. 
     180 * 
     181 * $linktext parameter is only used if the URL does not exist for the comment 
     182 * author. If the URL does exist then the URL will be used and the $linktext 
     183 * will be ignored. 
     184 * 
     185 * Encapsulate the HTML link between the $before and $after. So it will appear 
     186 * in the order of $before, link, and finally $after. 
    184187 * 
    185188 * @since 1.5 
    …… 
    203206 
    204207/** 
    205  * comment_author_url_link() - Displays the HTML link of the url of the author of the current comment 
     208 * Displays the HTML link of the url of the author of the current comment. 
    206209 * 
    207210 * @since 0.71 
    …… 
    217220 
    218221/** 
    219  * get_comment_date() - Retrieve the comment date of the current comment 
     222 * Retrieve the comment date of the current comment. 
    220223 * 
    221224 * @since 1.5 
    …… 
    236239 
    237240/** 
    238  * comment_date() - Display the comment date of the current comment 
     241 * Display the comment date of the current comment. 
    239242 * 
    240243 * @since 0.71 
    …… 
    247250 
    248251/** 
    249  * get_comment_excerpt() - Retrieve the excerpt of the current comment 
     252 * Retrieve the excerpt of the current comment. 
    250253 * 
    251254 * Will cut each word and only output the first 20 words with '...' at the end. 
    …… 
    279282 
    280283/** 
    281  * comment_excerpt() - Returns the excerpt of the current comment 
     284 * Display the excerpt of the current comment. 
    282285 * 
    283286 * @since 1.2 
    …… 
    289292 
    290293/** 
    291  * get_comment_ID() - Retrieve the comment id of the current comment 
     294 * Retrieve the comment id of the current comment. 
    292295 * 
    293296 * @since 1.5 
    …… 
    303306 
    304307/** 
    305  * comment_ID() - Displays the comment id of the current comment 
     308 * Displays the comment id of the current comment. 
    306309 * 
    307310 * @since 0.71 
    …… 
    313316 
    314317/** 
    315  * get_comment_link() - Retrieve the link to the current comment 
     318 * Retrieve the link to the current comment. 
    316319 * 
    317320 * @since 1.5 
    …… 
    326329 
    327330/** 
    328  * get_comments_link() - Retrieves the link to the current post comments 
     331 * Retrieves the link to the current post comments. 
    329332 * 
    330333 * @since 1.5 
    …… 
    337340 
    338341/** 
    339  * comments_link() - Displays the link to the current post comments 
     342 * Displays the link to the current post comments. 
    340343 * 
    341344 * @since 0.71 
    …… 
    349352 
    350353/** 
    351  * get_comments_number() - Retrieve the amount of comments a post has 
     354 * Retrieve the amount of comments a post has. 
    352355 * 
    353356 * @since 1.5 
    …… 
    374377 
    375378/** 
    376  * comments_number() - Display the language string for the number of comments the current post has 
     379 * Display the language string for the number of comments the current post has. 
    377380 * 
    378381 * @since 0.71 
    …… 
    400403 
    401404/** 
    402  * get_comment_text() - Retrieve the text of the current comment 
     405 * Retrieve the text of the current comment. 
    403406 * 
    404407 * @since 1.5 
    …… 
    413416 
    414417/** 
    415  * comment_text() - Displays the text of the current comment 
     418 * Displays the text of the current comment. 
    416419 * 
    417420 * @since 0.71 
    …… 
    424427 
    425428/** 
    426  * get_comment_time() - Retrieve the comment time of the current comment 
     429 * Retrieve the comment time of the current comment. 
    427430 * 
    428431 * @since 1.5 
    …… 
    445448 
    446449/** 
    447  * comment_time() - Display the comment time of the current comment 
     450 * Display the comment time of the current comment. 
    448451 * 
    449452 * @since 0.71 
    …… 
    456459 
    457460/** 
    458  * get_comment_type() - Retrieve the comment type of the current comment 
     461 * Retrieve the comment type of the current comment. 
    459462 * 
    460463 * @since 1.5 
    …… 
    474477 
    475478/** 
    476  * comment_type() - Display the comment type of the current comment 
     479 * Display the comment type of the current comment. 
    477480 * 
    478481 * @since 0.71 
    …… 
    497500 
    498501/** 
    499  * get_trackback_url() - Retrieve The current post's trackback URL 
    500  * 
    501  * There is a check to see if permalink's have been enabled and if so, will retrieve 
    502  * the pretty path. If permalinks weren't enabled, the ID of the current post is used 
    503  * and appended to the correct page to go to. 
     502 * Retrieve The current post's trackback URL. 
     503 * 
     504 * There is a check to see if permalink's have been enabled and if so, will 
     505 * retrieve the pretty path. If permalinks weren't enabled, the ID of the 
     506 * current post is used and appended to the correct page to go to. 
    504507 * 
    505508 * @since 1.5 
    …… 
    520523 
    521524/** 
    522  * trackback_url() - Displays the current post's trackback URL 
     525 * Displays the current post's trackback URL. 
    523526 * 
    524527 * @since 0.71 
    …… 
    534537 
    535538/** 
    536  * trackback_rdf() - Generates and displays the RDF for the trackback information of current post 
     539 * Generates and displays the RDF for the trackback information of current post. 
    537540 * 
    538541 * @since 0.71 
    …… 
    558561 
    559562/** 
    560  * comments_open() - Whether the current post is open for comments 
     563 * Whether the current post is open for comments. 
    561564 * 
    562565 * @since 1.5 
    …… 
    575578 
    576579/** 
    577  * pings_open() - Whether the current post is open for pings 
     580 * Whether the current post is open for pings. 
    578581 * 
    579582 * @since 1.5 
    …… 
    592595 
    593596/** 
    594  * wp_comment_form_unfiltered_html_nonce() - Displays form token for unfiltered comments 
    595  * 
    596  * Will only display nonce token if the current user has permissions for unfiltered html. 
    597  * Won't display the token for other users. 
    598  * 
    599  * The function was backported to 2.0.10 and was added to versions 2.1.3 and above. Does not 
    600  * exist in versions prior to 2.0.10 in the 2.0 branch and in the 2.1 branch, prior to 2.1.3. 
    601  * Technically added in 2.2.0. 
     597 * Displays form token for unfiltered comments. 
     598 * 
     599 * Will only display nonce token if the current user has permissions for 
     600 * unfiltered html. Won't display the token for other users. 
     601 * 
     602 * The function was backported to 2.0.10 and was added to versions 2.1.3 and 
     603 * above. Does not exist in versions prior to 2.0.10 in the 2.0 branch and in 
     604 * the 2.1 branch, prior to 2.1.3. Technically added in 2.2.0. 
    602605 * 
    603606 * @since 2.0.10 Backported to 2.0 branch 
    …… 
    612615 
    613616/** 
    614  * comments_template() - Loads the comment template specified in $file 
    615  * 
    616  * Will not display the comments template if not on single post or page, or 
    617  * if the post does not have comments. 
     617 * Loads the comment template specified in $file. 
     618 * 
     619 * Will not display the comments template if not on single post or page, or if 
     620 * the post does not have comments. 
    618621 * 
    619622 * Uses the WordPress database object to query for the comments. The comments 
    …… 
    670673 
    671674/** 
    672  * comments_popup_script() - Displays the JS popup script to show a comment 
     675 * Displays the JS popup script to show a comment. 
    673676 * 
    674677 * If the $file parameter is empty, then the home page is assumed. The defaults 
    …… 
    701704 
    702705/** 
    703  * comments_popup_link() - Displays the link to the comments popup window for the current post ID. 
    704  * 
    705  * Is not meant to be displayed on single posts and pages. Should be used on the lists of posts 
     706 * Displays the link to the comments popup window for the current post ID. 
     707 * 
     708 * Is not meant to be displayed on single posts and pages. Should be used on the 
     709 * lists of posts 
    706710 * 
    707711 * @since 0.71 

  • trunk/wp-includes/pluggable.php

    r8098 r8164  
    11<?php 
    22/** 
    3  * These functions can be replaced via plugins. They are loaded after 
    4  * plugins are loaded. 
     3 * These functions can be replaced via plugins. If plugins do not redefine these 
     4 * functions, then these will be used instead. 
    55 * 
    66 * @package WordPress 
    …… 
    99if ( !function_exists('set_current_user') ) : 
    1010/** 
    11  * set_current_user() - Populates global user information for any user 
    12  * 
    13  * Set $id to null and specify a name if you do not know a user's ID 
     11 * Changes the current user by ID or name. 
     12 * 
     13 * Set $id to null and specify a name if you do not know a user's ID. 
    1414 * 
    1515 * @since 2.0.1 
    …… 
    2727if ( !function_exists('wp_set_current_user') ) : 
    2828/** 
    29  * wp_set_current_user() - Changes the current user by ID or name 
    30  * 
    31  * Set $id to null and specify a name if you do not know a user's ID 
    32  * 
    33  * Some WordPress functionality is based on the current user and 
    34  * not based on the signed in user. Therefore, it opens the ability 
    35  * to edit and perform actions on users who aren't signed in. 
     29 * Changes the current user by ID or name. 
     30 * 
     31 * Set $id to null and specify a name if you do not know a user's ID. 
     32 * 
     33 * Some WordPress functionality is based on the current user and not based on 
     34 * the signed in user. Therefore, it opens the ability to edit and perform 
     35 * actions on users who aren't signed in. 
    3636 * 
    3737 * @since 2.0.4 
    …… 
    6161if ( !function_exists('wp_get_current_user') ) : 
    6262/** 
    63  * wp_get_current_user() - Retrieve the current user object 
     63 * Retrieve the current user object. 
    6464 * 
    6565 * @since 2.0.4 
    …… 
    7878if ( !function_exists('get_currentuserinfo') ) : 
    7979/** 
    80  * get_currentuserinfo() - Populate global variables with information about the currently logged in user 
    81  * 
    82  * Will set the current user, if the current user is not set. The current 
    83  * user will be set to the logged in person. If no user is logged in, then 
    84  * it will set the current user to 0, which is invalid and won't have any 
    85  * permissions. 
     80 * Populate global variables with information about the currently logged in user. 
     81 * 
     82 * Will set the current user, if the current user is not set. The current user 
     83 * will be set to the logged in person. If no user is logged in, then it will 
     84 * set the current user to 0, which is invalid and won't have any permissions. 
    8685 * 
    8786 * @since 0.71 
    …… 
    113112if ( !function_exists('get_userdata') ) : 
    114113/** 
    115  * get_userdata() - Retrieve user info by user ID 
     114 * Retrieve user info by user ID. 
    116115 * 
    117116 * @since 0.71 
    …… 
    143142if ( !function_exists('update_user_cache') ) : 
    144143/** 
    145  * update_user_cache() - Updates a users cache when overridden by a plugin 
     144 * Updates a users cache when overridden by a plugin. 
    146145 * 
    147146 * Core function does nothing. 
    …… 
    158157if ( !function_exists('get_userdatabylogin') ) : 
    159158/** 
    160  * get_userdatabylogin() - Retrieve user info by login name 
     159 * Retrieve user info by login name. 
    161160 * 
    162161 * @since 0.71 
    …… 
    192191if ( !function_exists('get_user_by_email') ) : 
    193192/** 
    194  * get_user_by_email() - Retrieve user info by email 
     193 * Retrieve user info by email. 
    195194 * 
    196195 * @since 2.5 
    …… 
    222221if ( !function_exists( 'wp_mail' ) ) : 
    223222/** 
    224  * wp_mail() - Function to send mail, similar to PHP's mail 
    225  * 
    226  * A true return value does not automatically mean that the 
    227  * user received the email successfully. It just only means 
    228  * that the method used was able to process the request 
    229  * without any errors. 
    230  * 
    231  * Using the two 'wp_mail_from' and 'wp_mail_from_name' hooks 
    232  * allow from creating a from address like 'Name <email@address.com>' 
    233  * when both are set. If just 'wp_mail_from' is set, then just 
    234  * the email address will be used with no name. 
    235  * 
    236  * The default content type is 'text/plain' which does not 
    237  * allow using HTML. However, you can set the content type 
    238  * of the email by using the 'wp_mail_content_type' filter. 
    239  * 
    240  * The default charset is based on the charset used on the 
    241  * blog. The charset can be set using the 'wp_mail_charset' 
    242  * filter. 
     223 * Send mail, similar to PHP's mail 
     224 * 
     225 * A true return value does not automatically mean that the user received the 
     226 * email successfully. It just only means that the method used was able to 
     227 * process the request without any errors. 
     228 * 
     229 * Using the two 'wp_mail_from' and 'wp_mail_from_name' hooks allow from 
     230 * creating a from address like 'Name <email@address.com>' when both are set. If 
     231 * just 'wp_mail_from' is set, then just the email address will be used with no 
     232 * name. 
     233 * 
     234 * The default content type is 'text/plain' which does not allow using HTML. 
     235 * However, you can set the content type of the email by using the 
     236 * 'wp_mail_content_type' filter. 
     237 * 
     238 * The default charset is based on the charset used on the blog. The charset can 
     239 * be set using the 'wp_mail_charset' filter. 
    243240 * 
    244241 * @since 1.2.1 
    …… 
    420417 
    421418/** 
    422  * wp_authenticate() - Checks a user's login information and logs them in if it checks out 
     419 * Checks a user's login information and logs them in if it checks out. 
     420 * 
    423421 * @since 2.5 
    424422 * 
    …… 
    460458 
    461459/** 
    462  * wp_logout() - Log the current user out 
     460 * Log the current user out. 
     461 * 
    463462 * @since 2.5 
    464  * 
    465463 */ 
    466464if ( !function_exists('wp_logout') ) : 
    …… 
    473471if ( !function_exists('wp_validate_auth_cookie') ) : 
    474472/** 
    475  * wp_validate_auth_cookie() - Validates authentication cookie 
    476  * 
    477  * The checks include making sure that the authentication cookie 
    478  * is set and pulling in the contents (if $cookie is not used). 
    479  * 
    480  * Makes sure the cookie is not expired. Verifies the hash in 
    481  * cookie is what is should be and compares the two. 
     473 * Validates authentication cookie. 
     474 * 
     475 * The checks include making sure that the authentication cookie is set and 
     476 * pulling in the contents (if $cookie is not used). 
     477 * 
     478 * Makes sure the cookie is not expired. Verifies the hash in cookie is what is 
     479 * should be and compares the two. 
    482480 * 
    483481 * @since 2.5 
    …… 
    534532if ( !function_exists('wp_generate_auth_cookie') ) : 
    535533/** 
    536  * wp_generate_auth_cookie() - Generate authentication cookie contents 
     534 * Generate authentication cookie contents. 
    537535 * 
    538536 * @since 2.5 
    …… 
    559557if ( !function_exists('wp_set_auth_cookie') ) : 
    560558/** 
    561  * wp_set_auth_cookie() - Sets the authentication cookies based User ID 
    562  * 
    563  * The $remember parameter increases the time that the cookie will 
    564  * be kept. The default the cookie is kept without remembering is 
    565  * two days. When $remember is set, the cookies will be kept for 
    566  * 14 days or two weeks. 
     559 * Sets the authentication cookies based User ID. 
     560 * 
     561 * The $remember parameter increases the time that the cookie will be kept. The 
     562 * default the cookie is kept without remembering is two days. When $remember is 
     563 * set, the cookies will be kept for 14 days or two weeks. 
    567564 * 
    568565 * @since 2.5 
    …… 
    605602if ( !function_exists('wp_clear_auth_cookie') ) : 
    606603/** 
    607  * wp_clear_auth_cookie() - Deletes all of the cookies associated with authentication 
     604 * Removes all of the cookies associated with authentication. 
    608605 * 
    609606 * @since 2.5 
    …… 
    627624if ( !function_exists('is_user_logged_in') ) : 
    628625/** 
    629  * is_user_logged_in() - Checks if the current visitor is a logged in user 
     626 * Checks if the current visitor is a logged in user. 
    630627 * 
    631628 * @since 2.0.0 
    …… 
    645642if ( !function_exists('auth_redirect') ) : 
    646643/** 
    647  * auth_redirect() - Checks if a user is logged in, if not it redirects them to the login page 
     644 * Checks if a user is logged in, if not it redirects them to the login page. 
    648645 * 
    649646 * @since 1.5 
    …… 
    688685if ( !function_exists('check_admin_referer') ) : 
    689686/** 
    690  * check_admin_referer() - Makes sure that a user was referred from another admin page, to avoid security exploits 
     687 * Makes sure that a user was referred from another admin page. 
     688 * 
     689 * To avoid security exploits. 
    691690 * 
    692691 * @since 1.2.0 
    …… 
    710709if ( !function_exists('check_ajax_referer') ) : 
    711710/** 
    712  * check_ajax_referer() - Verifies the AJAX request to prevent processing requests external of the blog. 
     711 * Verifies the AJAX request to prevent processing requests external of the blog. 
    713712 * 
    714713 * @since 2.0.4 
    …… 
    736735if ( !function_exists('wp_redirect') ) : 
    737736/** 
    738  * wp_redirect() - Redirects to another page, with a workaround for the IIS Set-Cookie bug 
     737 * Redirects to another page, with a workaround for the IIS Set-Cookie bug. 
    739738 * 
    740739 * @link http://support.microsoft.com/kb/q176113/ 
    …… 
    769768if ( !function_exists('wp_sanitize_redirect') ) : 
    770769/** 
    771  * wp_sanitize_redirect() - Sanitizes a URL for use in a redirect 
     770 * Sanitizes a URL for use in a redirect. 
    772771 * 
    773772 * @since 2.3 
    …… 
    797796if ( !function_exists('wp_safe_redirect') ) : 
    798797/** 
    799  * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect() 
     798 * Performs a safe (local) redirect, using wp_redirect(). 
    800799 * 
    801800 * Checks whether the $location is using an allowed host, if it has an absolute 
    802  * path. A plugin can therefore set or remove allowed host(s) to or from the list. 
     801 * path. A plugin can therefore set or remove allowed host(s) to or from the 
     802 * list. 
    803803 * 
    804804 * If the host is not allowed, then the redirect is to wp-admin on the siteurl 
    805  * instead. This prevents malicious redirects which redirect to another host, but 
    806  * only used in a few places. 
     805 * instead. This prevents malicious redirects which redirect to another host, 
     806 * but only used in a few places. 
    807807 * 
    808808 * @since 2.3 
    …… 
    835835if ( ! function_exists('wp_notify_postauthor') ) : 
    836836/** 
    837  * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts 
     837 * Notify an author of a comment/trackback/pingback to one of their posts. 
    838838 * 
    839839 * @since 1.0.0 
    …… 
    914914if ( !function_exists('wp_notify_moderator') ) : 
    915915/** 
    916  * wp_notify_moderator() - Notifies the moderator of the blog about a new comment that is awaiting approval 
     916 * Notifies the moderator of the blog about a new comment that is awaiting approval. 
    917917 * 
    918918 * @since 1.0 
    …… 
    983983if ( !function_exists('wp_new_user_notification') ) : 
    984984/** 
    985  * wp_new_user_notification() - Notify the blog admin of a new user, normally via email 
     985 * Notify the blog admin of a new user, normally via email. 
    986986 * 
    987987 * @since 2.0 
    …… 
    10161016if ( !function_exists('wp_nonce_tick') ) : 
    10171017/** 
    1018  * wp_nonce_tick() - Get the time-dependent variable for nonce creation 
    1019  * 
    1020  * A nonce has a lifespan of two ticks. Nonces in their second tick may be updated, e.g. by autosave. 
     1018 * Get the time-dependent variable for nonce creation. 
     1019 * 
     1020 * A nonce has a lifespan of two ticks. Nonces in their second tick may be 
     1021 * updated, e.g. by autosave. 
    10211022 * 
    10221023 * @since 2.5 
    …… 
    10331034if ( !function_exists('wp_verify_nonce') ) : 
    10341035/** 
    1035  * wp_verify_nonce() - Verify that correct nonce was used with time limit 
    1036  * 
    1037  * The user is given an amount of time to use the token, so therefore, since 
    1038  * the UID and $action remain the same, the independent variable is the time. 
     1036 * Verify that correct nonce was used with time limit. 
     1037 * 
     1038 * The user is given an amount of time to use the token, so therefore, since the 
     1039 * UID and $action remain the same, the independent variable is the time. 
    10391040 * 
    10401041 * @since 2.0.4 
    …… 
    10631064if ( !function_exists('wp_create_nonce') ) : 
    10641065/** 
    1065  * wp_create_nonce() - Creates a random, one time use token 
     1066 * Creates a random, one time use token. 
    10661067 * 
    10671068 * @since 2.0.4 
    …… 
    10821083if ( !function_exists('wp_salt') ) : 
    10831084/** 
    1084  * wp_salt() - Get salt to add to hashes to help prevent attacks 
    1085  * 
    1086  * You can set the salt by defining two areas. One is in the database and 
    1087  * the other is in your wp-config.php file. The database location is defined 
    1088  * in the option named 'secret', but most likely will not need to be changed. 
    1089  * 
    1090  * The second, located in wp-config.php, is a constant named 'SECRET_KEY', but 
    1091  * is not required. If the constant is not defined then the database constants 
    1092  * will be used, since they are most likely given to be unique. However, given 
    1093  * that the salt will be added to the password and can be seen, the constant 
    1094  * is recommended to be set manually. 
     1085 * Get salt to add to hashes to help prevent attacks. 
     1086 * 
     1087 * The secret key is located in two places: the database in case the secret key 
     1088 * isn't defined in the second place, which is in the wp-config.php file. If you 
     1089 * are going to set the secret key, then you must do so in the wp-config.php 
     1090 * file. 
     1091 * 
     1092 * The secret key in the database is randomly generated and will be appended to 
     1093 * the secret key that is in wp-config.php file in some instances. It is 
     1094 * important to have the secret key defined or changed in wp-config.php. 
     1095 * 
     1096 * If you have installed WordPress 2.5 or later, then you will have the 
     1097 * SECRET_KEY defined in the wp-config.php already. You will want to change the 
     1098 * value in it because hackers will know what it is. If you have upgraded to 
     1099 * WordPress 2.5 or later version from a version before WordPress 2.5, then you 
     1100 * should add the constant to your wp-config.php file. 
     1101 * 
     1102 * Below is an example of how the SECRET_KEY constant is defined with a value. 
     1103 * You must not copy the below example and paste into your wp-config.php. If you 
     1104 * need an example, then you can have a 
     1105 * {@link http://api.wordpress.org/secret-key/1.0/ secret key created} for you. 
    10951106 * 
    10961107 * <code> 
    …… 
    10981109 * </code> 
    10991110 * 
    1100  * Attention: Do not use above example! 
    1101  * 
    1102  * Salting passwords helps against tools which has stored hashed values 
    1103  * of common dictionary strings. The added values makes it harder to crack 
    1104  * if given salt string is not weak. 
    1105  * 
    1106  * Salting only helps if the string is not predictable and should be 
    1107  * made up of various characters. Think of the salt as a password for 
    1108  * securing your passwords, but common among all of your passwords. 
    1109  * Therefore the salt should be as long as possible as as difficult as 
    1110  * possible, because you will not have to remember it. 
     1111 * Salting passwords helps against tools which has stored hashed values of 
     1112 * common dictionary strings. The added values makes it harder to crack if given 
     1113 * salt string is not weak. 
    11111114 * 
    11121115 * @since 2.5 
     1116 * @link http://api.wordpress.org/secret-key/1.0/ Create a Secret Key for wp-config.php 
    11131117 * 
    11141118 * @return string Salt value from either 'SECRET_KEY' or 'secret' option 
    …… 
    11691173if ( !function_exists('wp_hash') ) : 
    11701174/** 
    1171  * wp_hash() - Get hash of given string 
     1175 * Get hash of given string. 
    11721176 * 
    11731177 * @since 2.0.4 
    …… 
    11861190if ( !function_exists('wp_hash_password') ) : 
    11871191/** 
    1188  * wp_hash_password() - Create a hash (encrypt) of a plain text password 
    1189  * 
    1190  * For integration with other applications, this function can be 
    1191  * overwritten to instead use the other package password checking 
    1192  * algorithm. 
     1192 * Create a hash (encrypt) of a plain text password. 
     1193 * 
     1194 * For integration with other applications, this function can be overwritten to 
     1195 * instead use the other package password checking algorithm. 
    11931196 * 
    11941197 * @since 2.5 
    …… 
    12141217if ( !function_exists('wp_check_password') ) : 
    12151218/** 
    1216  * wp_check_password() - Checks the plaintext password against the encrypted Password 
    1217  * 
    1218  * Maintains compatibility between old version and the new cookie 
    1219  * authentication protocol using PHPass library. The $hash parameter 
    1220  * is the encrypted password and the function compares the plain text 
    1221  * password when encypted similarly against the already encrypted 
    1222  * password to see if they match. 
    1223  * 
    1224  * For integration with other applications, this function can be 
    1225  * overwritten to instead use the other package password checking 
    1226  * algorithm. 
     1219 * Checks the plaintext password against the encrypted Password. 
     1220 * 
     1221 * Maintains compatibility between old version and the new cookie authentication 
     1222 * protocol using PHPass library. The $hash parameter is the encrypted password 
     1223 * and the function compares the plain text password when encypted similarly 
     1224 * against the already encrypted password to see if they match. 
     1225 * 
     1226 * For integration with other applications, this function can be overwritten to 
     1227 * instead use the other package password checking algorithm. 
    12271228 * 
    12281229 * @since 2.5 
    …… 
    12661267if ( !function_exists('wp_generate_password') ) : 
    12671268/** 
    1268  * wp_generate_password() - Generates a random password drawn from the defined set of characters 
     1269 * Generates a random password drawn from the defined set of characters. 
    12691270 * 
    12701271 * @since 2.5 
    …… 
    12861287if ( !function_exists('wp_set_password') ) : 
    12871288/** 
    1288  * wp_set_password() - Updates the user's password with a new encrypted one 
    1289  * 
    1290  * For integration with other applications, this function can be 
    1291  * overwritten to instead use the other package password checking 
    1292  * algorithm. 
     1289 * Updates the user's password with a new encrypted one. 
     1290 * 
     1291 * For integration with other applications, this function can be overwritten to 
     1292 * instead use the other package password checking algorithm. 
    12931293 * 
    12941294 * @since 2.5 
    …… 
    13111311if ( !function_exists( 'get_avatar' ) ) : 
    13121312/** 
    1313  * get_avatar() - Get avatar for a user 
    1314  * 
    1315  * Retrieve the avatar for a user provided a user ID or email address 
     1313 * Retrieve the avatar for a user who provided a user ID or email address. 
    13161314 * 
    13171315 * @since 2.5 
    …… 
    13891387if ( !function_exists('wp_setcookie') ) : 
    13901388/** 
    1391  * wp_setcookie() - Sets a cookie for a user who just logged in 
     1389 * Sets a cookie for a user who just logged in. 
    13921390 * 
    13931391 * @since 1.5 
    …… 
    14111409if ( !function_exists('wp_clearcookie') ) : 
    14121410/** 
    1413  * wp_clearcookie() - Clears the authentication cookie, logging the user out 
     1411 * Clears the authentication cookie, logging the user out. 
    14141412 * 
    14151413 * @since 1.5 
    …… 
    14251423if ( !function_exists('wp_get_cookie_login') ): 
    14261424/** 
    1427  * wp_get_cookie_login() - Gets the user cookie login 
    1428  * 
    1429  * This function is deprecated and should no longer be extended as it won't 
    1430  * be used anywhere in WordPress. Also, plugins shouldn't use it either. 
     1425 * Gets the user cookie login. 
     1426 * 
     1427 * This function is deprecated and should no longer be extended as it won't be 
     1428 * used anywhere in WordPress. Also, plugins shouldn't use it either. 
    14311429 * 
    14321430 * @since 2.0.4 
    …… 
    14431441if ( !function_exists('wp_login') ) : 
    14441442/** 
    1445  * wp_login() - Checks a users login information and logs them in if it checks out 
    1446  * 
    1447  * Use the global $error to get the reason why the login failed. 
    1448  * If the username is blank, no error will be set, so assume 
    1449  * blank username on that case. 
    1450  * 
    1451  * Plugins extending this function should also provide the global 
    1452  * $error and set what the error is, so that those checking the 
    1453  * global for why there was a failure can utilize it later. 
     1443 * Checks a users login information and logs them in if it checks out. 
     1444 * 
     1445 * Use the global $error to get the reason why the login failed. If the username 
     1446 * is blank, no error will be set, so assume blank username on that case. 
     1447 * 
     1448 * Plugins extending this function should also provide the global $error and set 
     1449 * what the error is, so that those checking the global for why there was a 
     1450 * failure can utilize it later. 
    14541451 * 
    14551452 * @since 1.2.2 
    …… 
    14771474if ( !function_exists( 'wp_text_diff' ) ) : 
    14781475/** 
    1479  * wp_text_diff() - compares two strings and outputs a human readable HTML representation of their difference 
    1480  * 
    1481  * Basically a wrapper for man diff(1) 
    1482  * 
    1483  * Must accept an optional third parameter, $args @see wp_parse_args() 
    1484  *    (string) title: optional.  If present, titles the diff in a manner compatible with the output 
    1485  * 
    1486  * Must return the empty string if the two compared strings are found to be equivalent according to whatever metric 
     1476 * Displays a human readable HTML representation of the difference between two strings. 
     1477 * 
     1478 * The Diff is available for getting the changes between versions. The output is 
     1479 * HTML, so the primary use is for displaying the changes. If the two strings 
     1480 * are equivalent, then an empty string will be returned. 
     1481 * 
     1482 * The arguments supported and can be changed are listed below. 
     1483 * 
     1484 * 'title' : Default is an empty string. Titles the diff in a manner compatible 
     1485 *      with the output. 
     1486 * 'title_left' : Default is an empty string. Change the HTML to the left of the 
     1487 *      title. 
     1488 * 'title_right' : Default is an empty string. Change the HTML to the right of 
     1489 *      the title. 
    14871490 * 
    14881491 * @since 2.6 
     1492 * @see wp_parse_args() Used to change defaults to user defined settings. 
    14891493 * @uses Text_Diff 
    14901494 * @uses WP_Text_Diff_Renderer_Table 
    …… 
    14921496 * @param string $left_string "old" (left) version of string 
    14931497 * @param string $right_string "new" (right) version of string 
    1494  * @param string|array $args @see wp_parse_args() 
    1495  * @return string human readable HTML of string differences.  Empty string if strings are equivalent 
     1498 * @param string|array $args Optional. Change 'title', 'title_left', and 'title_right' defaults. 
     1499 * @return string Empty string if strings are equivalent or HTML with differences. 
    14961500 */ 
    14971501function wp_text_diff( $left_string, $right_string, $args = null ) { 

  • trunk/wp-includes/taxonomy.php

    r7952 r8164  
    2121 
    2222/** 
    23  * get_object_taxonomies() - Return all of the taxonomy names that are of $object_type 
     23 * Return all of the taxonomy names that are of $object_type. 
    2424 * 
    2525 * It appears that this function can be used to find all of the names inside of 
    2626 * $wp_taxonomies global variable. 
    2727 * 
    28  * <code><?php $taxonomies = get_object_taxonomies('post'); ?></code> 
    29  * Should result in <code>Array('category', 'post_tag')</code> 
     28 * <code><?php $taxonomies = get_object_taxonomies('post'); ?></code> Should 
     29 * result in <code>Array('category', 'post_tag')</code> 
    3030 * 
    3131 * @package WordPress 
    …… 
    5959 
    6060/** 
    61  * get_taxonomy() - Returns the taxonomy object of $taxonomy. 
     61 * Retrieves the taxonomy object of $taxonomy. 
    6262 * 
    6363 * The get_taxonomy function will first check that the parameter string given 
    …… 
    8484 
    8585/** 
    86  * is_taxonomy() - Checks that the taxonomy name exists 
     86 * Checks that the taxonomy name exists. 
    8787 * 
    8888 * @package WordPress 
    …… 
    102102 
    103103/** 
    104  * is_taxonomy_hierarchical() - Whether the taxonomy object is hierarchical 
    105  * 
    106  * Checks to make sure that the taxonomy is an object first. Then Gets the object, and finally 
    107  * returns the hierarchical value in the object. 
     104 * Whether the taxonomy object is hierarchical. 
     105 * 
     106 * Checks to make sure that the taxonomy is an object first. Then Gets the 
     107 * object, and finally returns the hierarchical value in the object. 
    108108 * 
    109109 * A false return value might also mean that the taxonomy does not exist. 
    …… 
    128128 
    129129/** 
    130  * register_taxonomy() - Create or modify a taxonomy object. Do not use before init. 
    131  * 
    132  * A simple function for creating or modifying a taxonomy object based on the parameters given. 
    133  * The function will accept an array (third optional parameter), along with strings for the 
    134  * taxonomy name and another string for the object type. 
    135  * 
    136  * Nothing is returned, so expect error maybe or use is_taxonomy() to check whether taxonomy exists. 
     130 * Create or modify a taxonomy object. Do not use before init. 
     131 * 
     132 * A simple function for creating or modifying a taxonomy object based on the 
     133 * parameters given. The function will accept an array (third optional 
     134 * parameter), along with strings for the taxonomy name and another string for 
     135 * the object type. 
     136 * 
     137 * Nothing is returned, so expect error maybe or use is_taxonomy() to check 
     138 * whether taxonomy exists. 
    137139 * 
    138140 * Optional $args contents: 
    139  * hierarachical - has some defined purpose at other parts of the API and is a boolean value. 
    140  * update_count_callback - works much like a hook, in that it will be called when the count is updated. 
    141  * rewrite - false to prevent rewrite, or array('slug'=>$slug) to customize permastruct; default will use $taxonomy as slug 
    142  * query_var - false to prevent queries, or string to customize query var (?$query_var=$term); default will use $taxonomy as query var 
     141 * 
     142 * hierarachical - has some defined purpose at other parts of the API and is a 
     143 * boolean value. 
     144 * 
     145 * update_count_callback - works much like a hook, in that it will be called 
     146 * when the count is updated. 
     147 * 
     148 * rewrite - false to prevent rewrite, or array('slug'=>$slug) to customize 
     149 * permastruct; default will use $taxonomy as slug. 
     150 * 
     151 * query_var - false to prevent queries, or string to customize query var 
     152 * (?$query_var=$term); default will use $taxonomy as query var. 
    143153 * 
    144154 * @package WordPress 
    …… 
    185195 
    186196/** 
    187  * get_objects_in_term() - Return object_ids of valid taxonomy and term 
    188  * 
    189  * The strings of $taxonomies must exist before this function will continue. On failure of finding 
    190  * a valid taxonomy, it will return an WP_Error class, kind of like Exceptions in PHP 5, except you 
    191  * can't catch them. Even so, you can still test for the WP_Error class and get the error message. 
    192  * 
    193  * The $terms aren't checked the same as $taxonomies, but still need to exist for $object_ids to 
    194  * be returned. 
    195  * 
    196  * It is possible to change the order that object_ids is returned by either using PHP sort family 
    197  * functions or using the database by using $args with either ASC or DESC array. The value should 
    198  * be in the key named 'order'. 
     197 * Retrieve object_ids of valid taxonomy and term. 
     198 * 
     199 * The strings of $taxonomies must exist before this function will continue. On 
     200 * failure of finding a valid taxonomy, it will return an WP_Error class, kind 
     201 * of like Exceptions in PHP 5, except you can't catch them. Even so, you can 
     202 * still test for the WP_Error class and get the error message. 
     203 * 
     204 * The $terms aren't checked the same as $taxonomies, but still need to exist 
     205 * for $object_ids to be returned. 
     206 * 
     207 * It is possible to change the order that object_ids is returned by either 
     208 * using PHP sort family functions or using the database by using $args with 
     209 * either ASC or DESC array. The value should be in the key named 'order'. 
    199210 * 
    200211 * @package WordPress 
    …… 
    245256 
    246257/** 
    247  * get_term() - Get all Term data from database by Term ID. 
    248  * 
    249  * The usage of the get_term function is to apply filters to a term object. 
    250  * It is possible to get a term object from the database before applying the 
     258 * Get all Term data from database by Term ID. 
     259 * 
     260 * The usage of the get_term function is to apply filters to a term object. It 
     261 * is possible to get a term object from the database before applying the 
    251262 * filters. 
    252263 * 
    253  * $term ID must be part of $taxonomy, to get from the database. Failure, might be 
    254  * able to be captured by the hooks. Failure would be the same value as $wpdb returns for the 
    255  * get_row method. 
    256  * 
    257  * There are two hooks, one is specifically for each term, named 'get_term', and the second is 
    258  * for the taxonomy name, 'term_$taxonomy'. Both hooks gets the term object, and the taxonomy 
    259  * name as parameters. Both hooks are expected to return a Term object. 
    260  * 
    261  * 'get_term' hook - Takes two parameters the term Object and the taxonomy name. Must return 
    262  * term object. Used in get_term() as a catch-all filter for every $term. 
    263  * 
    264  * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy name. Must return 
    265  * term object. $taxonomy will be the taxonomy name, so for example, if 'category', it would be 
    266  * 'get_category' as the filter name. Useful for custom taxonomies or plugging into default taxonomies. 
     264 * $term ID must be part of $taxonomy, to get from the database. Failure, might 
     265 * be able to be captured by the hooks. Failure would be the same value as $wpdb 
     266 * returns for the get_row method. 
     267 * 
     268 * There are two hooks, one is specifically for each term, named 'get_term', and 
     269 * the second is for the taxonomy name, 'term_$taxonomy'. Both hooks gets the 
     270 * term object, and the taxonomy name as parameters. Both hooks are expected to 
     271 * return a Term object. 
     272 * 
     273 * 'get_term' hook - Takes two parameters the term Object and the taxonomy name. 
     274 * Must return term object. Used in get_term() as a catch-all filter for every 
     275 * $term. 
     276 * 
     277 * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy 
     278 * name. Must return term object. $taxonomy will be the taxonomy name, so for 
     279 * example, if 'category', it would be 'get_category' as the filter name. Useful 
     280 * for custom taxonomies or plugging into default taxonomies. 
    267281 * 
    268282 * @package WordPress 
    …… 
    317331 
    318332/** 
    319