Make WordPress Core

Ticket #7538: 7538.r8665.diff

File 7538.r8665.diff, 68.7 KB (added by santosj, 16 years ago)

Completed post.php phpdoc inline documentation based off of 8665.

  • 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 *
    450  * {@internal Missing Long Description}}
     425 * The defaults are as follows:
     426 *     'numberposts' - Default is 5. Total number of posts to retrieve.
     427 *     'offset' - Default is 0. See {@link WP_Query::query()} for more.
     428 *     'category' - What category to pull the posts from.
     429 *     'orderby' - Default is 'post_date'. How to order the posts.
     430 *     'order' - Default is 'DESC'. The order to retrieve the posts.
     431 *     'include' - See {@link WP_Query::query()} for more.
     432 *     'exclude' - See {@link WP_Query::query()} for more.
     433 *     'meta_key' - See {@link WP_Query::query()} for more.
     434 *     'meta_value' - See {@link WP_Query::query()} for more.
     435 *     'post_type' - Default is 'post'. Can be 'page', or 'attachment' to name a few.
     436 *     'post_parent' - The parent of the post or post type.
     437 *     'post_status' - Default is 'published'. Post status to retrieve.
    451438 *
    452  * @package WordPress
    453  * @subpackage Post
    454  * @since 1.2
     439 * @since 1.2.0
    455440 * @uses $wpdb
     441 * @uses WP_Query::query() See for more default arguments and information.
    456442 * @link http://codex.wordpress.org/Template_Tags/get_posts
    457443 *
    458  * @param array $args {@internal Missing Description}}
    459  * @return array {@internal Missing Description}}
     444 * @param array $args Optional. Override defaults.
     445 * @return array List of posts.
    460446 */
    461447function get_posts($args = null) {
    462448        $defaults = array(
     
    494480//
    495481
    496482/**
    497  * add_post_meta() - adds metadata for post
     483 * Add meta data field to a post.
    498484 *
    499  * {@internal Missing Long Description}}
     485 * Post meta data is called "Custom Fields" on the Administration Panels.
    500486 *
    501  * @package WordPress
    502  * @subpackage Post
    503  * @since 1.5
     487 * @since 1.5.0
    504488 * @uses $wpdb
    505489 * @link http://codex.wordpress.org/Function_Reference/add_post_meta
    506490 *
    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}}
     491 * @param int $post_id Post ID.
     492 * @param string $key Metadata name.
     493 * @param mixed $value Metadata value.
     494 * @param bool $unique Optional, default is false. Whether the same key should not be added.
     495 * @return bool False for failure. True for success.
    512496 */
    513497function add_post_meta($post_id, $meta_key, $meta_value, $unique = false) {
    514498        global $wpdb;
     
    533517}
    534518
    535519/**
    536  * delete_post_meta() - delete post metadata
     520 * Remove metadata matching criteria from a post.
    537521 *
    538  * {@internal Missing Long Description}}
     522 * You can match based on the key, or key and value. Removing based on key and
     523 * value, will keep from removing duplicate metadata with the same key. It also
     524 * allows removing all metadata matching key, if needed.
    539525 *
    540  * @package WordPress
    541  * @subpackage Post
    542  * @since 1.5
     526 * @since 1.5.0
    543527 * @uses $wpdb
    544528 * @link http://codex.wordpress.org/Function_Reference/delete_post_meta
    545529 *
    546530 * @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}}
     531 * @param string $key Metadata name.
     532 * @param mixed $value Optional. Metadata value.
     533 * @return bool False for failure. True for success.
    550534 */
    551535function delete_post_meta($post_id, $key, $value = '') {
    552536        global $wpdb;
     
    576560}
    577561
    578562/**
    579  * get_post_meta() - Get a post meta field
     563 * Retrieve post meta field for a post.
    580564 *
    581  * {@internal Missing Long Description}}
    582  *
    583  * @package WordPress
    584  * @subpackage Post
    585  * @since 1.5
     565 * @since 1.5.0
    586566 * @uses $wpdb
    587567 * @link http://codex.wordpress.org/Function_Reference/get_post_meta
    588568 *
    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}}
     569 * @param int $post_id Post ID.
     570 * @param string $key The meta key to retrieve.
     571 * @param bool $single Whether to return a single value.
     572 * @return mixed Will be an array if $single is false. Will be value of meta data field if $single is true.
    593573 */
    594574function get_post_meta($post_id, $key, $single = false) {
    595575        $post_id = (int) $post_id;
     
    620600}
    621601
    622602/**
    623  * update_post_meta() - Update a post meta field
     603 * Update post meta field based on post ID.
    624604 *
    625  * {@internal Missing Long Description}}
     605 * Use the $prev_value parameter to differentiate between meta fields with the
     606 * same key and post ID.
    626607 *
    627  * @package WordPress
    628  * @subpackage Post
     608 * If the meta field for the post does not exist, it will be added.
     609 *
    629610 * @since 1.5
    630611 * @uses $wpdb
    631612 * @link http://codex.wordpress.org/Function_Reference/update_post_meta
    632613 *
    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}}
     614 * @param int $post_id Post ID.
     615 * @param string $key Metadata key.
     616 * @param mixed $value Metadata value.
     617 * @param mixed $prev_value Optional. Previous value to check before removing.
     618 * @return bool False on failure, true if success.
    638619 */
    639620function update_post_meta($post_id, $meta_key, $meta_value, $prev_value = '') {
    640621        global $wpdb;
     
    662643}
    663644
    664645/**
    665  * delete_post_meta_by_key() - Delete everything from post meta matching $post_meta_key
     646 * Delete everything from post meta matching meta key.
    666647 *
    667  * @package WordPress
    668  * @subpackage Post
    669  * @since 2.3
     648 * @since 2.3.0
    670649 * @uses $wpdb
    671650 *
    672  * @param string $post_meta_key What to search for when deleting
     651 * @param string $post_meta_key Key to search for when deleting.
    673652 * @return bool Whether the post meta key was deleted from the database
    674653 */
    675654function delete_post_meta_by_key($post_meta_key) {
     
    683662}
    684663
    685664/**
    686  * get_post_custom() - Retrieve post custom fields
     665 * Retrieve post meta fields, based on post ID.
    687666 *
    688  * {@internal Missing Long Description}}
     667 * The post meta fields are retrieved from the cache, so the function is
     668 * optimized to be called more than once. It also applies to the functions, that
     669 * use this function.
    689670 *
    690  * @package WordPress
    691  * @subpackage Post
    692  * @since 1.2
     671 * @since 1.2.0
    693672 * @link http://codex.wordpress.org/Function_Reference/get_post_custom
    694673 *
    695  * @uses $id
    696  * @uses $wpdb
     674 * @uses $id Current Loop Post ID
    697675 *
    698676 * @param int $post_id post ID
    699  * @return array {@internal Missing Description}}
     677 * @return array
    700678 */
    701679function get_post_custom($post_id = 0) {
    702680        global $id;
     
    713691}
    714692
    715693/**
    716  * get_post_custom_keys() - Retrieve post custom field names
     694 * Retrieve meta field names for a post.
    717695 *
    718  * @package WordPress
    719  * @subpackage Post
    720  * @since 1.2
     696 * If there are no meta fields, then nothing (null) will be returned.
     697 *
     698 * @since 1.2.0
    721699 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_keys
    722700 *
    723701 * @param int $post_id post ID
    724  * @return array|null Either array of the keys, or null if keys would not be retrieved
     702 * @return array|null Either array of the keys, or null if keys could not be retrieved.
    725703 */
    726704function get_post_custom_keys( $post_id = 0 ) {
    727705        $custom = get_post_custom( $post_id );
     
    734712}
    735713
    736714/**
    737  * get_post_custom_values() - Retrieve values for a custom post field
     715 * Retrieve values for a custom post field.
    738716 *
    739  * @package WordPress
    740  * @subpackage Post
    741  * @since 1.2
     717 * The parameters must not be considered optional. All of the post meta fields
     718 * will be retrieved and only the meta field key values returned.
     719 *
     720 * @since 1.2.0
    742721 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_values
    743722 *
    744  * @param string $key field name
    745  * @param int $post_id post ID
    746  * @return mixed {@internal Missing Description}}
     723 * @param string $key Meta field key.
     724 * @param int $post_id Post ID
     725 * @return array Meta field values.
    747726 */
    748727function get_post_custom_values( $key = '', $post_id = 0 ) {
    749728        $custom = get_post_custom($post_id);
     
    752731}
    753732
    754733/**
    755  * is_sticky() - Check if post is sticky
     734 * Check if post is sticky.
    756735 *
    757  * {@internal Missing Long Description}}
     736 * Sticky posts should remain at the top of The Loop. If the post ID is not
     737 * given, then The Loop ID for the current post will be used.
    758738 *
    759  * @package WordPress
    760  * @subpackage Post
    761  * @since 2.7
     739 * @since 2.7.0
    762740 *
    763  * @param int $post_id A post ID
    764  * @return bool
     741 * @param int $post_id Optional. Post ID.
     742 * @return bool Whether post is sticky (true) or not sticky (false).
    765743 */
    766744function is_sticky($post_id = null) {
    767745        global $id;
     
    782760        return false;
    783761}
    784762
    785 
    786763/**
    787  * sanitize_post() - Sanitize every post field
     764 * Sanitize every post field.
    788765 *
    789  * {@internal Missing Long Description}}
     766 * If the context is 'raw', then the post object or array will just be returned.
    790767 *
    791  * @package WordPress
    792  * @subpackage Post
    793  * @since 2.3
     768 * @since 2.3.0
     769 * @uses sanitize_post_field() Used to sanitize the fields.
    794770 *
    795771 * @param object|array $post The Post Object or Array
    796  * @param string $context How to sanitize post fields
     772 * @param string $context Optional, default is 'display'. How to sanitize post fields.
    797773 * @return object|array The now sanitized Post Object or Array (will be the same type as $post)
    798774 */
    799775function sanitize_post($post, $context = 'display') {
     
    810786}
    811787
    812788/**
    813  * sanitize_post_field() - Sanitize post field based on context
     789 * Sanitize post field based on context.
    814790 *
    815  * {@internal Missing Long Description}}
     791 * Possible context values are: raw, edit, db, attribute, js, and display. The
     792 * display context is used by default.
    816793 *
    817  * @package WordPress
    818  * @subpackage Post
    819  * @since 2.3
     794 * @since 2.3.0
    820795 *
    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
     796 * @param string $field The Post Object field name.
     797 * @param mixed $value The Post Object value.
     798 * @param int $post_id Post ID.
     799 * @param string $context How to sanitize post fields.
     800 * @return mixed Sanitized value.
    826801 */
    827802function sanitize_post_field($field, $value, $post_id, $context) {
    828803        $int_fields = array('ID', 'post_parent', 'menu_order');
     
    882857}
    883858
    884859/**
    885  * Make a post sticky
     860 * Make a post sticky.
    886861 *
    887  * Makes a post stick to the top of the front page
     862 * Sticky posts should be displayed at the top of the front page.
    888863 *
    889  * @package WordPress
    890  * @subpackage Post
    891  * @since 2.7
     864 * @since 2.7.0
    892865 *
    893  * @param int $post_id A post ID
     866 * @param int $post_id Post ID.
    894867 */
    895868function stick_post($post_id) {
    896869        $stickies = get_option('sticky_posts');
     
    905878}
    906879
    907880/**
    908  * Unstick a post
     881 * Unstick a post.
    909882 *
    910  * Unstick a post from the front page
     883 * Sticky posts should be displayed at the top of the front page.
    911884 *
    912  * @package WordPress
    913  * @subpackage Post
    914  * @since 2.7
     885 * @since 2.7.0
    915886 *
    916  * @param int $post_id A post ID
     887 * @param int $post_id Post ID.
    917888 */
    918889function unstick_post($post_id) {
    919890        $stickies = get_option('sticky_posts');
     
    944915 * The $perm parameter checks for 'readable' value and if the user can read
    945916 * private posts, it will display that for the user that is signed in.
    946917 *
    947  * @package WordPress
    948  * @subpackage Post
    949  * @since 2.5
     918 * @since 2.5.0
    950919 * @link http://codex.wordpress.org/Template_Tags/wp_count_posts
    951920 *
    952921 * @param string $type Optional. Post type to retrieve count
     
    988957
    989958
    990959/**
    991  * wp_count_attachments() - Count number of attachments
     960 * Count number of attachments for the mime type(s).
    992961 *
    993  * {@internal Missing Long Description}}
     962 * If you set the optional mime_type parameter, then an array will still be
     963 * returned, but will only have the item you are looking for. It does not give
     964 * you the number of attachments that are children of a post. You can get that
     965 * by counting the number of children that post has.
    994966 *
    995  * @package WordPress
    996  * @subpackage Post
    997  * @since 2.5
     967 * @since 2.5.0
    998968 *
    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
     969 * @param string|array $mime_type Optional. Array or comma-separated list of MIME patterns.
     970 * @return array Number of posts for each mime type.
    1001971 */
    1002 
    1003972function wp_count_attachments( $mime_type = '' ) {
    1004973        global $wpdb;
    1005974
     
    1015984}
    1016985
    1017986/**
    1018  * wp_match_mime_type() - Check a MIME-Type against a list
     987 * Check a MIME-Type against a list.
    1019988 *
    1020  * {@internal Missing Long Description}}
     989 * If the wildcard_mime_types parameter is a string, it must be comma separated
     990 * list. If the real_mime_types is a string, it is also comma separated to
     991 * create the list.
    1021992 *
    1022  * @package WordPress
    1023  * @subpackage Post
    1024  * @since 2.5
     993 * @since 2.5.0
    1025994 *
    1026995 * @param string|array $wildcard_mime_types e.g. audio/mpeg or image (same as image/*) or flash (same as *flash*)
    1027996 * @param string|array $real_mime_types post_mime_type values
     
    10521021}
    10531022
    10541023/**
    1055  * wp_get_post_mime_type_where() - Convert MIME types into SQL
     1024 * Convert MIME types into SQL.
    10561025 *
    1057  * @package WordPress
    1058  * @subpackage Post
    1059  * @since 2.5
     1026 * @since 2.5.0
    10601027 *
    1061  * @param string|array $mime_types MIME types
    1062  * @return string SQL AND clause
     1028 * @param string|array $mime_types List of mime types or comma separated string of mime types.
     1029 * @return string The SQL AND clause for mime searching.
    10631030 */
    10641031function wp_post_mime_type_where($post_mime_types) {
    10651032        $where = '';
     
    10991066}
    11001067
    11011068/**
    1102  * wp_delete_post() - Deletes a Post
     1069 * Removes a post, attachment, or page.
    11031070 *
    1104  * {@internal Missing Long Description}}
     1071 * When the post and page goes, everything that is tied to it is deleted also.
     1072 * This includes comments, post meta fields, and terms associated with the post.
    11051073 *
    1106  * @package WordPress
    1107  * @subpackage Post
    11081074 * @since 1.0.0
     1075 * @uses do_action() Calls 'deleted_post' hook on post ID.
    11091076 *
    1110  * @param int $postid post ID
    1111  * @return mixed {@internal Missing Description}}
     1077 * @param int $postid Post ID.
     1078 * @return mixed
    11121079 */
    11131080function wp_delete_post($postid = 0) {
    11141081        global $wpdb, $wp_rewrite;
     
    11771144}
    11781145
    11791146/**
    1180  * wp_get_post_categories() - Retrieve the list of categories for a post
     1147 * Retrieve the list of categories for a post.
    11811148 *
    11821149 * Compatibility layer for themes and plugins. Also an easy layer of abstraction
    11831150 * away from the complexity of the taxonomy layer.
    11841151 *
    1185  * @package WordPress
    1186  * @subpackage Post
    1187  * @since 2.1
     1152 * @since 2.1.0
    11881153 *
    1189  * @uses wp_get_object_terms() Retrieves the categories. Args details can be found here
     1154 * @uses wp_get_object_terms() Retrieves the categories. Args details can be found here.
    11901155 *
    1191  * @param int $post_id Optional. The Post ID
    1192  * @param array $args Optional. Overwrite the defaults
    1193  * @return array {@internal Missing Description}}
     1156 * @param int $post_id Optional. The Post ID.
     1157 * @param array $args Optional. Overwrite the defaults.
     1158 * @return array
    11941159 */
    11951160function wp_get_post_categories( $post_id = 0, $args = array() ) {
    11961161        $post_id = (int) $post_id;
     
    12031168}
    12041169
    12051170/**
    1206  * wp_get_post_tags() - Retrieve the post tags
     1171 * Retrieve the tags for a post.
    12071172 *
     1173 * There is only one default for this function, called 'fields' and by default
     1174 * is set to 'all'. There are other defaults that can be override in
     1175 * {@link wp_get_object_terms()}.
     1176 *
    12081177 * @package WordPress
    12091178 * @subpackage Post
    1210  * @since 2.3
     1179 * @since 2.3.0
    12111180 *
    12121181 * @uses wp_get_object_terms() Gets the tags for returning. Args can be found here
    12131182 *
    12141183 * @param int $post_id Optional. The Post ID
    12151184 * @param array $args Optional. Overwrite the defaults
    1216  * @return mixed The tags the post has currently
     1185 * @return array List of post tags.
    12171186 */
    12181187function wp_get_post_tags( $post_id = 0, $args = array() ) {
    12191188        $post_id = (int) $post_id;
     
    12271196}
    12281197
    12291198/**
    1230  * wp_get_recent_posts() - Get the $num most recent posts
     1199 * Retrieve number of recent posts.
    12311200 *
    1232  * {@internal Missing Long Description}}
    1233  *
    1234  * @package WordPress
    1235  * @subpackage Post
    12361201 * @since 1.0.0
     1202 * @uses $wpdb
    12371203 *
    1238  * @param int $num number of posts to get
    1239  * @return array {@internal Missing Description}}
     1204 * @param int $num Optional, default is 10. Number of posts to get.
     1205 * @return array List of posts.
    12401206 */
    12411207function wp_get_recent_posts($num = 10) {
    12421208        global $wpdb;
     
    12501216        $sql = "SELECT * FROM $wpdb->posts WHERE post_type = 'post' ORDER BY post_date DESC $limit";
    12511217        $result = $wpdb->get_results($sql,ARRAY_A);
    12521218
    1253         return $result?$result:array();
     1219        return $result ? $result : array();
    12541220}
    12551221
    12561222/**
    1257  * wp_get_single_post() - Get one post
     1223 * Retrieve a single post, based on post ID.
    12581224 *
    1259  * {@internal Missing Long Description}}
     1225 * Has categories in 'post_category' property or key. Has tags in 'tags_input'
     1226 * property or key.
    12601227 *
    1261  * @package WordPress
    1262  * @subpackage Post
    12631228 * @since 1.0.0
    1264  * @uses $wpdb
    12651229 *
    1266  * @param int $postid post ID
    1267  * @param string $mode How to return result, either OBJECT, ARRAY_N, or ARRAY_A
     1230 * @param int $postid Post ID.
     1231 * @param string $mode How to return result, either OBJECT, ARRAY_N, or ARRAY_A.
    12681232 * @return object|array Post object or array holding post contents and information
    12691233 */
    12701234function wp_get_single_post($postid = 0, $mode = OBJECT) {
     
    12861250}
    12871251
    12881252/**
    1289  * wp_insert_post() - Insert a post
     1253 * Insert a post.
    12901254 *
    1291  * {@internal Missing Long Description}}
     1255 * If the $postarr parameter has 'ID' set to a value, then post will be updated.
    12921256 *
    1293  * @package WordPress
    1294  * @subpackage Post
    1295  * @since 1.0.0
     1257 * You can set the post date manually, but setting the values for 'post_date'
     1258 * and 'post_date_gmt' keys. You can close the comments or open the comments by
     1259 * setting the value for 'comment_status' key.
    12961260 *
     1261 * The defaults for the parameter $postarr are:
     1262 *     'post_status' - Default is 'draft'.
     1263 *     'post_type' - Default is 'post'.
     1264 *     'post_author' - Default is current user ID. The ID of the user, who added
     1265 *         the post.
     1266 *     'ping_status' - Default is the value in default ping status option.
     1267 *         Whether the attachment can accept pings.
     1268 *     'post_parent' - Default is 0. Set this for the post it belongs to, if
     1269 *         any.
     1270 *     'menu_order' - Default is 0. The order it is displayed.
     1271 *     'to_ping' - Whether to ping.
     1272 *     'pinged' - Default is empty string.
     1273 *     'post_password' - Default is empty string. The password to access the
     1274 *         attachment.
     1275 *     'guid' - Global Unique ID for referencing the attachment.
     1276 *     'post_content_filtered' - Post content filtered.
     1277 *     'post_excerpt' - Post excerpt.
     1278 *
     1279 * @since 1.0.0
    12971280 * @uses $wpdb
    12981281 * @uses $wp_rewrite
    12991282 * @uses $user_ID
    1300  * @uses $allowedtags
    13011283 *
    1302  * @param array $postarr post contents
    1303  * @return int post ID or 0 on error
     1284 * @param array $postarr Optional. Override defaults.
     1285 * @param bool $wp_error Optional. Allow return of WP_Error on failure.
     1286 * @return int|WP_Error The value 0 or WP_Error on failure. The post ID on success.
    13041287 */
    13051288function wp_insert_post($postarr = array(), $wp_error = false) {
    13061289        global $wpdb, $wp_rewrite, $user_ID;
     
    15071490}
    15081491
    15091492/**
    1510  * wp_update_post() - Update a post
     1493 * Update a post with new post data.
    15111494 *
    1512  * {@internal Missing Long Description}}
     1495 * The date does not have to be set for drafts. You can set the date and it will
     1496 * not be overridden.
    15131497 *
    1514  * @package WordPress
    1515  * @subpackage Post
    15161498 * @since 1.0.0
    1517  * @uses $wpdb
    15181499 *
    1519  * @param array $postarr post data
    1520  * @return int {@internal Missing Description}}
     1500 * @param array|object $postarr Post data.
     1501 * @return int 0 on failure, Post ID on success.
    15211502 */
    15221503function wp_update_post($postarr = array()) {
    15231504        if ( is_object($postarr) )
     
    15581539}
    15591540
    15601541/**
    1561  * wp_publish_post() - Mark a post as "published"
     1542 * Publish a post by transitioning the post status.
    15621543 *
    1563  * {@internal Missing Long Description}}
    1564  *
    1565  * @package WordPress
    1566  * @subpackage Post
    1567  * @since 2.1
     1544 * @since 2.1.0
    15681545 * @uses $wpdb
     1546 * @uses do_action() Calls 'edit_post', 'save_post', and 'wp_insert_post' on post_id and post data.
    15691547 *
    1570  * @param int $post_id Post ID
    1571  * @return int|null {@internal Missing Description}}
     1548 * @param int $post_id Post ID.
     1549 * @return null
    15721550 */
    15731551function wp_publish_post($post_id) {
    15741552        global $wpdb;
     
    15991577}
    16001578
    16011579/**
    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.
     1580 * Publish future post and make sure post ID has future post status.
    16051581 *
    1606  * {@internal Missing Long Description}}
     1582 * Invoked by cron 'publish_future_post' event. This safeguard prevents cron
     1583 * from publishing drafts, etc.
    16071584 *
    1608  * @package WordPress
    1609  * @subpackage Post
    1610  * @since 2.5
    1611  * @uses $wpdb
     1585 * @since 2.5.0
    16121586 *
    1613  * @param int $post_id Post ID
    1614  * @return int|null {@internal Missing Description}}
     1587 * @param int $post_id Post ID.
     1588 * @return null Nothing is returned. Which can mean that no action is required or post was published.
    16151589 */
    16161590function check_and_publish_future_post($post_id) {
    16171591
     
    16271601}
    16281602
    16291603/**
    1630  * wp_add_post_tags() - Adds the tags to a post
     1604 * Adds tags to a post.
    16311605 *
    1632  * @uses wp_set_post_tags() Same first two paraeters, but the last parameter is always set to true.
     1606 * @uses wp_set_post_tags() Same first two parameters, but the last parameter is always set to true.
    16331607 *
    16341608 * @package WordPress
    16351609 * @subpackage Post
    1636  * @since 2.3
     1610 * @since 2.3.0
    16371611 *
    1638  * @param int $post_id Optional. Post ID
    1639  * @param string $tags The tags to set for the post
     1612 * @param int $post_id Post ID
     1613 * @param string $tags The tags to set for the post, separated by commas.
    16401614 * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise
    16411615 */
    16421616function wp_add_post_tags($post_id = 0, $tags = '') {
    16431617        return wp_set_post_tags($post_id, $tags, true);
    16441618}
    16451619
     1620
    16461621/**
    1647  * wp_set_post_tags() - Set the tags for a post
     1622 * Set the tags for a post.
    16481623 *
    1649  * {@internal Missing Long Description}}
     1624 * @since 2.3.0
     1625 * @uses wp_set_object_terms() Sets the tags for the post.
    16501626 *
    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
     1627 * @param int $post_id Post ID.
     1628 * @param string $tags The tags to set for the post, separated by commas.
    16581629 * @param bool $append If true, don't delete existing tags, just add on. If false, replace the tags with the new tags.
    16591630 * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise
    16601631 */
     
    16721643}
    16731644
    16741645/**
    1675  * wp_set_post_categories() - Set categories for a post
     1646 * Set categories for a post.
    16761647 *
    1677  * {@internal Missing Long Description}}
     1648 * If the post categories parameter is not set, then the default category is
     1649 * going used.
    16781650 *
    1679  * @package WordPress
    1680  * @subpackage Post
    1681  * @since 2.1
    1682  * @uses $wpdb
     1651 * @since 2.1.0
    16831652 *
    1684  * @param int $post_ID post ID
    1685  * @param array $post_categories
    1686  * @return bool|mixed {@internal Missing Description}}
     1653 * @param int $post_ID Post ID.
     1654 * @param array $post_categories Optional. List of categories.
     1655 * @return bool|mixed
    16871656 */
    16881657function wp_set_post_categories($post_ID = 0, $post_categories = array()) {
    16891658        $post_ID = (int) $post_ID;
     
    16971666        $post_categories = array_unique($post_categories);
    16981667
    16991668        return wp_set_object_terms($post_ID, $post_categories, 'category');
    1700 }       // wp_set_post_categories()
     1669}
    17011670
    17021671/**
    1703  * wp_transition_post_status() - Change the post transition status
     1672 * Transition the post status of a post.
    17041673 *
    1705  * {@internal Missing Long Description}}
     1674 * Calls hooks to transition post status. If the new post status is not the same
     1675 * as the previous post status, then two hooks will be ran, the first is
     1676 * 'transition_post_status' with new status, old status, and post data. The
     1677 * next action called is 'OLDSTATUS_to_NEWSTATUS' the NEWSTATUS is the
     1678 * $new_status parameter and the OLDSTATUS is $old_status parameter; it has the
     1679 * post data.
    17061680 *
    1707  * @package WordPress
    1708  * @subpackage Post
    1709  * @since 2.3
     1681 * The final action will run whether or not the post statuses are the same. The
     1682 * action is named 'NEWSTATUS_POSTTYPE', NEWSTATUS is from the $new_status
     1683 * parameter and POSTTYPE is post_type post data.
    17101684 *
    1711  * @param string $new_status {@internal Missing Description}}
    1712  * @param string $old_status {@internal Missing Description}}
    1713  * @param int $post {@internal Missing Description}}
     1685 * @since 2.3.0
     1686 *
     1687 * @param string $new_status Transition to this post status.
     1688 * @param string $old_status Previous post status.
     1689 * @param object $post Post data.
    17141690 */
    17151691function wp_transition_post_status($new_status, $old_status, $post) {
    17161692        if ( $new_status != $old_status ) {
     
    17251701//
    17261702
    17271703/**
    1728  * add_ping() - Add a URL to those already pung
     1704 * Add a URL to those already pung.
    17291705 *
    1730  * {@internal Missing Long Description}}
    1731  *
    1732  * @package WordPress
    1733  * @subpackage Post
    1734  * @since 1.5
     1706 * @since 1.5.0
    17351707 * @uses $wpdb
    17361708 *
    1737  * @param int $post_id post ID
    1738  * @param string $uri {@internal Missing Description}}
    1739  * @return mixed {@internal Missing Description}}
     1709 * @param int $post_id Post ID.
     1710 * @param string $uri Ping URI.
     1711 * @return int How many rows were updated.
    17401712 */
    17411713function add_ping($post_id, $uri) {
    17421714        global $wpdb;
     
    17521724}
    17531725
    17541726/**
    1755  * get_enclosed() - Get enclosures already enclosed for a post
     1727 * Retrieve enclosures already enclosed for a post.
    17561728 *
    1757  * {@internal Missing Long Description}}
    1758  *
    1759  * @package WordPress
    1760  * @subpackage Post
    1761  * @since 1.5
     1729 * @since 1.5.0
    17621730 * @uses $wpdb
    17631731 *
    1764  * @param int $post_id post ID
    1765  * @return array {@internal Missing Description}}
     1732 * @param int $post_id Post ID.
     1733 * @return array List of enclosures
    17661734 */
    17671735function get_enclosed($post_id) {
    17681736        $custom_fields = get_post_custom( $post_id );
     
    17831751}
    17841752
    17851753/**
    1786  * get_pung() - Get URLs already pinged for a post
     1754 * Retrieve URLs already pinged for a post.
    17871755 *
    1788  * {@internal Missing Long Description}}
    1789  *
    1790  * @package WordPress
    1791  * @subpackage Post
    1792  * @since 1.5
     1756 * @since 1.5.0
    17931757 * @uses $wpdb
    17941758 *
    1795  * @param int $post_id post ID
    1796  * @return array {@internal Missing Description}}
     1759 * @param int $post_id Post ID.
     1760 * @return array
    17971761 */
    17981762function get_pung($post_id) {
    17991763        global $wpdb;
     
    18051769}
    18061770
    18071771/**
    1808  * get_to_ping() - Get any URLs in the todo list
     1772 * Retrieve URLs that need to be pinged.
    18091773 *
    1810  * {@internal Missing Long Description}}
    1811  *
    1812  * @package WordPress
    1813  * @subpackage Post
    1814  * @since 1.5
     1774 * @since 1.5.0
    18151775 * @uses $wpdb
    18161776 *
    1817  * @param int $post_id post ID
    1818  * @return array {@internal Missing Description}}
     1777 * @param int $post_id Post ID
     1778 * @return array
    18191779 */
    18201780function get_to_ping($post_id) {
    18211781        global $wpdb;
     
    18271787}
    18281788
    18291789/**
    1830  * trackback_url_list() - Do trackbacks for a list of urls
     1790 * Do trackbacks for a list of URLs.
    18311791 *
    1832  * {@internal Missing Long Description}}
    1833  *
    1834  * @package WordPress
    1835  * @subpackage Post
    18361792 * @since 1.0.0
    18371793 *
    1838  * @param string $tb_list comma separated list of URLs
    1839  * @param int $post_id post ID
     1794 * @param string $tb_list Comma separated list of URLs
     1795 * @param int $post_id Post ID
    18401796 */
    18411797function trackback_url_list($tb_list, $post_id) {
    1842         if (!empty($tb_list)) {
     1798        if ( ! empty( $tb_list ) ) {
    18431799                // get post data
    18441800                $postdata = wp_get_single_post($post_id, ARRAY_A);
    18451801
     
    18471803                extract($postdata, EXTR_SKIP);
    18481804
    18491805                // form an excerpt
    1850                 $excerpt = strip_tags($post_excerpt?$post_excerpt:$post_content);
     1806                $excerpt = strip_tags($post_excerpt ? $post_excerpt : $post_content);
    18511807
    18521808                if (strlen($excerpt) > 255) {
    18531809                        $excerpt = substr($excerpt,0,252) . '...';
     
    18551811
    18561812                $trackback_urls = explode(',', $tb_list);
    18571813                foreach( (array) $trackback_urls as $tb_url) {
    1858                                 $tb_url = trim($tb_url);
    1859                                 trackback($tb_url, stripslashes($post_title), $excerpt, $post_id);
     1814                        $tb_url = trim($tb_url);
     1815                        trackback($tb_url, stripslashes($post_title), $excerpt, $post_id);
    18601816                }
    1861                 }
     1817        }
    18621818}
    18631819
    18641820//
     
    18661822//
    18671823
    18681824/**
    1869  * get_all_page_ids() - Get a list of page IDs
     1825 * Get a list of page IDs.
    18701826 *
    1871  * {@internal Missing Long Description}}
    1872  *
    1873  * @package WordPress
    1874  * @subpackage Post
    1875  * @since 2.0
     1827 * @since 2.0.0
    18761828 * @uses $wpdb
    18771829 *
    1878  * @return array {@internal Missing Description}}
     1830 * @return array List of page IDs.
    18791831 */
    18801832function get_all_page_ids() {
    18811833        global $wpdb;
     
    18891841}
    18901842
    18911843/**
    1892  * get_page() - Retrieves page data given a page ID or page object
     1844 * Retrieves page data given a page ID or page object.
    18931845 *
    1894  * {@internal Missing Long Description}}
    1895  *
    1896  * @package WordPress
    1897  * @subpackage Post
    18981846 * @since 1.5.1
    18991847 *
    1900  * @param mixed &$page page object or page ID
    1901  * @param string $output what to output
     1848 * @param mixed $page Page object or page ID. Passed by reference.
     1849 * @param string $output What to output. OBJECT, ARRAY_A, or ARRAY_N.
    19021850 * @param string $filter How the return value should be filtered.
    1903  * @return mixed {@internal Missing Description}}
     1851 * @return mixed Page data.
    19041852 */
    19051853function &get_page(&$page, $output = OBJECT, $filter = 'raw') {
    19061854        if ( empty($page) ) {
     
    19161864}
    19171865
    19181866/**
    1919  * get_page_by_path() - Retrieves a page given its path
     1867 * Retrieves a page given its path.
    19201868 *
    1921  * {@internal Missing Long Description}}
    1922  *
    1923  * @package WordPress
    1924  * @subpackage Post
    1925  * @since 2.1
     1869 * @since 2.1.0
    19261870 * @uses $wpdb
    19271871 *
    1928  * @param string $page_path page path
    1929  * @param string $output output type
    1930  * @return mixed {@internal Missing Description}}
     1872 * @param string $page_path Page path
     1873 * @param string $output Optional. Output type. OBJECT, ARRAY_N, or ARRAY_A.
     1874 * @return mixed Null when complete.
    19311875 */
    19321876function get_page_by_path($page_path, $output = OBJECT) {
    19331877        global $wpdb;
     
    19441888        $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 ));
    19451889
    19461890        if ( empty($pages) )
    1947                 return NULL;
     1891                return null;
    19481892
    19491893        foreach ($pages as $page) {
    19501894                $path = '/' . $leaf_path;
     
    19581902                        return get_page($page->ID, $output);
    19591903        }
    19601904
    1961         return NULL;
     1905        return null;
    19621906}
    19631907
    19641908/**
    1965  * get_page_by_title() - Retrieve a page given its title
     1909 * Retrieve a page given its title.
    19661910 *
    1967  * {@internal Missing Long Description}}
    1968  *
    1969  * @package WordPress
    1970  * @subpackage Post
    1971  * @since 2.1
     1911 * @since 2.1.0
    19721912 * @uses $wpdb
    19731913 *
    1974  * @param string $page_title page title
    1975  * @param string $output output type
    1976  * @return mixed {@internal Missing Description}}
     1914 * @param string $page_title Page title
     1915 * @param string $output Optional. Output type. OBJECT, ARRAY_N, or ARRAY_A.
     1916 * @return mixed
    19771917 */
    19781918function get_page_by_title($page_title, $output = OBJECT) {
    19791919        global $wpdb;
     
    19811921        if ( $page )
    19821922                return get_page($page, $output);
    19831923
    1984         return NULL;
     1924        return null;
    19851925}
    19861926
    19871927/**
    1988  * get_page_children() - Retrieve child pages
     1928 * Retrieve child pages from list of pages matching page ID.
    19891929 *
    1990  * {@internal Missing Long Description}}
     1930 * Matches against the pages parameter against the page ID. Also matches all
     1931 * children for the same to retrieve all children of a page. Does not make any
     1932 * SQL queries to get the children.
    19911933 *
    1992  * @package WordPress
    1993  * @subpackage Post
    19941934 * @since 1.5.1
    19951935 *
    1996  * @param int $page_id page ID
    1997  * @param array $pages list of pages
    1998  * @return array {@internal Missing Description}}
     1936 * @param int $page_id Page ID.
     1937 * @param array $pages List of pages' objects.
     1938 * @return array
    19991939 */
    20001940function &get_page_children($page_id, $pages) {
    20011941        $page_list = array();
     
    20101950}
    20111951
    20121952/**
    2013  * get_page_hierarchy() - {@internal Missing Short Description}}
     1953 * Order the pages with children under parents in a flat list.
    20141954 *
    2015  * Fetches the pages returned as a FLAT list, but arranged in order of their hierarchy,
    2016  * i.e., child parents immediately follow their parents.
     1955 * Fetches the pages returned as a FLAT list, but arranged in order of their
     1956 * hierarchy, i.e., child parents immediately follow their parents.
    20171957 *
    2018  * @package WordPress
    2019  * @subpackage Post
    2020  * @since 2.0
     1958 * @since 2.0.0
    20211959 *
    2022  * @param array $posts posts array
    2023  * @param int $parent parent page ID
    2024  * @return array {@internal Missing Description}}
     1960 * @param array $posts Posts array.
     1961 * @param int $parent Parent page ID.
     1962 * @return array
    20251963 */
    20261964function get_page_hierarchy($posts, $parent = 0) {
    20271965        $result = array ( );
     
    20361974}
    20371975
    20381976/**
    2039  * get_page_uri() - Builds a page URI
     1977 * Builds URI for a page.
    20401978 *
    2041  * {@internal Missing Long Description}}
     1979 * Sub pages will be in the "directory" under the parent page post name.
    20421980 *
    2043  * @package WordPress
    2044  * @subpackage Post
    2045  * @since 1.5
     1981 * @since 1.5.0
    20461982 *
    2047  * @param int $page_id page ID
    2048  * @return string {@internal Missing Description}}
     1983 * @param int $page_id Page ID.
     1984 * @return string Page URI.
    20491985 */
    20501986function get_page_uri($page_id) {
    20511987        $page = get_page($page_id);
     
    20642000}
    20652001
    20662002/**
    2067  * get_pages() - Retrieve a list of pages
     2003 * Retrieve a list of pages.
    20682004 *
    2069  * {@internal Missing Long Description}}
     2005 * The defaults that can be overridden are the following: 'child_of',
     2006 * 'sort_order', 'sort_column', 'post_title', 'hierarchical', 'exclude',
     2007 * 'include', 'meta_key', 'meta_value', and 'authors'.
    20702008 *
    2071  * @package WordPress
    2072  * @subpackage Post
    2073  * @since 1.5
     2009 * @since 1.5.0
    20742010 * @uses $wpdb
    20752011 *
    2076  * @param mixed $args Optional. Array or string of options
     2012 * @param mixed $args Optional. Array or string of options that overrides defaults.
    20772013 * @return array List of pages matching defaults or $args
    20782014 */
    20792015function &get_pages($args = '') {
     
    21612097        if ( ! empty( $meta_key ) || ! empty( $meta_value ) ) {
    21622098                $join = " LEFT JOIN $wpdb->postmeta ON ( $wpdb->posts.ID = $wpdb->postmeta.post_id )";
    21632099
    2164                 // meta_key and met_value might be slashed
     2100                // meta_key and meta_value might be slashed
    21652101                $meta_key = stripslashes($meta_key);
    21662102                $meta_value = stripslashes($meta_value);
    21672103                if ( ! empty( $meta_key ) )
     
    21982134//
    21992135
    22002136/**
    2201  * is_local_attachment() - Check if the attachment URI is local one and is really an attachment.
     2137 * Check if the attachment URI is local one and is really an attachment.
    22022138 *
    2203  * {@internal Missing Long Description}}
     2139 * @since 2.0.0
    22042140 *
    2205  * @package WordPress
    2206  * @subpackage Post
    2207  * @since 2.0
    2208  *
    22092141 * @param string $url URL to check
    2210  * @return bool {@internal Missing Description}}
     2142 * @return bool True on success, false on failure.
    22112143 */
    22122144function is_local_attachment($url) {
    22132145        if (strpos($url, get_bloginfo('url')) === false)
     
    22232155}
    22242156
    22252157/**
    2226  * wp_insert_attachment() - Insert an attachment
     2158 * Insert an attachment.
    22272159 *
    2228  * {@internal Missing Long Description}}
     2160 * If you set the 'ID' in the $object parameter, it will mean that you are
     2161 * updating and attempt to update the attachment. You can also set the
     2162 * attachment name or title by setting the key 'post_name' or 'post_title'.
    22292163 *
    2230  * @package WordPress
    2231  * @subpackage Post
    2232  * @since 2.0
     2164 * You can set the dates for the attachment manually by setting the 'post_date'
     2165 * and 'post_date_gmt' keys' values.
    22332166 *
     2167 * By default, the comments will use the default settings for whether the
     2168 * comments are allowed. You can close them manually or keep them open by
     2169 * setting the value for the 'comment_status' key.
     2170 *
     2171 * The $object parameter can have the following:
     2172 *     'post_status' - Default is 'draft'. Can not be override, set the same as
     2173 *         parent post.
     2174 *     'post_type' - Default is 'post', will be set to attachment. Can not
     2175 *         override.
     2176 *     'post_author' - Default is current user ID. The ID of the user, who added
     2177 *         the attachment.
     2178 *     'ping_status' - Default is the value in default ping status option.
     2179 *         Whether the attachment can accept pings.
     2180 *     'post_parent' - Default is 0. Can use $parent parameter or set this for
     2181 *         the post it belongs to, if any.
     2182 *     'menu_order' - Default is 0. The order it is displayed.
     2183 *     'to_ping' - Whether to ping.
     2184 *     'pinged' - Default is empty string.
     2185 *     'post_password' - Default is empty string. The password to access the
     2186 *         attachment.
     2187 *     'guid' - Global Unique ID for referencing the attachment.
     2188 *     'post_content_filtered' - Attachment post content filtered.
     2189 *     'post_excerpt' - Attachment excerpt.
     2190 *
     2191 * @since 2.0.0
    22342192 * @uses $wpdb
    22352193 * @uses $user_ID
    22362194 *
    2237  * @param object $object attachment object
    2238  * @param string $file filename
    2239  * @param int $post_parent parent post ID
    2240  * @return int {@internal Missing Description}}
     2195 * @param string|array $object Arguments to override defaults.
     2196 * @param string $file Optional filename.
     2197 * @param int $post_parent Parent post ID.
     2198 * @return int Attachment ID.
    22412199 */
    22422200function wp_insert_attachment($object, $file = false, $parent = 0) {
    22432201        global $wpdb, $user_ID;
     
    23002258                $post_date_gmt = current_time('mysql', 1);
    23012259
    23022260        if ( empty($post_modified) )
    2303                 $post_modified = $post_date;
     2261                $post_modified = $post_date;
    23042262        if ( empty($post_modified_gmt) )
    2305                 $post_modified_gmt = $post_date_gmt;
     2263                $post_modified_gmt = $post_date_gmt;
    23062264
    23072265        if ( empty($comment_status) ) {
    23082266                if ( $update )
     
    23672325}
    23682326
    23692327/**
    2370  * wp_delete_attachment() - Delete an attachment
     2328 * Delete an attachment.
    23712329 *
    2372  * {@internal Missing Long Description}}
     2330 * Will remove the file also, when the attachment is removed. Removes all post
     2331 * meta fields, taxonomy, comments, etc associated with the attachment (except
     2332 * the main post).
    23732333 *
    2374  * @package WordPress
    2375  * @subpackage Post
    2376  * @since 2.0
     2334 * @since 2.0.0
    23772335 * @uses $wpdb
     2336 * @uses do_action() Calls 'delete_attachment' hook on Attachment ID.
    23782337 *
    2379  * @param int $postid attachment Id
    2380  * @return mixed {@internal Missing Description}}
     2338 * @param int $postid Attachment ID.
     2339 * @return mixed False on failure. Post data on success.
    23812340 */
    23822341function wp_delete_attachment($postid) {
    23832342        global $wpdb;
     
    24312390}
    24322391
    24332392/**
    2434  * wp_get_attachment_metadata() - Retrieve metadata for an attachment
     2393 * Retrieve attachment meta field for attachment ID.
    24352394 *
    2436  * {@internal Missing Long Description}}
     2395 * @since 2.1.0
    24372396 *
    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}}
     2397 * @param int $post_id Attachment ID
     2398 * @param bool $unfiltered Optional, default is false. If true, filters are not run.
     2399 * @return string|bool Attachment meta field. False on failure.
    24452400 */
    24462401function wp_get_attachment_metadata( $post_id, $unfiltered = false ) {
    24472402        $post_id = (int) $post_id;
     
    24552410}
    24562411
    24572412/**
    2458  * wp_update_attachment_metadata() - Update metadata for an attachment
     2413 * Update metadata for an attachment.
    24592414 *
    2460  * {@internal Missing Long Description}}
     2415 * @since 2.1.0
    24612416 *
    2462  * @package WordPress
    2463  * @subpackage Post
    2464  * @since 2.1
    2465  *
    2466  * @param int $post_id attachment ID
    2467  * @param array $data attachment data
    2468  * @return int {@internal Missing Description}}
     2417 * @param int $post_id Attachment ID.
     2418 * @param array $data Attachment data.
     2419 * @return int
    24692420 */
    24702421function wp_update_attachment_metadata( $post_id, $data ) {
    24712422        $post_id = (int) $post_id;
     
    24782429}
    24792430
    24802431/**
    2481  * wp_get_attachment_url() - Retrieve the URL for an attachment
     2432 * Retrieve the URL for an attachment.
    24822433 *
    2483  * {@internal Missing Long Description}}
     2434 * @since 2.1.0
    24842435 *
    2485  * @package WordPress
    2486  * @subpackage Post
    2487  * @since 2.1
    2488  *
    2489  * @param int $post_id attachment ID
    2490  * @return string {@internal Missing Description}}
     2436 * @param int $post_id Attachment ID.
     2437 * @return string
    24912438 */
    24922439function wp_get_attachment_url( $post_id = 0 ) {
    24932440        $post_id = (int) $post_id;
     
    25032450}
    25042451
    25052452/**
    2506  * wp_get_attachment_thumb_file() - Retrieve thumbnail for an attachment
     2453 * Retrieve thumbnail for an attachment.
    25072454 *
    2508  * {@internal Missing Long Description}}
     2455 * @since 2.1.0
    25092456 *
    2510  * @package WordPress
    2511  * @subpackage Post
    2512  * @since 2.1
    2513  *
    2514  * @param int $post_id attachment ID
    2515  * @return mixed {@internal Missing Description}}
     2457 * @param int $post_id Attachment ID.
     2458 * @return mixed False on failure. Thumbnail file path on success.
    25162459 */
    25172460function wp_get_attachment_thumb_file( $post_id = 0 ) {
    25182461        $post_id = (int) $post_id;
     
    25292472}
    25302473
    25312474/**
    2532  * wp_get_attachment_thumb_url() - Retrieve URL for an attachment thumbnail
     2475 * Retrieve URL for an attachment thumbnail.
    25332476 *
    2534  * {@internal Missing Long Description}}
     2477 * @since 2.1.0
    25352478 *
    2536  * @package WordPress
    2537  * @subpackage Post
    2538  * @since 2.1
    2539  *
    2540  * @param int $post_id attachment ID
    2541  * @return string {@internal Missing Description}}
     2479 * @param int $post_id Attachment ID
     2480 * @return string|bool False on failure. Thumbnail URL on success.
    25422481 */
    25432482function wp_get_attachment_thumb_url( $post_id = 0 ) {
    25442483        $post_id = (int) $post_id;
     
    25602499}
    25612500
    25622501/**
    2563  * wp_attachment_is_image() - Check if the attachment is an image
     2502 * Check if the attachment is an image.
    25642503 *
    2565  * {@internal Missing Long Description}}
     2504 * @since 2.1.0
    25662505 *
    2567  * @package WordPress
    2568  * @subpackage Post
    2569  * @since 2.1
    2570  *
    2571  * @param int $post_id attachment ID
    2572  * @return bool {@internal Missing Description}}
     2506 * @param int $post_id Attachment ID
     2507 * @return bool
    25732508 */
    25742509function wp_attachment_is_image( $post_id = 0 ) {
    25752510        $post_id = (int) $post_id;
     
    25892524}
    25902525
    25912526/**
    2592  * wp_mime_type_icon() - Retrieve the icon for a MIME type
     2527 * Retrieve the icon for a MIME type.
    25932528 *
    2594  * {@internal Missing Long Description}}
     2529 * @since 2.1.0
    25952530 *
    2596  * @package WordPress
    2597  * @subpackage Post
    2598  * @since 2.1
    2599  *
    26002531 * @param string $mime MIME type
    2601  * @return string|bool {@internal Missing Description}}
     2532 * @return string|bool
    26022533 */
    26032534function wp_mime_type_icon( $mime = 0 ) {
    26042535        if ( !is_numeric($mime) )
     
    26792610}
    26802611
    26812612/**
    2682  * wp_check_for_changed_slugs() - {@internal Missing Short Description}}
     2613 * Checked for changed slugs for published posts and save old slug.
    26832614 *
    2684  * {@internal Missing Long Description}}
     2615 * The function is used along with form POST data. It checks for the wp-old-slug
     2616 * POST field. Will only be concerned with published posts and the slug actually
     2617 * changing.
    26852618 *
    2686  * @package WordPress
    2687  * @subpackage Post
    2688  * @since 2.1
     2619 * If the slug was changed and not already part of the old slugs then it will be
     2620 * added to the post meta field ('_wp_old_slug') for storing old slugs for that
     2621 * post.
    26892622 *
    2690  * @param int $post_id The Post ID
     2623 * The most logically usage of this function is redirecting changed posts, so
     2624 * that those that linked to an changed post will be redirected to the new post.
     2625 *
     2626 * @since 2.1.0
     2627 *
     2628 * @param int $post_id Post ID.
    26912629 * @return int Same as $post_id
    26922630 */
    26932631function wp_check_for_changed_slugs($post_id) {
     
    27182656}
    27192657
    27202658/**
    2721  * get_private_posts_cap_sql() - {@internal Missing Short Description}}
     2659 * Retrieve the private post SQL based on capability.
    27222660 *
    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.
     2661 * This function provides a standardized way to appropriately select on the
     2662 * post_status of posts/pages. The function will return a piece of SQL code that
     2663 * can be added to a WHERE clause; this SQL is constructed to allow all
     2664 * published posts, and all private posts to which the user has access.
    27282665 *
    2729  * @package WordPress
    2730  * @subpackage Post
    2731  * @since 2.2
     2666 * It also allows plugins that define their own post type to control the cap by
     2667 * using the hook 'pub_priv_sql_capability'. The plugin is expected to return
     2668 * the capability the user must have to read the private post type.
    27322669 *
     2670 * @since 2.2.0
     2671 *
    27332672 * @uses $user_ID
    2734  * @uses apply_filters() Call 'pub_priv_sql_capability' filter for plugins with different post types
     2673 * @uses apply_filters() Call 'pub_priv_sql_capability' filter for plugins with different post types.
    27352674 *
    27362675 * @param string $post_type currently only supports 'post' or 'page'.
    27372676 * @return string SQL code that can be added to a where clause.
     
    27732712}
    27742713
    27752714/**
    2776  * get_lastpostdate() - {@internal Missing Short Description}}
     2715 * Retrieve the date the the last post was published.
    27772716 *
    2778  * {@internal Missing Long Description}}
     2717 * The server timezone is the default and is the difference between GMT and
     2718 * server time. The 'blog' value is the date when the last post was posted. The
     2719 * 'gmt' is when the last post was posted in GMT formatted date.
    27792720 *
    2780  * @package WordPress
    2781  * @subpackage Post
    27822721 * @since 0.71
    27832722 *
    27842723 * @uses $wpdb
     
    28142753}
    28152754
    28162755/**
    2817  * get_lastpostmodified() - {@internal Missing Short Description}}
     2756 * Retrieve last post modified date depending on timezone.
    28182757 *
    2819  * {@internal Missing Long Description}}
     2758 * The server timezone is the default and is the difference between GMT and
     2759 * server time. The 'blog' value is just when the last post was modified. The
     2760 * 'gmt' is when the last post was modified in GMT time.
    28202761 *
    2821  * @package WordPress
    2822  * @subpackage Post
    2823  * @since 1.2
    2824  *
     2762 * @since 1.2.0
    28252763 * @uses $wpdb
    28262764 * @uses $blog_id
    28272765 * @uses apply_filters() Calls 'get_lastpostmodified' filter
    28282766 *
    28292767 * @global mixed $cache_lastpostmodified Stores the date the last post was modified
    2830  * @global mixed $pagenow The current page being viewed
    28312768 *
    28322769 * @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'.
    28332770 * @return string The date the post was last modified.
     
    28592796}
    28602797
    28612798/**
    2862  * update_post_cache() - Updates posts in cache
     2799 * Updates posts in cache.
    28632800 *
    2864  * @usedby update_page_cache() update_page_cache() aliased by this function.
     2801 * @usedby update_page_cache() Aliased by this function.
    28652802 *
    28662803 * @package WordPress
    28672804 * @subpackage Cache
     
    28782815}
    28792816
    28802817/**
    2881  * clean_post_cache() - Will clean the post in the cache
     2818 * Will clean the post in the cache.
    28822819 *
    2883  * Cleaning means delete from the cache of the post. Will call to clean
    2884  * the term object cache associated with the post ID.
     2820 * Cleaning means delete from the cache of the post. Will call to clean the term
     2821 * object cache associated with the post ID.
    28852822 *
    28862823 * @package WordPress
    28872824 * @subpackage Cache
    2888  * @since 2.0
     2825 * @since 2.0.0
    28892826 *
    28902827 * @uses do_action() Will call the 'clean_post_cache' hook action.
    28912828 *
     
    29112848}
    29122849
    29132850/**
    2914  * update_page_cache() - Alias of update_post_cache()
     2851 * Alias of update_post_cache().
    29152852 *
    29162853 * @see update_post_cache() Posts and pages are the same, alias is intentional
    29172854 *
     
    29262863}
    29272864
    29282865/**
    2929  * clean_page_cache() - Will clean the page in the cache
     2866 * Will clean the page in the cache.
    29302867 *
    2931  * Clean (read: delete) page from cache that matches $id. Will also clean
    2932  * cache associated with 'all_page_ids' and 'get_pages'.
     2868 * Clean (read: delete) page from cache that matches $id. Will also clean cache
     2869 * associated with 'all_page_ids' and 'get_pages'.
    29332870 *
    29342871 * @package WordPress
    29352872 * @subpackage Cache
    2936  * @since 2.0
     2873 * @since 2.0.0
    29372874 *
    29382875 * @uses do_action() Will call the 'clean_page_cache' hook action.
    29392876 *
     
    29492886}
    29502887
    29512888/**
    2952  * update_post_caches() - Call major cache updating functions for list of Post objects.
     2889 * Call major cache updating functions for list of Post objects.
    29532890 *
    29542891 * @package WordPress
    29552892 * @subpackage Cache
    2956  * @since 1.5
     2893 * @since 1.5.0
    29572894 *
    29582895 * @uses $wpdb
    29592896 * @uses update_post_cache()
     
    29802917}
    29812918
    29822919/**
    2983  * update_postmeta_cache() - {@internal Missing Short Description}}
     2920 * Updates metadata cache for list of post IDs.
    29842921 *
    2985  * {@internal Missing Long Description}}
     2922 * Performs SQL query to retrieve the metadata for the post IDs and updates the
     2923 * metadata cache for the posts. Therefore, the functions, which call this
     2924 * function, do not need to perform SQL queries on their own.
    29862925 *
    29872926 * @package WordPress
    29882927 * @subpackage Cache
    2989  * @since 2.1
     2928 * @since 2.1.0
    29902929 *
    29912930 * @uses $wpdb
    29922931 *
    2993  * @param array $post_ids {@internal Missing Description}}
    2994  * @return bool|array Returns false if there is nothing to update or an array of metadata
     2932 * @param array $post_ids List of post IDs.
     2933 * @return bool|array Returns false if there is nothing to update or an array of metadata.
    29952934 */
    29962935function update_postmeta_cache($post_ids) {
    29972936        global $wpdb;
     
    30512990//
    30522991
    30532992/**
    3054  * _transition_post_status() - Hook {@internal Missing Short Description}}
     2993 * Hook for managing future post transitions to published.
    30552994 *
    3056  * {@internal Missing Long Description}}
    3057  *
    3058  * @package WordPress
    3059  * @subpackage Post
    3060  * @since 2.3
    3061  *
     2995 * @since 2.3.0
     2996 * @access private
    30622997 * @uses $wpdb
    30632998 *
    3064  * @param string $new_status {@internal Missing Description}}
    3065  * @param string $old_status {@internal Missing Description}}
     2999 * @param string $new_status New post status
     3000 * @param string $old_status Previous post status
    30663001 * @param object $post Object type containing the post information
    30673002 */
    30683003function _transition_post_status($new_status, $old_status, $post) {
     
    30803015}
    30813016
    30823017/**
    3083  * _future_post_hook() - Hook used to schedule publication for a post marked for the future.
     3018 * Hook used to schedule publication for a post marked for the future.
    30843019 *
    30853020 * The $post properties used and must exist are 'ID' and 'post_date_gmt'.
    30863021 *
    3087  * @package WordPress
    3088  * @subpackage Post
    3089  * @since 2.3
     3022 * @since 2.3.0
    30903023 *
    3091  * @param int $post_id Not Used. Can be set to null.
     3024 * @param int $deprecated Not Used. Can be set to null.
    30923025 * @param object $post Object type containing the post information
    30933026 */
    30943027function _future_post_hook($deprecated = '', $post) {
     
    30973030}
    30983031
    30993032/**
    3100  * _publish_post_hook() - Hook {@internal Missing Short Description}}
     3033 * Hook to schedule pings and enclosures when a post is published.
    31013034 *
    3102  * {@internal Missing Long Description}}
    3103  *
    3104  * @package WordPress
    3105  * @subpackage Post
    3106  * @since 2.3
    3107  *
     3035 * @since 2.3.0
    31083036 * @uses $wpdb
    31093037 * @uses XMLRPC_REQUEST
    31103038 * @uses APP_REQUEST
     
    31323060}
    31333061
    31343062/**
    3135  * _save_post_hook() - Hook used to prevent page/post cache and rewrite rules from staying dirty
     3063 * Hook used to prevent page/post cache and rewrite rules from staying dirty.
    31363064 *
    3137  * Does two things. If the post is a page and has a template then it will update/add that
    3138  * template to the meta. For both pages and posts, it will clean the post cache to make sure
    3139  * that the cache updates to the changes done recently. For pages, the rewrite rules of
    3140  * WordPress are flushed to allow for any changes.
     3065 * Does two things. If the post is a page and has a template then it will
     3066 * update/add that template to the meta. For both pages and posts, it will clean
     3067 * the post cache to make sure that the cache updates to the changes done
     3068 * recently. For pages, the rewrite rules of WordPress are flushed to allow for
     3069 * any changes.
    31413070 *
    3142  * The $post parameter, only uses 'post_type' property and 'page_template' property.
     3071 * The $post parameter, only uses 'post_type' property and 'page_template'
     3072 * property.
    31433073 *
    3144  * @package WordPress
    3145  * @subpackage Post
    3146  * @since 2.3
    3147  *
     3074 * @since 2.3.0
    31483075 * @uses $wp_rewrite Flushes Rewrite Rules.
    31493076 *
    31503077 * @param int $post_id The ID in the database table for the $post
     
    31603087        }
    31613088}
    31623089
    3163 //
    3164 // Private
    3165 //
    3166 
     3090/**
     3091 * Retrieve post ancestors and append to post ancestors property.
     3092 *
     3093 * Will only retrieve ancestors once, if property is already set, then nothing
     3094 * will be done. If there is not a parent post, or post ID and post parent ID
     3095 * are the same then nothing will be done.
     3096 *
     3097 * The parameter is passed by reference, so nothing needs to be returned. The
     3098 * property will be updated and can be referenced after the function is
     3099 * complete. The post parent will be an ancestor and the parent of the post
     3100 * parent will be an ancestor. There will only be two ancestors at the most.
     3101 *
     3102 * @access private
     3103 * @since unknown
     3104 * @uses $wpdb
     3105 *
     3106 * @param object $_post Post data.
     3107 * @return null When nothing needs to be done.
     3108 */
    31673109function _get_post_ancestors(&$_post) {
    31683110        global $wpdb;
    31693111
     
    31833125        }
    31843126}
    31853127
    3186 /* Post Revisions */
    3187 
    31883128/**
    3189  * _wp_post_revision_fields() - determines which fields of posts are to be saved in revisions
     3129 * Determines which fields of posts are to be saved in revisions.
    31903130 *
    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.
     3131 * Does two things. If passed a post *array*, it will return a post array ready
     3132 * to be insterted into the posts table as a post revision. Otherwise, returns
     3133 * an array whose keys are the post fields to be saved for post revisions.
    31943134 *
    31953135 * @package WordPress
    3196  * @subpackage Post Revisions
    3197  * @since 2.6
     3136 * @subpackage Post_Revisions
     3137 * @since 2.6.0
     3138 * @access private
    31983139 *
    3199  * @param array $post optional a post array to be processed for insertion as a post revision
     3140 * @param array $post Optional a post array to be processed for insertion as a post revision.
    32003141 * @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
     3142 * @return array Post array ready to be inserted as a post revision or array of fields that can be versioned.
    32023143 */
    32033144function _wp_post_revision_fields( $post = null, $autosave = false ) {
    32043145        static $fields = false;
     
    32373178}
    32383179
    32393180/**
    3240  * wp_save_post_revision() - Saves an already existing post as a post revision.  Typically used immediately prior to post updates.
     3181 * Saves an already existing post as a post revision.
    32413182 *
     3183 * Typically used immediately prior to post updates.
     3184 *
    32423185 * @package WordPress
    3243  * @subpackage Post Revisions
    3244  * @since 2.6
     3186 * @subpackage Post_Revisions
     3187 * @since 2.6.0
    32453188 *
    32463189 * @uses _wp_put_post_revision()
    32473190 *
    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
     3191 * @param int $post_id The ID of the post to save as a revision.
     3192 * @return mixed Null or 0 if error, new revision ID, if success.
    32503193 */
    32513194function wp_save_post_revision( $post_id ) {
    32523195        // We do autosaves manually with wp_create_post_autosave()
     
    32903233}
    32913234
    32923235/**
    3293  * wp_get_post_autosave() - returns the autosaved data of the specified post.
     3236 * Retrieve the autosaved data of the specified post.
    32943237 *
    3295  * Returns a post object containing the information that was autosaved for the specified post.
     3238 * Returns a post object containing the information that was autosaved for the
     3239 * specified post.
    32963240 *
    32973241 * @package WordPress
    3298  * @subpackage Post Revisions
    3299  * @since 2.6
     3242 * @subpackage Post_Revisions
     3243 * @since 2.6.0
    33003244 *
    3301  * @param int $post_id The post ID
    3302  * @return object|bool the autosaved data or false on failure or when no autosave exists
     3245 * @param int $post_id The post ID.
     3246 * @return object|bool The autosaved data or false on failure or when no autosave exists.
    33033247 */
    33043248function wp_get_post_autosave( $post_id ) {
    33053249        global $wpdb;
     
    33263270        return false;
    33273271}
    33283272
    3329 // Internally used to hack WP_Query into submission
     3273/**
     3274 * Internally used to hack WP_Query into submission.
     3275 *
     3276 * @package WordPress
     3277 * @subpackage Post_Revisions
     3278 * @since 2.6.0
     3279 *
     3280 * @param object $query WP_Query object
     3281 */
    33303282function _wp_get_post_autosave_hack( $query ) {
    33313283        $query->is_single = false;
    33323284}
    33333285
    3334 
    33353286/**
    3336  * wp_is_post_revision() - Determines if the specified post is a revision.
     3287 * Determines if the specified post is a revision.
    33373288 *
    33383289 * @package WordPress
    3339  * @subpackage Post Revisions
    3340  * @since 2.6
     3290 * @subpackage Post_Revisions
     3291 * @since 2.6.0
    33413292 *
    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
     3293 * @param int|object $post Post ID or post object.
     3294 * @return bool|int False if not a revision, ID of revision's parent otherwise.
    33443295 */
    33453296function wp_is_post_revision( $post ) {
    33463297        if ( !$post = wp_get_post_revision( $post ) )
     
    33493300}
    33503301
    33513302/**
    3352  * wp_is_post_autosave() - Determines if the specified post is an autosave.
     3303 * Determines if the specified post is an autosave.
    33533304 *
    33543305 * @package WordPress
    3355  * @subpackage Post Revisions
    3356  * @since 2.6
     3306 * @subpackage Post_Revisions
     3307 * @since 2.6.0
    33573308 *
    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
     3309 * @param int|object $post Post ID or post object.
     3310 * @return bool|int False if not a revision, ID of autosave's parent otherwise
    33603311 */
    33613312function wp_is_post_autosave( $post ) {
    33623313        if ( !$post = wp_get_post_revision( $post ) )
     
    33673318}
    33683319
    33693320/**
    3370  * _wp_put_post_revision() - Inserts post data into the posts table as a post revision
     3321 * Inserts post data into the posts table as a post revision.
    33713322 *
    33723323 * @package WordPress
    3373  * @subpackage Post Revisions
    3374  * @since 2.6
     3324 * @subpackage Post_Revisions
     3325 * @since 2.6.0
    33753326 *
    33763327 * @uses wp_insert_post()
    33773328 *
    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
     3329 * @param int|object|array $post Post ID, post object OR post array.
     3330 * @param bool $autosave Optional. Is the revision an autosave?
     3331 * @return mixed Null or 0 if error, new revision ID if success.
    33813332 */
    33823333function _wp_put_post_revision( $post = null, $autosave = false ) {
    33833334        if ( is_object($post) )
     
    34023353}
    34033354
    34043355/**
    3405  * wp_get_post_revision() - Gets a post revision
     3356 * Gets a post revision.
    34063357 *
    34073358 * @package WordPress
    3408  * @subpackage Post Revisions
    3409  * @since 2.6
     3359 * @subpackage Post_Revisions
     3360 * @since 2.6.0
    34103361 *
    34113362 * @uses get_post()
    34123363 *
    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
     3364 * @param int|object $post Post ID or post object
     3365 * @param string $output Optional. OBJECT, ARRAY_A, or ARRAY_N.
     3366 * @param string $filter Optional sanitation filter.  @see sanitize_post()
     3367 * @return mixed Null if error or post object if success
    34173368 */
    34183369function &wp_get_post_revision(&$post, $output = OBJECT, $filter = 'raw') {
    34193370        $null = null;
     
    34363387}
    34373388
    34383389/**
    3439  * wp_restore_post_revision() - Restores a post to the specified revision
     3390 * Restores a post to the specified revision.
    34403391 *
    3441  * Can restore a past using all fields of the post revision, or only selected fields.
     3392 * Can restore a past using all fields of the post revision, or only selected
     3393 * fields.
    34423394 *
    34433395 * @package WordPress
    3444  * @subpackage Post Revisions
    3445  * @since 2.6
     3396 * @subpackage Post_Revisions
     3397 * @since 2.6.0
    34463398 *
    34473399 * @uses wp_get_post_revision()
    34483400 * @uses wp_update_post()
    34493401 *
    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
     3402 * @param int|object $revision_id Revision ID or revision object.
     3403 * @param array $fields Optional. What fields to restore from.  Defaults to all.
     3404 * @return mixed Null if error, false if no fields to restore, (int) post ID if success.
    34533405 */
    34543406function wp_restore_post_revision( $revision_id, $fields = null ) {
    34553407        if ( !$revision = wp_get_post_revision( $revision_id, ARRAY_A ) )
     
    34783430}
    34793431
    34803432/**
    3481  * wp_delete_post_revision() - Deletes a revision.
     3433 * Deletes a revision.
    34823434 *
    3483  * Deletes the row from the posts table corresponding to the specified revision
     3435 * Deletes the row from the posts table corresponding to the specified revision.
    34843436 *
    34853437 * @package WordPress
    3486  * @subpackage Post Revisions
    3487  * @since 2.6
     3438 * @subpackage Post_Revisions
     3439 * @since 2.6.0
    34883440 *
    34893441 * @uses wp_get_post_revision()
    34903442 * @uses wp_delete_post()
    34913443 *
    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
     3444 * @param int|object $revision_id Revision ID or revision object.
     3445 * @param array $fields Optional. What fields to restore from.  Defaults to all.
     3446 * @return mixed Null if error, false if no fields to restore, (int) post ID if success.
    34953447 */
    34963448function wp_delete_post_revision( $revision_id ) {
    34973449        if ( !$revision = wp_get_post_revision( $revision_id ) )
     
    35083460}
    35093461
    35103462/**
    3511  * wp_get_post_revisions() - Returns all revisions of specified post
     3463 * Returns all revisions of specified post.
    35123464 *
    35133465 * @package WordPress
    3514  * @subpackage Post Revisions
    3515  * @since 2.6
     3466 * @subpackage Post_Revisions
     3467 * @since 2.6.0
    35163468 *
    35173469 * @uses get_children()
    35183470 *
    3519  * @param int|object $post_id post ID or post object
     3471 * @param int|object $post_id Post ID or post object
    35203472 * @return array empty if no revisions
    35213473 */
    35223474function wp_get_post_revisions( $post_id = 0, $args = null ) {