Ticket #7538: post.phpdoc.r8662.diff

File post.phpdoc.r8662.diff, 55.5 KB (added by jacobsantos, 4 years ago)

Corrections for post.php based off of r8662

  • post.php

     
    22/** 
    33 * Post functions and post utility function. 
    44 * 
    5  * Warning: The inline documentation for the functions contained 
    6  * in this file might be inaccurate, so the documentation is not 
    7  * authoritative at the moment. 
    8  * 
    95 * @package WordPress 
    106 * @subpackage Post 
    11  * @since 1.5 
     7 * @since 1.5.0 
    128 */ 
    139 
    1410/** 
    … …  
    2218 * prevent looking up the meta name and provide a mechanism for sending the 
    2319 * attached filename through a filter. 
    2420 * 
    25  * @package WordPress 
    26  * @subpackage Post 
    27  * @since 2.0 
    28  * @uses apply_filters() Calls 'get_attached_file' on file path and attachment ID 
     21 * @since 2.0.0 
     22 * @uses apply_filters() Calls 'get_attached_file' on file path and attachment ID. 
    2923 * 
    3024 * @param int $attachment_id Attachment ID 
    3125 * @param bool $unfiltered Whether to apply filters or not 
    … …  
    4438 * Used to update the file path of the attachment, which uses post meta name 
    4539 * '_wp_attached_file' to store the path of the attachment. 
    4640 * 
    47  * @package WordPress 
    48  * @subpackage Post 
    49  * @since 2.1 
    50  * @uses apply_filters() Calls 'update_attached_file' on file path and attachment ID 
     41 * @since 2.1.0 
     42 * @uses apply_filters() Calls 'update_attached_file' on file path and attachment ID. 
    5143 * 
    5244 * @param int $attachment_id Attachment ID 
    5345 * @param string $file File path for the attachment 
    … …  
    7971 * example of what is possible. 
    8072 * 
    8173 * The arguments listed as defaults are for this function and also of the 
    82  * get_posts() function. The arguments are combined with the get_children 
    83  * defaults and are then passed to the get_posts() function, which accepts 
    84  * additional arguments. You can replace the defaults in this function, listed 
    85  * below and the additional arguments listed in the get_posts() function. 
     74 * {@link get_posts()} function. The arguments are combined with the 
     75 * get_children defaults and are then passed to the {@link get_posts()} 
     76 * function, which accepts additional arguments. You can replace the defaults in 
     77 * this function, listed below and the additional arguments listed in the 
     78 * {@link get_posts()} function. 
    8679 * 
    8780 * The 'post_parent' is the most important argument and important attention 
    8881 * needs to be paid to the $args parameter. If you pass either an object or an 
    … …  
    10396 * @see get_posts() Has additional arguments that can be replaced. 
    10497 * @internal Claims made in the long description might be inaccurate. 
    10598 * 
    106  * @package WordPress 
    107  * @subpackage Post 
    108  * @since 2.0 
     99 * @since 2.0.0 
    109100 * 
    110101 * @param mixed $args Optional. User defined arguments for replacing the defaults. 
    111102 * @param string $output Optional. Constant for return type, either OBJECT (default), ARRAY_A, ARRAY_N. 
    … …  
    156147} 
    157148 
    158149/** 
    159  * get_extended() - Get extended entry info (<!--more-->) 
     150 * Get extended entry info (<!--more-->). 
    160151 * 
    161  * {@internal Missing Long Description}} 
     152 * There should not be any space after the second dash and before the word 
     153 * 'more'. There can be text or space(s) after the word 'more', but won't be 
     154 * referenced. 
    162155 * 
    163  * @package WordPress 
    164  * @subpackage Post 
     156 * The returned array has 'main' and 'extended' keys. Main has the text before 
     157 * the <code><!--more--></code>. The 'extended' key has the content after the 
     158 * <code><!--more--></code> comment. 
     159 * 
    165160 * @since 1.0.0 
    166161 * 
    167  * @param string $post {@internal Missing Description}} 
    168  * @return array {@internal Missing Description}} 
     162 * @param string $post Post content. 
     163 * @return array Post before ('main') and after ('extended'). 
    169164 */ 
    170165function get_extended($post) { 
    171166        //Match the new style more links 
    … …  
    184179} 
    185180 
    186181/** 
    187  * get_post() - Retrieves post data given a post ID or post object. 
     182 * Retrieves post data given a post ID or post object. 
    188183 * 
    189  * {@internal Missing Long Description}} 
     184 * See {@link sanitize_post()} for optional $filter values. Also, the parameter 
     185 * $post, must be given as a variable, since it is passed by reference. 
    190186 * 
    191  * @package WordPress 
    192  * @subpackage Post 
    193187 * @since 1.5.1 
    194188 * @uses $wpdb 
    195189 * @link http://codex.wordpress.org/Function_Reference/get_post 
    196190 * 
    197  * @param int|object &$post post ID or post object 
    198  * @param string $output {@internal Missing Description}} 
    199  * @param string $filter {@internal Missing Description}} 
    200  * @return mixed {@internal Missing Description}} 
     191 * @param int|object $post Post ID or post object. 
     192 * @param string $output Optional, default is Object. Either OBJECT, ARRAY_A, or ARRAY_N. 
     193 * @param string $filter Optional, default is raw.  
     194 * @return mixed Post data 
    201195 */ 
    202196function &get_post(&$post, $output = OBJECT, $filter = 'raw') { 
    203197        global $wpdb; 
    … …  
    241235/** 
    242236 * Retrieve ancestors of a post. 
    243237 * 
    244  * @package WordPress 
    245  * @subpackage Post 
    246  * @since 2.5 
     238 * @since 2.5.0 
    247239 * 
    248240 * @param int|object $post Post ID or post object 
    249241 * @return array Ancestor IDs or empty array if none are found. 
    … …  
    266258 * The context values are based off of the taxonomy filter functions and 
    267259 * supported values are found within those functions. 
    268260 * 
    269  * @package WordPress 
    270  * @subpackage Post 
    271  * @since 2.3 
     261 * @since 2.3.0 
    272262 * @uses sanitize_post_field() See for possible $context values. 
    273263 * 
    274264 * @param string $field Post field name 
    … …  
    298288 * This function can be used with any post type, but it makes more sense with 
    299289 * attachments. 
    300290 * 
    301  * @package WordPress 
    302  * @subpackage Post 
    303  * @since 2.0 
     291 * @since 2.0.0 
    304292 * 
    305293 * @param int $ID Optional. Post ID. 
    306294 * @return bool|string False on failure or returns the mime type 
    … …  
    320308 * If the post ID is of an attachment, then the parent post status will be given 
    321309 * instead. 
    322310 * 
    323  * @package WordPress 
    324  * @subpackage Post 
    325  * @since 2.0 
     311 * @since 2.0.0 
    326312 * 
    327313 * @param int $ID Post ID 
    328314 * @return string|bool Post status or false on failure. 
    … …  
    346332 * Posts have a limited set of valid status values, this provides the 
    347333 * post_status values and descriptions. 
    348334 * 
    349  * @package WordPress 
    350  * @subpackage Post 
    351  * @since 2.5 
     335 * @since 2.5.0 
    352336 * 
    353337 * @return array List of post statuses. 
    354338 */ 
    … …  
    369353 * Pages have a limited set of valid status values, this provides the 
    370354 * post_status values and descriptions. 
    371355 * 
    372  * @package WordPress 
    373  * @subpackage Page 
    374  * @since 2.5 
     356 * @since 2.5.0 
    375357 * 
    376358 * @return array List of page statuses. 
    377359 */ 
    … …  
    386368} 
    387369 
    388370/** 
    389  * get_post_type() - Returns post type 
     371 * Retrieve the post type of the current post or of a given post. 
    390372 * 
    391  * {@internal Missing Long Description}} 
     373 * @since 2.1.0 
    392374 * 
    393  * @package WordPress 
    394  * @subpackage Post 
    395  * @since 2.1 
    396  * 
    397375 * @uses $wpdb 
    398  * @uses $posts {@internal Missing Description}} 
     376 * @uses $posts The Loop post global 
    399377 * 
    400  * @param mixed $post post object or post ID 
    401  * @return mixed post type or false 
     378 * @param mixed $post Optional. Post object or post ID. 
     379 * @return bool|string post type or false on failure. 
    402380 */ 
    403381function get_post_type($post = false) { 
    404382        global $posts; 
    … …  
    415393} 
    416394 
    417395/** 
    418  * set_post_type() - Set post type 
     396 * Updates the post type for the post ID. 
    419397 * 
    420  * {@internal Missing Long Description}} 
     398 * The page or post cache will be cleaned for the post ID. 
    421399 * 
    422  * @package WordPress 
    423  * @subpackage Post 
    424  * @since 2.5 
     400 * @since 2.5.0 
    425401 * 
    426402 * @uses $wpdb 
    427  * @uses $posts {@internal Missing Description}} 
    428403 * 
    429  * @param mixed $post_id post ID 
    430  * @param mixed post type 
    431  * @return bool {@internal Missing Description}} 
     404 * @param int $post_id Post ID to change post type. Not actually optional. 
     405 * @param string $post_type Optional, default is post. Supported values are 'post' or 'page' to name a few. 
     406 * @return int Amount of rows changed. Should be 1 for success and 0 for failure. 
    432407 */ 
    433408function set_post_type( $post_id = 0, $post_type = 'post' ) { 
    434409        global $wpdb; 
    … …  
    445420} 
    446421 
    447422/** 
    448  * get_posts() - Returns a number of posts 
     423 * Retrieve list of latest posts or posts matching criteria. 
    449424 * 
    450425 * {@internal Missing Long Description}} 
    451426 * 
    452  * @package WordPress 
    453  * @subpackage Post 
    454  * @since 1.2 
     427 * @since 1.2.0 
    455428 * @uses $wpdb 
    456429 * @link http://codex.wordpress.org/Template_Tags/get_posts 
    457430 * 
    458  * @param array $args {@internal Missing Description}} 
    459  * @return array {@internal Missing Description}} 
     431 * @param array $args Optional. Override defaults. 
     432 * @return array List of posts. 
    460433 */ 
    461434function get_posts($args = null) { 
    462435        $defaults = array( 
    … …  
    494467// 
    495468 
    496469/** 
    497  * add_post_meta() - adds metadata for post 
     470 * Add meta data field to a post. 
    498471 * 
    499  * {@internal Missing Long Description}} 
     472 * Post meta data is called "Custom Fields" on the Administration Panels. 
    500473 * 
    501  * @package WordPress 
    502  * @subpackage Post 
    503  * @since 1.5 
     474 * @since 1.5.0 
    504475 * @uses $wpdb 
    505476 * @link http://codex.wordpress.org/Function_Reference/add_post_meta 
    506477 * 
    507  * @param int $post_id post ID 
    508  * @param string $key {@internal Missing Description}} 
    509  * @param mixed $value {@internal Missing Description}} 
    510  * @param bool $unique whether to check for a value with the same key 
    511  * @return bool {@internal Missing Description}} 
     478 * @param int $post_id Post ID. 
     479 * @param string $key Metadata name. 
     480 * @param mixed $value Metadata value. 
     481 * @param bool $unique Optional, default is false. Whether the same key should not be added. 
     482 * @return bool False for failure. True for success. 
    512483 */ 
    513484function add_post_meta($post_id, $meta_key, $meta_value, $unique = false) { 
    514485        global $wpdb; 
    … …  
    533504} 
    534505 
    535506/** 
    536  * delete_post_meta() - delete post metadata 
     507 * Remove metadata matching criteria from a post. 
    537508 * 
    538  * {@internal Missing Long Description}} 
     509 * You can match based on the key, or key and value. Removing based on key and 
     510 * value, will keep from removing duplicate metadata with the same key. It also 
     511 * allows removing all metadata matching key, if needed. 
    539512 * 
    540  * @package WordPress 
    541  * @subpackage Post 
    542  * @since 1.5 
     513 * @since 1.5.0 
    543514 * @uses $wpdb 
    544515 * @link http://codex.wordpress.org/Function_Reference/delete_post_meta 
    545516 * 
    546517 * @param int $post_id post ID 
    547  * @param string $key {@internal Missing Description}} 
    548  * @param mixed $value {@internal Missing Description}} 
    549  * @return bool {@internal Missing Description}} 
     518 * @param string $key Metadata name. 
     519 * @param mixed $value Optional. Metadata value. 
     520 * @return bool False for failure. True for success. 
    550521 */ 
    551522function delete_post_meta($post_id, $key, $value = '') { 
    552523        global $wpdb; 
    … …  
    576547} 
    577548 
    578549/** 
    579  * get_post_meta() - Get a post meta field 
     550 * Retrieve post meta field for a post. 
    580551 * 
    581  * {@internal Missing Long Description}} 
    582  * 
    583  * @package WordPress 
    584  * @subpackage Post 
    585  * @since 1.5 
     552 * @since 1.5.0 
    586553 * @uses $wpdb 
    587554 * @link http://codex.wordpress.org/Function_Reference/get_post_meta 
    588555 * 
    589  * @param int $post_id post ID 
    590  * @param string $key The meta key to retrieve 
    591  * @param bool $single Whether to return a single value 
    592  * @return mixed {@internal Missing Description}} 
     556 * @param int $post_id Post ID. 
     557 * @param string $key The meta key to retrieve. 
     558 * @param bool $single Whether to return a single value. 
     559 * @return mixed Will be an array if $single is false. Will be value of meta data field if $single is true. 
    593560 */ 
    594561function get_post_meta($post_id, $key, $single = false) { 
    595562        $post_id = (int) $post_id; 
    … …  
    620587} 
    621588 
    622589/** 
    623  * update_post_meta() - Update a post meta field 
     590 * Update post meta field based on post ID. 
    624591 * 
    625  * {@internal Missing Long Description}} 
     592 * Use the $prev_value parameter to differentiate between meta fields with the 
     593 * same key and post ID. 
    626594 * 
    627  * @package WordPress 
    628  * @subpackage Post 
     595 * If the meta field for the post does not exist, it will be added. 
     596 * 
    629597 * @since 1.5 
    630598 * @uses $wpdb 
    631599 * @link http://codex.wordpress.org/Function_Reference/update_post_meta 
    632600 * 
    633  * @param int $post_id post ID 
    634  * @param string $key {@internal Missing Description}} 
    635  * @param mixed $value {@internal Missing Description}} 
    636  * @param mixed $prev_value previous value (for differentiating between meta fields with the same key and post ID) 
    637  * @return bool {@internal Missing Description}} 
     601 * @param int $post_id Post ID. 
     602 * @param string $key Metadata key. 
     603 * @param mixed $value Metadata value. 
     604 * @param mixed $prev_value Optional. Previous value to check before removing. 
     605 * @return bool False on failure, true if success. 
    638606 */ 
    639607function update_post_meta($post_id, $meta_key, $meta_value, $prev_value = '') { 
    640608        global $wpdb; 
    … …  
    662630} 
    663631 
    664632/** 
    665  * delete_post_meta_by_key() - Delete everything from post meta matching $post_meta_key 
     633 * Delete everything from post meta matching meta key. 
    666634 * 
    667  * @package WordPress 
    668  * @subpackage Post 
    669  * @since 2.3 
     635 * @since 2.3.0 
    670636 * @uses $wpdb 
    671637 * 
    672  * @param string $post_meta_key What to search for when deleting 
     638 * @param string $post_meta_key Key to search for when deleting. 
    673639 * @return bool Whether the post meta key was deleted from the database 
    674640 */ 
    675641function delete_post_meta_by_key($post_meta_key) { 
    … …  
    683649} 
    684650 
    685651/** 
    686  * get_post_custom() - Retrieve post custom fields 
     652 * Retrieve post meta fields, based on post ID. 
    687653 * 
    688  * {@internal Missing Long Description}} 
     654 * The post meta fields are retrieved from the cache, so the function is 
     655 * optimized to be called more than once. It also applies to the functions, that 
     656 * use this function. 
    689657 * 
    690  * @package WordPress 
    691  * @subpackage Post 
    692  * @since 1.2 
     658 * @since 1.2.0 
    693659 * @link http://codex.wordpress.org/Function_Reference/get_post_custom 
    694660 * 
    695  * @uses $id 
    696  * @uses $wpdb 
     661 * @uses $id Current Loop Post ID 
    697662 * 
    698663 * @param int $post_id post ID 
    699664 * @return array {@internal Missing Description}} 
    … …  
    713678} 
    714679 
    715680/** 
    716  * get_post_custom_keys() - Retrieve post custom field names 
     681 * Retrieve meta field names for a post. 
    717682 * 
    718  * @package WordPress 
    719  * @subpackage Post 
    720  * @since 1.2 
     683 * If there are no meta fields, then nothing (null) will be returned. 
     684 * 
     685 * @since 1.2.0 
    721686 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_keys 
    722687 * 
    723688 * @param int $post_id post ID 
    724  * @return array|null Either array of the keys, or null if keys would not be retrieved 
     689 * @return array|null Either array of the keys, or null if keys could not be retrieved. 
    725690 */ 
    726691function get_post_custom_keys( $post_id = 0 ) { 
    727692        $custom = get_post_custom( $post_id ); 
    … …  
    734699} 
    735700 
    736701/** 
    737  * get_post_custom_values() - Retrieve values for a custom post field 
     702 * Retrieve values for a custom post field. 
    738703 * 
    739  * @package WordPress 
    740  * @subpackage Post 
    741  * @since 1.2 
     704 * The parameters must not be considered optional. All of the post meta fields 
     705 * will be retrieved and only the meta field key values returned. 
     706 * 
     707 * @since 1.2.0 
    742708 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_values 
    743709 * 
    744  * @param string $key field name 
    745  * @param int $post_id post ID 
    746  * @return mixed {@internal Missing Description}} 
     710 * @param string $key Meta field key. 
     711 * @param int $post_id Post ID 
     712 * @return array Meta field values. 
    747713 */ 
    748714function get_post_custom_values( $key = '', $post_id = 0 ) { 
    749715        $custom = get_post_custom($post_id); 
    … …  
    752718} 
    753719 
    754720/** 
    755  * is_sticky() - Check if post is sticky 
     721 * Check if post is sticky. 
    756722 * 
    757  * {@internal Missing Long Description}} 
     723 * Sticky posts should remain at the top of The Loop. If the post ID is not 
     724 * given, then The Loop ID for the current post will be used. 
    758725 * 
    759  * @package WordPress 
    760  * @subpackage Post 
    761  * @since 2.7 
     726 * @since 2.7.0 
    762727 * 
    763  * @param int $post_id A post ID 
    764  * @return bool 
     728 * @param int $post_id Optional. Post ID. 
     729 * @return bool Whether post is sticky (true) or not sticky (false). 
    765730 */ 
    766731function is_sticky($post_id = null) { 
    767732        global $id; 
    … …  
    782747        return false; 
    783748} 
    784749 
    785  
    786750/** 
    787  * sanitize_post() - Sanitize every post field 
     751 * Sanitize every post field. 
    788752 * 
    789  * {@internal Missing Long Description}} 
     753 * If the context is 'raw', then the post object or array will just be returned. 
    790754 * 
    791  * @package WordPress 
    792  * @subpackage Post 
    793  * @since 2.3 
     755 * @since 2.3.0 
     756 * @uses sanitize_post_field() Used to sanitize the fields. 
    794757 * 
    795758 * @param object|array $post The Post Object or Array 
    796  * @param string $context How to sanitize post fields 
     759 * @param string $context Optional, default is 'display'. How to sanitize post fields. 
    797760 * @return object|array The now sanitized Post Object or Array (will be the same type as $post) 
    798761 */ 
    799762function sanitize_post($post, $context = 'display') { 
    … …  
    810773} 
    811774 
    812775/** 
    813  * sanitize_post_field() - Sanitize post field based on context 
     776 * Sanitize post field based on context. 
    814777 * 
    815  * {@internal Missing Long Description}} 
     778 * Possible context values are: raw, edit, db, attribute, js, and display. The 
     779 * display context is used by default. 
    816780 * 
    817  * @package WordPress 
    818  * @subpackage Post 
    819  * @since 2.3 
     781 * @since 2.3.0 
    820782 * 
    821  * @param string $field The Post Object field name 
    822  * @param string $value The Post Object value 
    823  * @param int $postid Post ID 
    824  * @param string $context How to sanitize post fields 
    825  * @return string Sanitized value 
     783 * @param string $field The Post Object field name. 
     784 * @param mixed $value The Post Object value. 
     785 * @param int $post_id Post ID. 
     786 * @param string $context How to sanitize post fields. 
     787 * @return mixed Sanitized value. 
    826788 */ 
    827789function sanitize_post_field($field, $value, $post_id, $context) { 
    828790        $int_fields = array('ID', 'post_parent', 'menu_order'); 
    … …  
    882844} 
    883845 
    884846/** 
    885  * Make a post sticky 
     847 * Make a post sticky. 
    886848 * 
    887  * Makes a post stick to the top of the front page 
     849 * Sticky posts should be displayed at the top of the front page. 
    888850 * 
    889  * @package WordPress 
    890  * @subpackage Post 
    891  * @since 2.7 
     851 * @since 2.7.0 
    892852 * 
    893  * @param int $post_id A post ID 
     853 * @param int $post_id Post ID. 
    894854 */ 
    895855function stick_post($post_id) { 
    896856        $stickies = get_option('sticky_posts'); 
    … …  
    905865} 
    906866 
    907867/** 
    908  * Unstick a post 
     868 * Unstick a post. 
    909869 * 
    910  * Unstick a post from the front page 
     870 * Sticky posts should be displayed at the top of the front page. 
    911871 * 
    912  * @package WordPress 
    913  * @subpackage Post 
    914  * @since 2.7 
     872 * @since 2.7.0 
    915873 * 
    916  * @param int $post_id A post ID 
     874 * @param int $post_id Post ID. 
    917875 */ 
    918876function unstick_post($post_id) { 
    919877        $stickies = get_option('sticky_posts'); 
    … …  
    944902 * The $perm parameter checks for 'readable' value and if the user can read 
    945903 * private posts, it will display that for the user that is signed in. 
    946904 * 
    947  * @package WordPress 
    948  * @subpackage Post 
    949  * @since 2.5 
     905 * @since 2.5.0 
    950906 * @link http://codex.wordpress.org/Template_Tags/wp_count_posts 
    951907 * 
    952908 * @param string $type Optional. Post type to retrieve count 
    … …  
    988944 
    989945 
    990946/** 
    991  * wp_count_attachments() - Count number of attachments 
     947 * Count number of attachments for the mime type(s). 
    992948 * 
    993  * {@internal Missing Long Description}} 
     949 * If you set the optional mime_type parameter, then an array will still be 
     950 * returned, but will only have the item you are looking for. It does not give 
     951 * you the number of attachments that are children of a post. You can get that 
     952 * by counting the number of children that post has. 
    994953 * 
    995  * @package WordPress 
    996  * @subpackage Post 
    997  * @since 2.5 
     954 * @since 2.5.0 
    998955 * 
    999  * @param string|array $post_mime_type Array or comma-separated list of MIME patterns 
    1000  * @return array Number of posts for each post_mime_type 
     956 * @param string|array $mime_type Optional. Array or comma-separated list of MIME patterns. 
     957 * @return array Number of posts for each mime type. 
    1001958 */ 
    1002  
    1003959function wp_count_attachments( $mime_type = '' ) { 
    1004960        global $wpdb; 
    1005961 
    … …  
    1015971} 
    1016972 
    1017973/** 
    1018  * wp_match_mime_type() - Check a MIME-Type against a list 
     974 * Check a MIME-Type against a list. 
    1019975 * 
    1020  * {@internal Missing Long Description}} 
     976 * If the wildcard_mime_types parameter is a string, it must be comma separated 
     977 * list. If the real_mime_types is a string, it is also comma separated to 
     978 * create the list. 
    1021979 * 
    1022  * @package WordPress 
    1023  * @subpackage Post 
    1024  * @since 2.5 
     980 * @since 2.5.0 
    1025981 * 
    1026982 * @param string|array $wildcard_mime_types e.g. audio/mpeg or image (same as image/*) or flash (same as *flash*) 
    1027983 * @param string|array $real_mime_types post_mime_type values 
    … …  
    10521008} 
    10531009 
    10541010/** 
    1055  * wp_get_post_mime_type_where() - Convert MIME types into SQL 
     1011 * Convert MIME types into SQL. 
    10561012 * 
    1057  * @package WordPress 
    1058  * @subpackage Post 
    1059  * @since 2.5 
     1013 * @since 2.5.0 
    10601014 * 
    1061  * @param string|array $mime_types MIME types 
    1062  * @return string SQL AND clause 
     1015 * @param string|array $mime_types List of mime types or comma separated string of mime types. 
     1016 * @return string The SQL AND clause for mime searching. 
    10631017 */ 
    10641018function wp_post_mime_type_where($post_mime_types) { 
    10651019        $where = ''; 
    … …  
    10991053} 
    11001054 
    11011055/** 
    1102  * wp_delete_post() - Deletes a Post 
     1056 * Removes a post, attachment, or page post type. 
    11031057 * 
    1104  * {@internal Missing Long Description}} 
    1105  * 
    1106  * @package WordPress 
    1107  * @subpackage Post 
    11081058 * @since 1.0.0 
     1059 * @uses do_action() Calls 'deleted_post' hook on post ID. 
    11091060 * 
    1110  * @param int $postid post ID 
    1111  * @return mixed {@internal Missing Description}} 
     1061 * @param int $postid Post ID. 
     1062 * @return mixed 
    11121063 */ 
    11131064function wp_delete_post($postid = 0) { 
    11141065        global $wpdb, $wp_rewrite; 
    … …  
    11771128} 
    11781129 
    11791130/** 
    1180  * wp_get_post_categories() - Retrieve the list of categories for a post 
     1131 * Retrieve the list of categories for a post. 
    11811132 * 
    11821133 * Compatibility layer for themes and plugins. Also an easy layer of abstraction 
    11831134 * away from the complexity of the taxonomy layer. 
    11841135 * 
    1185  * @package WordPress 
    1186  * @subpackage Post 
    1187  * @since 2.1 
     1136 * @since 2.1.0 
    11881137 * 
    11891138 * @uses wp_get_object_terms() Retrieves the categories. Args details can be found here 
    11901139 * 
    … …  
    12031152} 
    12041153 
    12051154/** 
    1206  * wp_get_post_tags() - Retrieve the post tags 
     1155 * Retrieve the tags for a post. 
    12071156 * 
     1157 * There is only one default for this function, called 'fields' and by default 
     1158 * is set to 'all'. There are other defaults that can be override in 
     1159 * {@link wp_get_object_terms()}. 
     1160 * 
    12081161 * @package WordPress 
    12091162 * @subpackage Post 
    1210  * @since 2.3 
     1163 * @since 2.3.0 
    12111164 * 
    12121165 * @uses wp_get_object_terms() Gets the tags for returning. Args can be found here 
    12131166 * 
    12141167 * @param int $post_id Optional. The Post ID 
    12151168 * @param array $args Optional. Overwrite the defaults 
    1216  * @return mixed The tags the post has currently 
     1169 * @return array List of post tags. 
    12171170 */ 
    12181171function wp_get_post_tags( $post_id = 0, $args = array() ) { 
    12191172        $post_id = (int) $post_id; 
    … …  
    12271180} 
    12281181 
    12291182/** 
    1230  * wp_get_recent_posts() - Get the $num most recent posts 
     1183 * Retrieve number of recent posts. 
    12311184 * 
    1232  * {@internal Missing Long Description}} 
    1233  * 
    1234  * @package WordPress 
    1235  * @subpackage Post 
    12361185 * @since 1.0.0 
     1186 * @uses $wpdb 
    12371187 * 
    1238  * @param int $num number of posts to get 
    1239  * @return array {@internal Missing Description}} 
     1188 * @param int $num Optional, default is 10. Number of posts to get. 
     1189 * @return array List of posts. 
    12401190 */ 
    12411191function wp_get_recent_posts($num = 10) { 
    12421192        global $wpdb; 
    … …  
    12501200        $sql = "SELECT * FROM $wpdb->posts WHERE post_type = 'post' ORDER BY post_date DESC $limit"; 
    12511201        $result = $wpdb->get_results($sql,ARRAY_A); 
    12521202 
    1253         return $result?$result:array(); 
     1203        return $result ? $result : array(); 
    12541204} 
    12551205 
    12561206/** 
    1257  * wp_get_single_post() - Get one post 
     1207 * Retrieve a single post, based on post ID. 
    12581208 * 
    1259  * {@internal Missing Long Description}} 
     1209 * Has categories in 'post_category' property or key. Has tags in 'tags_input' 
     1210 * property or key. 
    12601211 * 
    1261  * @package WordPress 
    1262  * @subpackage Post 
    12631212 * @since 1.0.0 
    1264  * @uses $wpdb 
    12651213 * 
    1266  * @param int $postid post ID 
    1267  * @param string $mode How to return result, either OBJECT, ARRAY_N, or ARRAY_A 
     1214 * @param int $postid Post ID 
     1215 * @param string $mode How to return result, either OBJECT, ARRAY_N, or ARRAY_A. 
    12681216 * @return object|array Post object or array holding post contents and information 
    12691217 */ 
    12701218function wp_get_single_post($postid = 0, $mode = OBJECT) { 
    … …  
    12861234} 
    12871235 
    12881236/** 
    1289  * wp_insert_post() - Insert a post 
     1237 * wp_insert_post() -  
    12901238 * 
    1291  * {@internal Missing Long Description}} 
    1292  * 
    12931239 * @package WordPress 
    12941240 * @subpackage Post 
    1295  * @since 1.0.0 
    12961241 * 
     1242 * @uses $allowedtags 
     1243 * 
     1244 * @param array $postarr  
     1245 * @return int post ID or 0 on error 
     1246 */ 
     1247/** 
     1248 * Insert a post. 
     1249 * 
     1250 * {@internal Missing Long Description}} 
     1251 * 
     1252 * @since 1.0.0 
    12971253 * @uses $wpdb 
    12981254 * @uses $wp_rewrite 
    12991255 * @uses $user_ID 
    1300  * @uses $allowedtags 
    13011256 * 
    1302  * @param array $postarr post contents 
    1303  * @return int post ID or 0 on error 
     1257 * @param array $postarr Optional. Override defaults. 
     1258 * @param bool $wp_error Optional. Allow return of WP_Error on failure. 
     1259 * @return int|WP_Error {@internal Missing Description}} 
    13041260 */ 
    13051261function wp_insert_post($postarr = array(), $wp_error = false) { 
    13061262        global $wpdb, $wp_rewrite, $user_ID; 
    … …  
    15111467 * 
    15121468 * {@internal Missing Long Description}} 
    15131469 * 
    1514  * @package WordPress 
    1515  * @subpackage Post 
    15161470 * @since 1.0.0 
    15171471 * @uses $wpdb 
    15181472 * 
    1519  * @param array $postarr post data 
     1473 * @param array|object $postarr post data 
    15201474 * @return int {@internal Missing Description}} 
    15211475 */ 
    15221476function wp_update_post($postarr = array()) { 
    … …  
    15581512} 
    15591513 
    15601514/** 
    1561  * wp_publish_post() - Mark a post as "published" 
     1515 * Publish a post by transitioning the post status. 
    15621516 * 
    1563  * {@internal Missing Long Description}} 
    1564  * 
    1565  * @package WordPress 
    1566  * @subpackage Post 
    1567  * @since 2.1 
     1517 * @since 2.1.0 
    15681518 * @uses $wpdb 
     1519 * @uses do_action() Calls 'edit_post', 'save_post', and 'wp_insert_post' on post_id and post data. 
    15691520 * 
    15701521 * @param int $post_id Post ID 
    15711522 * @return int|null {@internal Missing Description}} 
    … …  
    15991550} 
    16001551 
    16011552/** 
    1602  * check_and_publish_future_post() - check to make sure post has correct status before 
    1603  * passing it on to be published. Invoked by cron 'publish_future_post' event 
    1604  * This safeguard prevents cron from publishing drafts, etc. 
     1553 * Publish future post and make sure post ID has future post status. 
    16051554 * 
    1606  * {@internal Missing Long Description}} 
     1555 * Invoked by cron 'publish_future_post' event. This safeguard prevents cron 
     1556 * from publishing drafts, etc. 
    16071557 * 
    1608  * @package WordPress 
    1609  * @subpackage Post 
    1610  * @since 2.5 
    1611  * @uses $wpdb 
     1558 * @since 2.5.0 
    16121559 * 
    1613  * @param int $post_id Post ID 
    1614  * @return int|null {@internal Missing Description}} 
     1560 * @param int $post_id Post ID. 
     1561 * @return null Nothing is returned. Which can mean that no action is required or post was published. 
    16151562 */ 
    16161563function check_and_publish_future_post($post_id) { 
    16171564 
    … …  
    16271574} 
    16281575 
    16291576/** 
    1630  * wp_add_post_tags() - Adds the tags to a post 
     1577 * Adds tags to a post. 
    16311578 * 
    1632  * @uses wp_set_post_tags() Same first two paraeters, but the last parameter is always set to true. 
     1579 * @uses wp_set_post_tags() Same first two parameters, but the last parameter is always set to true. 
    16331580 * 
    16341581 * @package WordPress 
    16351582 * @subpackage Post 
    1636  * @since 2.3 
     1583 * @since 2.3.0 
    16371584 * 
    1638  * @param int $post_id Optional. Post ID 
    1639  * @param string $tags The tags to set for the post 
     1585 * @param int $post_id Post ID 
     1586 * @param string $tags The tags to set for the post, separated by commas. 
    16401587 * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise 
    16411588 */ 
    16421589function wp_add_post_tags($post_id = 0, $tags = '') { 
    16431590        return wp_set_post_tags($post_id, $tags, true); 
    16441591} 
    16451592 
     1593 
    16461594/** 
    1647  * wp_set_post_tags() - Set the tags for a post 
     1595 * Set the tags for a post. 
    16481596 * 
    1649  * {@internal Missing Long Description}} 
     1597 * @since 2.3.0 
     1598 * @uses wp_set_object_terms() Sets the tags for the post. 
    16501599 * 
    1651  * @package WordPress 
    1652  * @subpackage Post 
    1653  * @since 2.3 
    1654  * @uses $wpdb 
    1655  * 
    1656  * @param int $post_id post ID 
    1657  * @param string $tags The tags to set for the post 
     1600 * @param int $post_id Post ID. 
     1601 * @param string $tags The tags to set for the post, separated by commas. 
    16581602 * @param bool $append If true, don't delete existing tags, just add on. If false, replace the tags with the new tags. 
    16591603 * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise 
    16601604 */ 
    … …  
    16721616} 
    16731617 
    16741618/** 
    1675  * wp_set_post_categories() - Set categories for a post 
     1619 * Set categories for a post. 
    16761620 * 
    1677  * {@internal Missing Long Description}} 
     1621 * If the post categories parameter is not set, then the default category is 
     1622 * going used. 
    16781623 * 
    1679  * @package WordPress 
    1680  * @subpackage Post 
    1681  * @since 2.1 
    1682  * @uses $wpdb 
     1624 * @since 2.1.0 
    16831625 * 
    1684  * @param int $post_ID post ID 
    1685  * @param array $post_categories 
    1686  * @return bool|mixed {@internal Missing Description}} 
     1626 * @param int $post_ID Post ID. 
     1627 * @param array $post_categories Optional. List of categories. 
     1628 * @return bool|mixed 
    16871629 */ 
    16881630function wp_set_post_categories($post_ID = 0, $post_categories = array()) { 
    16891631        $post_ID = (int) $post_ID; 
    … …  
    16971639        $post_categories = array_unique($post_categories); 
    16981640 
    16991641        return wp_set_object_terms($post_ID, $post_categories, 'category'); 
    1700 }       // wp_set_post_categories() 
     1642} 
    17011643 
    17021644/** 
    1703  * wp_transition_post_status() - Change the post transition status 
     1645 * Transition the post status of a post. 
    17041646 * 
    1705  * {@internal Missing Long Description}} 
     1647 * Calls hooks to transition post status. If the new post status is not the same 
     1648 * as the previous post status, then two hooks will be ran, the first is 
     1649 * 'transition_post_status' with new status, old status, and post data. The 
     1650 * next action called is 'OLDSTATUS_to_NEWSTATUS' the NEWSTATUS is the 
     1651 * $new_status parameter and the OLDSTATUS is $old_status parameter; it has the 
     1652 * post data. 
    17061653 * 
    1707  * @package WordPress 
    1708  * @subpackage Post 
    1709  * @since 2.3 
     1654 * The final action will run whether or not the post statuses are the same. The 
     1655 * action is named 'NEWSTATUS_POSTTYPE', NEWSTATUS is from the $new_status 
     1656 * parameter and POSTTYPE is post_type post data. 
    17101657 * 
    1711  * @param string $new_status {@internal Missing Description}} 
    1712  * @param string $old_status {@internal Missing Description}} 
    1713  * @param int $post {@internal Missing Description}} 
     1658 * @since 2.3.0 
     1659 * 
     1660 * @param string $new_status Transition to this post status. 
     1661 * @param string $old_status Previous post status. 
     1662 * @param object $post Post data. 
    17141663 */ 
    17151664function wp_transition_post_status($new_status, $old_status, $post) { 
    17161665        if ( $new_status != $old_status ) { 
    … …  
    17251674// 
    17261675 
    17271676/** 
    1728  * add_ping() - Add a URL to those already pung 
     1677 * Add a URL to those already pung. 
    17291678 * 
    1730  * {@internal Missing Long Description}} 
    1731  * 
    1732  * @package WordPress 
    1733  * @subpackage Post 
    1734  * @since 1.5 
     1679 * @since 1.5.0 
    17351680 * @uses $wpdb 
    17361681 * 
    1737  * @param int $post_id post ID 
    1738  * @param string $uri {@internal Missing Description}} 
    1739  * @return mixed {@internal Missing Description}} 
     1682 * @param int $post_id Post ID. 
     1683 * @param string $uri Ping URI. 
     1684 * @return int How many rows were updated. 
    17401685 */ 
    17411686function add_ping($post_id, $uri) { 
    17421687        global $wpdb; 
    … …  
    17521697} 
    17531698 
    17541699/** 
    1755  * get_enclosed() - Get enclosures already enclosed for a post 
     1700 * Retrieve enclosures already enclosed for a post. 
    17561701 * 
    1757  * {@internal Missing Long Description}} 
    1758  * 
    1759  * @package WordPress 
    1760  * @subpackage Post 
    1761  * @since 1.5 
     1702 * @since 1.5.0 
    17621703 * @uses $wpdb 
    17631704 * 
    1764  * @param int $post_id post ID 
    1765  * @return array {@internal Missing Description}} 
     1705 * @param int $post_id Post ID. 
     1706 * @return array List of enclosures 
    17661707 */ 
    17671708function get_enclosed($post_id) { 
    17681709        $custom_fields = get_post_custom( $post_id ); 
    … …  
    17831724} 
    17841725 
    17851726/** 
    1786  * get_pung() - Get URLs already pinged for a post 
     1727 * Retrieve URLs already pinged for a post. 
    17871728 * 
    1788  * {@internal Missing Long Description}} 
    1789  * 
    1790  * @package WordPress 
    1791  * @subpackage Post 
    1792  * @since 1.5 
     1729 * @since 1.5.0 
    17931730 * @uses $wpdb 
    17941731 * 
    1795  * @param int $post_id post ID 
    1796  * @return array {@internal Missing Description}} 
     1732 * @param int $post_id Post ID. 
     1733 * @return array 
    17971734 */ 
    17981735function get_pung($post_id) { 
    17991736        global $wpdb; 
    … …  
    18051742} 
    18061743 
    18071744/** 
    1808  * get_to_ping() - Get any URLs in the todo list 
     1745 * Retrieve URLs that need to be pinged. 
    18091746 * 
    1810  * {@internal Missing Long Description}} 
    1811  * 
    1812  * @package WordPress 
    1813  * @subpackage Post 
    1814  * @since 1.5 
     1747 * @since 1.5.0 
    18151748 * @uses $wpdb 
    18161749 * 
    1817  * @param int $post_id post ID 
    1818  * @return array {@internal Missing Description}} 
     1750 * @param int $post_id Post ID 
     1751 * @return array 
    18191752 */ 
    18201753function get_to_ping($post_id) { 
    18211754        global $wpdb; 
    … …  
    18271760} 
    18281761 
    18291762/** 
    1830  * trackback_url_list() - Do trackbacks for a list of urls 
     1763 * Do trackbacks for a list of URLs. 
    18311764 * 
    1832  * {@internal Missing Long Description}} 
    1833  * 
    1834  * @package WordPress 
    1835  * @subpackage Post 
    18361765 * @since 1.0.0 
    18371766 * 
    1838  * @param string $tb_list comma separated list of URLs 
    1839  * @param int $post_id post ID 
     1767 * @param string $tb_list Comma separated list of URLs 
     1768 * @param int $post_id Post ID 
    18401769 */ 
    18411770function trackback_url_list($tb_list, $post_id) { 
    1842         if (!empty($tb_list)) { 
     1771        if ( ! empty( $tb_list ) ) { 
    18431772                // get post data 
    18441773                $postdata = wp_get_single_post($post_id, ARRAY_A); 
    18451774 
    … …  
    18471776                extract($postdata, EXTR_SKIP); 
    18481777 
    18491778                // form an excerpt 
    1850                 $excerpt = strip_tags($post_excerpt?$post_excerpt:$post_content); 
     1779                $excerpt = strip_tags($post_excerpt ? $post_excerpt : $post_content); 
    18511780 
    18521781                if (strlen($excerpt) > 255) { 
    18531782                        $excerpt = substr($excerpt,0,252) . '...'; 
    … …  
    18551784 
    18561785                $trackback_urls = explode(',', $tb_list); 
    18571786                foreach( (array) $trackback_urls as $tb_url) { 
    1858                                 $tb_url = trim($tb_url); 
    1859                                 trackback($tb_url, stripslashes($post_title), $excerpt, $post_id); 
     1787                        $tb_url = trim($tb_url); 
     1788                        trackback($tb_url, stripslashes($post_title), $excerpt, $post_id); 
    18601789                } 
    1861                 } 
     1790        } 
    18621791} 
    18631792 
    18641793// 
    … …  
    18661795// 
    18671796 
    18681797/** 
    1869  * get_all_page_ids() - Get a list of page IDs 
     1798 * Get a list of page IDs. 
    18701799 * 
    1871  * {@internal Missing Long Description}} 
    1872  * 
    1873  * @package WordPress 
    1874  * @subpackage Post 
    1875  * @since 2.0 
     1800 * @since 2.0.0 
    18761801 * @uses $wpdb 
    18771802 * 
    1878  * @return array {@internal Missing Description}} 
     1803 * @return array List of page IDs. 
    18791804 */ 
    18801805function get_all_page_ids() { 
    18811806        global $wpdb; 
    … …  
    18891814} 
    18901815 
    18911816/** 
    1892  * get_page() - Retrieves page data given a page ID or page object 
     1817 * Retrieves page data given a page ID or page object. 
    18931818 * 
    1894  * {@internal Missing Long Description}} 
    1895  * 
    1896  * @package WordPress 
    1897  * @subpackage Post 
    18981819 * @since 1.5.1 
    18991820 * 
    1900  * @param mixed &$page page object or page ID 
    1901  * @param string $output what to output 
     1821 * @param mixed $page Page object or page ID. Passed by reference. 
     1822 * @param string $output What to output. OBJECT, ARRAY_A, or ARRAY_N. 
    19021823 * @param string $filter How the return value should be filtered. 
    1903  * @return mixed {@internal Missing Description}} 
     1824 * @return mixed Page data. 
    19041825 */ 
    19051826function &get_page(&$page, $output = OBJECT, $filter = 'raw') { 
    19061827        if ( empty($page) ) { 
    … …  
    19161837} 
    19171838 
    19181839/** 
    1919  * get_page_by_path() - Retrieves a page given its path 
     1840 * Retrieves a page given its path. 
    19201841 * 
    1921  * {@internal Missing Long Description}} 
    1922  * 
    1923  * @package WordPress 
    1924  * @subpackage Post 
    1925  * @since 2.1 
     1842 * @since 2.1.0 
    19261843 * @uses $wpdb 
    19271844 * 
    1928  * @param string $page_path page path 
    1929  * @param string $output output type 
    1930  * @return mixed {@internal Missing Description}} 
     1845 * @param string $page_path Page path 
     1846 * @param string $output Optional. Output type. OBJECT, ARRAY_N, or ARRAY_A. 
     1847 * @return mixed Null when complete. 
    19311848 */ 
    19321849function get_page_by_path($page_path, $output = OBJECT) { 
    19331850        global $wpdb; 
    … …  
    19441861        $pages = $wpdb->get_results( $wpdb->prepare( "SELECT ID, post_name, post_parent FROM $wpdb->posts WHERE post_name = %s AND (post_type = 'page' OR post_type = 'attachment')", $leaf_path )); 
    19451862 
    19461863        if ( empty($pages) ) 
    1947                 return NULL; 
     1864                return null; 
    19481865 
    19491866        foreach ($pages as $page) { 
    19501867                $path = '/' . $leaf_path; 
    … …  
    19581875                        return get_page($page->ID, $output); 
    19591876        } 
    19601877 
    1961         return NULL; 
     1878        return null; 
    19621879} 
    19631880 
    19641881/** 
    1965  * get_page_by_title() - Retrieve a page given its title 
     1882 * Retrieve a page given its title. 
    19661883 * 
    1967  * {@internal Missing Long Description}} 
    1968  * 
    1969  * @package WordPress 
    1970  * @subpackage Post 
    1971  * @since 2.1 
     1884 * @since 2.1.0 
    19721885 * @uses $wpdb 
    19731886 * 
    1974  * @param string $page_title page title 
    1975  * @param string $output output type 
    1976  * @return mixed {@internal Missing Description}} 
     1887 * @param string $page_title Page title 
     1888 * @param string $output Optional. Output type. OBJECT, ARRAY_N, or ARRAY_A. 
     1889 * @return mixed 
    19771890 */ 
    19781891function get_page_by_title($page_title, $output = OBJECT) { 
    19791892        global $wpdb; 
    … …  
    19811894        if ( $page ) 
    19821895                return get_page($page, $output); 
    19831896 
    1984         return NULL; 
     1897        return null; 
    19851898} 
    19861899 
    19871900/** 
    … …  
    19891902 * 
    19901903 * {@internal Missing Long Description}} 
    19911904 * 
    1992  * @package WordPress 
    1993  * @subpackage Post 
    19941905 * @since 1.5.1 
    19951906 * 
    19961907 * @param int $page_id page ID 
    … …  
    20361947} 
    20371948 
    20381949/** 
    2039  * get_page_uri() - Builds a page URI 
     1950 * Builds a page URI. 
    20401951 * 
    2041  * {@internal Missing Long Description}} 
     1952 * @since 1.5.0 
    20421953 * 
    2043  * @package WordPress 
    2044  * @subpackage Post 
    2045  * @since 1.5 
    2046  * 
    2047  * @param int $page_id page ID 
    2048  * @return string {@internal Missing Description}} 
     1954 * @param int $page_id Page ID. 
     1955 * @return string Page URI. 
    20491956 */ 
    20501957function get_page_uri($page_id) { 
    20511958        $page = get_page($page_id); 
    … …  
    20641971} 
    20651972 
    20661973/** 
    2067  * get_pages() - Retrieve a list of pages 
     1974 * Retrieve a list of pages. 
    20681975 * 
    20691976 * {@internal Missing Long Description}} 
    20701977 * 
    2071  * @package WordPress 
    2072  * @subpackage Post 
    2073  * @since 1.5 
     1978 * @since 1.5.0 
    20741979 * @uses $wpdb 
    20751980 * 
    2076  * @param mixed $args Optional. Array or string of options 
     1981 * @param mixed $args Optional. Array or string of options that overrides defaults. 
    20771982 * @return array List of pages matching defaults or $args 
    20781983 */ 
    20791984function &get_pages($args = '') { 
    … …  
    21982103// 
    21992104 
    22002105/** 
    2201  * is_local_attachment() - Check if the attachment URI is local one and is really an attachment. 
     2106 * Check if the attachment URI is local one and is really an attachment. 
    22022107 * 
    2203  * {@internal Missing Long Description}} 
     2108 * @since 2.0.0 
    22042109 * 
    2205  * @package WordPress 
    2206  * @subpackage Post 
    2207  * @since 2.0 
    2208  * 
    22092110 * @param string $url URL to check 
    2210  * @return bool {@internal Missing Description}} 
     2111 * @return bool True on success, false on failure. 
    22112112 */ 
    22122113function is_local_attachment($url) { 
    22132114        if (strpos($url, get_bloginfo('url')) === false) 
    … …  
    22232124} 
    22242125 
    22252126/** 
    2226  * wp_insert_attachment() - Insert an attachment 
     2127 * Insert an attachment. 
    22272128 * 
    22282129 * {@internal Missing Long Description}} 
    22292130 * 
    2230  * @package WordPress 
    2231  * @subpackage Post 
    2232  * @since 2.0 
    2233  * 
     2131 * @since 2.0.0 
    22342132 * @uses $wpdb 
    22352133 * @uses $user_ID 
    22362134 * 
    2237  * @param object $object attachment object 
    2238  * @param string $file filename 
    2239  * @param int $post_parent parent post ID 
     2135 * @param object $object Attachment object. 
     2136 * @param string $file Optional filename. 
     2137 * @param int $post_parent Parent post ID. 
    22402138 * @return int {@internal Missing Description}} 
    22412139 */ 
    22422140function wp_insert_attachment($object, $file = false, $parent = 0) { 
    … …  
    23672265} 
    23682266 
    23692267/** 
    2370  * wp_delete_attachment() - Delete an attachment 
     2268 * Delete an attachment. 
    23712269 * 
    2372  * {@internal Missing Long Description}} 
     2270 * Will remove the file also, when the attachment is removed. 
    23732271 * 
    2374  * @package WordPress 
    2375  * @subpackage Post 
    2376  * @since 2.0 
     2272 * @since 2.0.0 
    23772273 * @uses $wpdb 
    23782274 * 
    2379  * @param int $postid attachment Id 
    2380  * @return mixed {@internal Missing Description}} 
     2275 * @param int $postid Attachment ID 
     2276 * @return mixed False on failure. Post data on success. 
    23812277 */ 
    23822278function wp_delete_attachment($postid) { 
    23832279        global $wpdb; 
    … …  
    24312327} 
    24322328 
    24332329/** 
    2434  * wp_get_attachment_metadata() - Retrieve metadata for an attachment 
     2330 * Retrieve attachment meta field for attachment ID. 
    24352331 * 
    2436  * {@internal Missing Long Description}} 
     2332 * @since 2.1.0 
    24372333 * 
    2438  * @package WordPress 
    2439  * @subpackage Post 
    2440  * @since 2.1 
    2441  * 
    2442  * @param int $post_id attachment ID 
    2443  * @param bool $unfiltered Optional, default is false. If true, filters are not run 
    2444  * @return array {@internal Missing Description}} 
     2334 * @param int $post_id Attachment ID 
     2335 * @param bool $unfiltered Optional, default is false. If true, filters are not run. 
     2336 * @return string|bool Attachment meta field. False on failure. 
    24452337 */ 
    24462338function wp_get_attachment_metadata( $post_id, $unfiltered = false ) { 
    24472339        $post_id = (int) $post_id; 
    … …  
    24552347} 
    24562348 
    24572349/** 
    2458  * wp_update_attachment_metadata() - Update metadata for an attachment 
     2350 * Update metadata for an attachment. 
    24592351 * 
    2460  * {@internal Missing Long Description}} 
     2352 * @since 2.1.0 
    24612353 * 
    2462  * @package WordPress 
    2463  * @subpackage Post 
    2464  * @since 2.1 
    2465  * 
    24662354 * @param int $post_id attachment ID 
    24672355 * @param array $data attachment data 
    2468  * @return int {@internal Missing Description}} 
     2356 * @return int 
    24692357 */ 
    24702358function wp_update_attachment_metadata( $post_id, $data ) { 
    24712359        $post_id = (int) $post_id; 
    … …  
    24782366} 
    24792367 
    24802368/** 
    2481  * wp_get_attachment_url() - Retrieve the URL for an attachment 
     2369 * Retrieve the URL for an attachment. 
    24822370 * 
    2483  * {@internal Missing Long Description}} 
     2371 * @since 2.1.0 
    24842372 * 
    2485  * @package WordPress 
    2486  * @subpackage Post 
    2487  * @since 2.1 
    2488  * 
    2489  * @param int $post_id attachment ID 
    2490  * @return string {@internal Missing Description}} 
     2373 * @param int $post_id Attachment ID. 
     2374 * @return string 
    24912375 */ 
    24922376function wp_get_attachment_url( $post_id = 0 ) { 
    24932377        $post_id = (int) $post_id; 
    … …  
    25032387} 
    25042388 
    25052389/** 
    2506  * wp_get_attachment_thumb_file() - Retrieve thumbnail for an attachment 
     2390 * Retrieve thumbnail for an attachment. 
    25072391 * 
    2508  * {@internal Missing Long Description}} 
     2392 * @since 2.1.0 
    25092393 * 
    2510  * @package WordPress 
    2511  * @subpackage Post 
    2512  * @since 2.1 
    2513  * 
    2514  * @param int $post_id attachment ID 
    2515  * @return mixed {@internal Missing Description}} 
     2394 * @param int $post_id Attachment ID. 
     2395 * @return mixed False on failure. Thumbnail file path on success. 
    25162396 */ 
    25172397function wp_get_attachment_thumb_file( $post_id = 0 ) { 
    25182398        $post_id = (int) $post_id; 
    … …  
    25292409} 
    25302410 
    25312411/** 
    2532  * wp_get_attachment_thumb_url() - Retrieve URL for an attachment thumbnail 
     2412 * Retrieve URL for an attachment thumbnail. 
    25332413 * 
    2534  * {@internal Missing Long Description}} 
     2414 * @since 2.1.0 
    25352415 * 
    2536  * @package WordPress 
    2537  * @subpackage Post 
    2538  * @since 2.1 
    2539  * 
    2540  * @param int $post_id attachment ID 
    2541  * @return string {@internal Missing Description}} 
     2416 * @param int $post_id Attachment ID 
     2417 * @return string|bool False on failure. Thumbnail URL on success. 
    25422418 */ 
    25432419function wp_get_attachment_thumb_url( $post_id = 0 ) { 
    25442420        $post_id = (int) $post_id; 
    … …  
    25602436} 
    25612437 
    25622438/** 
    2563  * wp_attachment_is_image() - Check if the attachment is an image 
     2439 * Check if the attachment is an image. 
    25642440 * 
    2565  * {@internal Missing Long Description}} 
     2441 * @since 2.1.0 
    25662442 * 
    2567  * @package WordPress 
    2568  * @subpackage Post 
    2569  * @since 2.1 
    2570  * 
    2571  * @param int $post_id attachment ID 
    2572  * @return bool {@internal Missing Description}} 
     2443 * @param int $post_id Attachment ID 
     2444 * @return bool 
    25732445 */ 
    25742446function wp_attachment_is_image( $post_id = 0 ) { 
    25752447        $post_id = (int) $post_id; 
    … …  
    25892461} 
    25902462 
    25912463/** 
    2592  * wp_mime_type_icon() - Retrieve the icon for a MIME type 
     2464 * Retrieve the icon for a MIME type. 
    25932465 * 
    25942466 * {@internal Missing Long Description}} 
    25952467 * 
    2596  * @package WordPress 
    2597  * @subpackage Post 
    2598  * @since 2.1 
     2468 * @since 2.1.0 
    25992469 * 
    26002470 * @param string $mime MIME type 
    26012471 * @return string|bool {@internal Missing Description}} 
    … …  
    26792549} 
    26802550 
    26812551/** 
    2682  * wp_check_for_changed_slugs() - {@internal Missing Short Description}} 
     2552 * {@internal Missing Short Description}} 
    26832553 * 
    26842554 * {@internal Missing Long Description}} 
    26852555 * 
    2686  * @package WordPress 
    2687  * @subpackage Post 
    26882556 * @since 2.1 
    26892557 * 
    2690  * @param int $post_id The Post ID 
     2558 * @param int $post_id Post ID. 
    26912559 * @return int Same as $post_id 
    26922560 */ 
    26932561function wp_check_for_changed_slugs($post_id) { 
    … …  
    27182586} 
    27192587 
    27202588/** 
    2721  * get_private_posts_cap_sql() - {@internal Missing Short Description}} 
     2589 * {@internal Missing Short Description}} 
    27222590 * 
    2723  * This function provides a standardized way to appropriately select on 
    2724  * the post_status of posts/pages. The function will return a piece of 
    2725  * SQL code that can be added to a WHERE clause; this SQL is constructed 
    2726  * to allow all published posts, and all private posts to which the user 
    2727  * has access. 
     2591 * This function provides a standardized way to appropriately select on the 
     2592 * post_status of posts/pages. The function will return a piece of SQL code that 
     2593 * can be added to a WHERE clause; this SQL is constructed to allow all 
     2594 * published posts, and all private posts to which the user has access. 
    27282595 * 
    2729  * @package WordPress 
    2730  * @subpackage Post 
    2731  * @since 2.2 
     2596 * @since 2.2.0 
    27322597 * 
    27332598 * @uses $user_ID 
    27342599 * @uses apply_filters() Call 'pub_priv_sql_capability' filter for plugins with different post types 
    … …  
    28592724} 
    28602725 
    28612726/** 
    2862  * update_post_cache() - Updates posts in cache 
     2727 * Updates posts in cache. 
    28632728 * 
    2864  * @usedby update_page_cache() update_page_cache() aliased by this function. 
     2729 * @usedby update_page_cache() Aliased by this function. 
    28652730 * 
    28662731 * @package WordPress 
    28672732 * @subpackage Cache 
    … …  
    28782743} 
    28792744 
    28802745/** 
    2881  * clean_post_cache() - Will clean the post in the cache 
     2746 * Will clean the post in the cache. 
    28822747 * 
    2883  * Cleaning means delete from the cache of the post. Will call to clean 
    2884  * the term object cache associated with the post ID. 
     2748 * Cleaning means delete from the cache of the post. Will call to clean the term 
     2749 * object cache associated with the post ID. 
    28852750 * 
    28862751 * @package WordPress 
    28872752 * @subpackage Cache 
    2888  * @since 2.0 
     2753 * @since 2.0.0 
    28892754 * 
    28902755 * @uses do_action() Will call the 'clean_post_cache' hook action. 
    28912756 * 
    … …  
    29112776} 
    29122777 
    29132778/** 
    2914  * update_page_cache() - Alias of update_post_cache() 
     2779 * Alias of update_post_cache(). 
    29152780 * 
    29162781 * @see update_post_cache() Posts and pages are the same, alias is intentional 
    29172782 * 
    … …  
    29262791} 
    29272792 
    29282793/** 
    2929  * clean_page_cache() - Will clean the page in the cache 
     2794 * Will clean the page in the cache. 
    29302795 * 
    2931  * Clean (read: delete) page from cache that matches $id. Will also clean 
    2932  * cache associated with 'all_page_ids' and 'get_pages'. 
     2796 * Clean (read: delete) page from cache that matches $id. Will also clean cache 
     2797 * associated with 'all_page_ids' and 'get_pages'. 
    29332798 * 
    29342799 * @package WordPress 
    29352800 * @subpackage Cache 
    … …  
    29492814} 
    29502815 
    29512816/** 
    2952  * update_post_caches() - Call major cache updating functions for list of Post objects. 
     2817 * Call major cache updating functions for list of Post objects. 
    29532818 * 
    29542819 * @package WordPress 
    29552820 * @subpackage Cache 
    2956  * @since 1.5 
     2821 * @since 1.5.0 
    29572822 * 
    29582823 * @uses $wpdb 
    29592824 * @uses update_post_cache() 
    … …  
    30802945} 
    30812946 
    30822947/** 
    3083  * _future_post_hook() - Hook used to schedule publication for a post marked for the future. 
     2948 * Hook used to schedule publication for a post marked for the future. 
    30842949 * 
    30852950 * The $post properties used and must exist are 'ID' and 'post_date_gmt'. 
    30862951 * 
    30872952 * @package WordPress 
    30882953 * @subpackage Post 
    3089  * @since 2.3 
     2954 * @since 2.3.0 
    30902955 * 
    30912956 * @param int $post_id Not Used. Can be set to null. 
    30922957 * @param object $post Object type containing the post information 
    … …  
    31322997} 
    31332998 
    31342999/** 
    3135  * _save_post_hook() - Hook used to prevent page/post cache and rewrite rules from staying dirty 
     3000 * Hook used to prevent page/post cache and rewrite rules from staying dirty. 
    31363001 * 
    31373002 * Does two things. If the post is a page and has a template then it will update/add that 
    31383003 * template to the meta. For both pages and posts, it will clean the post cache to make sure 
    … …  
    31433008 * 
    31443009 * @package WordPress 
    31453010 * @subpackage Post 
    3146  * @since 2.3 
     3011 * @since 2.3.0 
    31473012 * 
    31483013 * @uses $wp_rewrite Flushes Rewrite Rules. 
    31493014 * 
    … …  
    31643029// Private 
    31653030// 
    31663031 
     3032/** 
     3033 *  
     3034 * 
     3035 * @param unknown_type $_post 
     3036 */ 
    31673037function _get_post_ancestors(&$_post) { 
    31683038        global $wpdb; 
    31693039 
    … …  
    31833053        } 
    31843054} 
    31853055 
    3186 /* Post Revisions */ 
    3187  
    31883056/** 
    3189  * _wp_post_revision_fields() - determines which fields of posts are to be saved in revisions 
     3057 * Determines which fields of posts are to be saved in revisions. 
    31903058 * 
    3191  * Does two things. If passed a post *array*, it will return a post array ready to be 
    3192  * insterted into the posts table as a post revision. 
    3193  * Otherwise, returns an array whose keys are the post fields to be saved for post revisions. 
     3059 * Does two things. If passed a post *array*, it will return a post array ready 
     3060 * to be insterted into the posts table as a post revision. Otherwise, returns 
     3061 * an array whose keys are the post fields to be saved for post revisions. 
    31943062 * 
    31953063 * @package WordPress 
    3196  * @subpackage Post Revisions 
    3197  * @since 2.6 
     3064 * @subpackage Post_Revisions 
     3065 * @since 2.6.0 
     3066 * @access private 
    31983067 * 
    3199  * @param array $post optional a post array to be processed for insertion as a post revision 
     3068 * @param array $post Optional a post array to be processed for insertion as a post revision. 
    32003069 * @param bool $autosave optional Is the revision an autosave? 
    3201  * @return array post array ready to be inserted as a post revision or array of fields that can be versioned 
     3070 * @return array Post array ready to be inserted as a post revision or array of fields that can be versioned. 
    32023071 */ 
    32033072function _wp_post_revision_fields( $post = null, $autosave = false ) { 
    32043073        static $fields = false; 
    … …  
    32373106} 
    32383107 
    32393108/** 
    3240  * wp_save_post_revision() - Saves an already existing post as a post revision.  Typically used immediately prior to post updates. 
     3109 * Saves an already existing post as a post revision. 
    32413110 * 
     3111 * Typically used immediately prior to post updates. 
     3112 * 
    32423113 * @package WordPress 
    3243  * @subpackage Post Revisions 
    3244  * @since 2.6 
     3114 * @subpackage Post_Revisions 
     3115 * @since 2.6.0 
    32453116 * 
    32463117 * @uses _wp_put_post_revision() 
    32473118 * 
    3248  * @param int $post_id The ID of the post to save as a revision 
    3249  * @return mixed null or 0 if error, new revision ID if success 
     3119 * @param int $post_id The ID of the post to save as a revision. 
     3120 * @return mixed Null or 0 if error, new revision ID, if success. 
    32503121 */ 
    32513122function wp_save_post_revision( $post_id ) { 
    32523123        // We do autosaves manually with wp_create_post_autosave() 
    … …  
    32903161} 
    32913162 
    32923163/** 
    3293  * wp_get_post_autosave() - returns the autosaved data of the specified post. 
     3164 * Retrieve the autosaved data of the specified post. 
    32943165 * 
    3295  * Returns a post object containing the information that was autosaved for the specified post. 
     3166 * Returns a post object containing the information that was autosaved for the 
     3167 * specified post. 
    32963168 * 
    32973169 * @package WordPress 
    3298  * @subpackage Post Revisions 
    3299  * @since 2.6 
     3170 * @subpackage Post_Revisions 
     3171 * @since 2.6.0 
    33003172 * 
    3301  * @param int $post_id The post ID 
    3302  * @return object|bool the autosaved data or false on failure or when no autosave exists 
     3173 * @param int $post_id The post ID. 
     3174 * @return object|bool The autosaved data or false on failure or when no autosave exists. 
    33033175 */ 
    33043176function wp_get_post_autosave( $post_id ) { 
    33053177        global $wpdb; 
    … …  
    33263198        return false; 
    33273199} 
    33283200 
    3329 // Internally used to hack WP_Query into submission 
     3201/** 
     3202 * Internally used to hack WP_Query into submission. 
     3203 * 
     3204 * @package WordPress 
     3205 * @subpackage Post_Revisions 
     3206 * @since 2.6.0 
     3207 * 
     3208 * @param object $query WP_Query object 
     3209 */ 
    33303210function _wp_get_post_autosave_hack( $query ) { 
    33313211        $query->is_single = false; 
    33323212} 
    33333213 
    3334  
    33353214/** 
    3336  * wp_is_post_revision() - Determines if the specified post is a revision. 
     3215 * Determines if the specified post is a revision. 
    33373216 * 
    33383217 * @package WordPress 
    3339  * @subpackage Post Revisions 
    3340  * @since 2.6 
     3218 * @subpackage Post_Revisions 
     3219 * @since 2.6.0 
    33413220 * 
    3342  * @param int|object $post post ID or post object 
    3343  * @return bool|int false if not a revision, ID of revision's parent otherwise 
     3221 * @param int|object $post Post ID or post object. 
     3222 * @return bool|int False if not a revision, ID of revision's parent otherwise. 
    33443223 */ 
    33453224function wp_is_post_revision( $post ) { 
    33463225        if ( !$post = wp_get_post_revision( $post ) ) 
    … …  
    33493228} 
    33503229 
    33513230/** 
    3352  * wp_is_post_autosave() - Determines if the specified post is an autosave. 
     3231 * Determines if the specified post is an autosave. 
    33533232 * 
    33543233 * @package WordPress 
    3355  * @subpackage Post Revisions 
    3356  * @since 2.6 
     3234 * @subpackage Post_Revisions 
     3235 * @since 2.6.0 
    33573236 * 
    3358  * @param int|object $post post ID or post object 
    3359  * @return bool|int false if not a revision, ID of autosave's parent otherwise 
     3237 * @param int|object $post Post ID or post object. 
     3238 * @return bool|int False if not a revision, ID of autosave's parent otherwise 
    33603239 */ 
    33613240function wp_is_post_autosave( $post ) { 
    33623241        if ( !$post = wp_get_post_revision( $post ) ) 
    … …  
    33673246} 
    33683247 
    33693248/** 
    3370  * _wp_put_post_revision() - Inserts post data into the posts table as a post revision 
     3249 * Inserts post data into the posts table as a post revision. 
    33713250 * 
    33723251 * @package WordPress 
    3373  * @subpackage Post Revisions 
    3374  * @since 2.6 
     3252 * @subpackage Post_Revisions 
     3253 * @since 2.6.0 
    33753254 * 
    33763255 * @uses wp_insert_post() 
    33773256 * 
    3378  * @param int|object|array $post post ID, post object OR post array 
    3379  * @param bool $autosave optional Is the revision an autosave? 
    3380  * @return mixed null or 0 if error, new revision ID if success 
     3257 * @param int|object|array $post Post ID, post object OR post array. 
     3258 * @param bool $autosave Optional. Is the revision an autosave? 
     3259 * @return mixed Null or 0 if error, new revision ID if success. 
    33813260 */ 
    33823261function _wp_put_post_revision( $post = null, $autosave = false ) { 
    33833262        if ( is_object($post) ) 
    … …  
    34023281} 
    34033282 
    34043283/** 
    3405  * wp_get_post_revision() - Gets a post revision 
     3284 * Gets a post revision. 
    34063285 * 
    34073286 * @package WordPress 
    3408  * @subpackage Post Revisions 
    3409  * @since 2.6 
     3287 * @subpackage Post_Revisions 
     3288 * @since 2.6.0 
    34103289 * 
    34113290 * @uses get_post() 
    34123291 * 
    3413  * @param int|object $post post ID or post object 
    3414  * @param $output optional OBJECT, ARRAY_A, or ARRAY_N 
    3415  * @param string $filter optional sanitation filter.  @see sanitize_post() 
    3416  * @return mixed null if error or post object if success 
     3292 * @param int|object $post Post ID or post object 
     3293 * @param string $output Optional. OBJECT, ARRAY_A, or ARRAY_N. 
     3294 * @param string $filter Optional sanitation filter.  @see sanitize_post() 
     3295 * @return mixed Null if error or post object if success 
    34173296 */ 
    34183297function &wp_get_post_revision(&$post, $output = OBJECT, $filter = 'raw') { 
    34193298        $null = null; 
    … …  
    34363315} 
    34373316 
    34383317/** 
    3439  * wp_restore_post_revision() - Restores a post to the specified revision 
     3318 * Restores a post to the specified revision. 
    34403319 * 
    3441  * Can restore a past using all fields of the post revision, or only selected fields. 
     3320 * Can restore a past using all fields of the post revision, or only selected 
     3321 * fields. 
    34423322 * 
    34433323 * @package WordPress 
    3444  * @subpackage Post Revisions 
    3445  * @since 2.6 
     3324 * @subpackage Post_Revisions 
     3325 * @since 2.6.0 
    34463326 * 
    34473327 * @uses wp_get_post_revision() 
    34483328 * @uses wp_update_post() 
    34493329 * 
    3450  * @param int|object $revision_id revision ID or revision object 
    3451  * @param array $fields optional What fields to restore from.  Defaults to all. 
    3452  * @return mixed null if error, false if no fields to restore, (int) post ID if success 
     3330 * @param int|object $revision_id Revision ID or revision object. 
     3331 * @param array $fields Optional. What fields to restore from.  Defaults to all. 
     3332 * @return mixed Null if error, false if no fields to restore, (int) post ID if success. 
    34533333 */ 
    34543334function wp_restore_post_revision( $revision_id, $fields = null ) { 
    34553335        if ( !$revision = wp_get_post_revision( $revision_id, ARRAY_A ) ) 
    … …  
    34783358} 
    34793359 
    34803360/** 
    3481  * wp_delete_post_revision() - Deletes a revision. 
     3361 * Deletes a revision. 
    34823362 * 
    3483  * Deletes the row from the posts table corresponding to the specified revision 
     3363 * Deletes the row from the posts table corresponding to the specified revision. 
    34843364 * 
    34853365 * @package WordPress 
    3486  * @subpackage Post Revisions 
    3487  * @since 2.6 
     3366 * @subpackage Post_Revisions 
     3367 * @since 2.6.0 
    34883368 * 
    34893369 * @uses wp_get_post_revision() 
    34903370 * @uses wp_delete_post() 
    34913371 * 
    3492  * @param int|object $revision_id revision ID or revision object 
    3493  * @param array $fields optional What fields to restore from.  Defaults to all. 
    3494  * @return mixed null if error, false if no fields to restore, (int) post ID if success 
     3372 * @param int|object $revision_id Revision ID or revision object. 
     3373 * @param array $fields Optional. What fields to restore from.  Defaults to all. 
     3374 * @return mixed Null if error, false if no fields to restore, (int) post ID if success. 
    34953375 */ 
    34963376function wp_delete_post_revision( $revision_id ) { 
    34973377        if ( !$revision = wp_get_post_revision( $revision_id ) ) 
    … …  
    35083388} 
    35093389 
    35103390/** 
    3511  * wp_get_post_revisions() - Returns all revisions of specified post 
     3391 * Returns all revisions of specified post. 
    35123392 * 
    35133393 * @package WordPress 
    3514  * @subpackage Post Revisions 
    3515  * @since 2.6 
     3394 * @subpackage Post_Revisions 
     3395 * @since 2.6.0 
    35163396 * 
    35173397 * @uses get_children() 
    35183398 * 
    3519  * @param int|object $post_id post ID or post object 
     3399 * @param int|object $post_id Post ID or post object 
    35203400 * @return array empty if no revisions 
    35213401 */ 
    35223402function wp_get_post_revisions( $post_id = 0, $args = null ) {