WordPress.org
Get WordPress

Make WordPress Core

Ticket #7538: post.phpdoc.r8662.diff

File post.phpdoc.r8662.diff, 55.5 KB (added by jacobsantos, 17 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 ) {