WordPress.org
Get WordPress

Make WordPress Core

Changeset 8669


Ignore:
Timestamp:
08/19/2008 04:38:06 PM (17 years ago)
Author:
ryan
Message:

post.php phpdoc. Props santosj. fixes #7538

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/post.php

    r8647 r8669  
    22/**
    33 * Post functions and post utility function.
    4  *
    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.
    84 *
    95 * @package WordPress
    106 * @subpackage Post
    11  * @since 1.5
     7 * @since 1.5.0
    128 */
    139
    … …  
    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
    … …  
    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
    … …  
    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
    … …  
    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.
    … …  
    157148
    158149/**
    159  * get_extended() - Get extended entry info (<!--more-->)
    160  *
    161  * {@internal Missing Long Description}}
    162  *
    163  * @package WordPress
    164  * @subpackage Post
     150 * Get extended entry info (<!--more-->).
     151 *
     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.
     155 *
     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) {
    … …  
    185180
    186181/**
    187  * get_post() - Retrieves post data given a post ID or post object.
    188  *
    189  * {@internal Missing Long Description}}
    190  *
    191  * @package WordPress
    192  * @subpackage Post
     182 * Retrieves post data given a post ID or post object.
     183 *
     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.
     186 *
    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') {
    … …  
    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
    … …  
    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 *
    … …  
    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.
    … …  
    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
    … …  
    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.
    … …  
    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.
    … …  
    387369
    388370/**
    389  * get_post_type() - Returns post type
    390  *
    391  * {@internal Missing Long Description}}
    392  *
    393  * @package WordPress
    394  * @subpackage Post
    395  * @since 2.1
     371 * Retrieve the post type of the current post or of a given post.
     372 *
     373 * @since 2.1.0
    396374 *
    397375 * @uses $wpdb
    398  * @uses $posts {@internal Missing Description}}
    399  *
    400  * @param mixed $post post object or post ID
    401  * @return mixed post type or false
     376 * @uses $posts The Loop post global
     377 *
     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) {
    … …  
    416394
    417395/**
    418  * set_post_type() - Set post type
    419  *
    420  * {@internal Missing Long Description}}
    421  *
    422  * @package WordPress
    423  * @subpackage Post
    424  * @since 2.5
     396 * Updates the post type for the post ID.
     397 *
     398 * The page or post cache will be cleaned for the post ID.
     399 *
     400 * @since 2.5.0
    425401 *
    426402 * @uses $wpdb
    427  * @uses $posts {@internal Missing Description}}
    428  *
    429  * @param mixed $post_id post ID
    430  * @param mixed post type
    431  * @return bool {@internal Missing Description}}
     403 *
     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' ) {
    … …  
    446421
    447422/**
    448  * get_posts() - Returns a number of posts
    449  *
    450  * {@internal Missing Long Description}}
    451  *
    452  * @package WordPress
    453  * @subpackage Post
    454  * @since 1.2
     423 * Retrieve list of latest posts or posts matching criteria.
     424 *
     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.
     438 *
     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) {
    … …  
    495481
    496482/**
    497  * add_post_meta() - adds metadata for post
    498  *
    499  * {@internal Missing Long Description}}
    500  *
    501  * @package WordPress
    502  * @subpackage Post
    503  * @since 1.5
     483 * Add meta data field to a post.
     484 *
     485 * Post meta data is called "Custom Fields" on the Administration Panels.
     486 *
     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) {
    … …  
    534518
    535519/**
    536  * delete_post_meta() - delete post metadata
    537  *
    538  * {@internal Missing Long Description}}
    539  *
    540  * @package WordPress
    541  * @subpackage Post
    542  * @since 1.5
     520 * Remove metadata matching criteria from a post.
     521 *
     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.
     525 *
     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 = '') {
    … …  
    577561
    578562/**
    579  * get_post_meta() - Get a post meta field
    580  *
    581  * {@internal Missing Long Description}}
    582  *
    583  * @package WordPress
    584  * @subpackage Post
    585  * @since 1.5
     563 * Retrieve post meta field for a post.
     564 *
     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) {
    … …  
    621601
    622602/**
    623  * update_post_meta() - Update a post meta field
    624  *
    625  * {@internal Missing Long Description}}
    626  *
    627  * @package WordPress
    628  * @subpackage Post
     603 * Update post meta field based on post ID.
     604 *
     605 * Use the $prev_value parameter to differentiate between meta fields with the
     606 * same key and post ID.
     607 *
     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 = '') {
    … …  
    663644
    664645/**
    665  * delete_post_meta_by_key() - Delete everything from post meta matching $post_meta_key
    666  *
    667  * @package WordPress
    668  * @subpackage Post
    669  * @since 2.3
     646 * Delete everything from post meta matching meta key.
     647 *
     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 */
    … …  
    684663
    685664/**
    686  * get_post_custom() - Retrieve post custom fields
    687  *
    688  * {@internal Missing Long Description}}
    689  *
    690  * @package WordPress
    691  * @subpackage Post
    692  * @since 1.2
     665 * Retrieve post meta fields, based on post ID.
     666 *
     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.
     670 *
     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) {
    … …  
    714692
    715693/**
    716  * get_post_custom_keys() - Retrieve post custom field names
    717  *
    718  * @package WordPress
    719  * @subpackage Post
    720  * @since 1.2
     694 * Retrieve meta field names for a post.
     695 *
     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 ) {
    … …  
    735713
    736714/**
    737  * get_post_custom_values() - Retrieve values for a custom post field
    738  *
    739  * @package WordPress
    740  * @subpackage Post
    741  * @since 1.2
     715 * Retrieve values for a custom post field.
     716 *
     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 ) {
    … …  
    753732
    754733/**
    755  * is_sticky() - Check if post is sticky
    756  *
    757  * {@internal Missing Long Description}}
    758  *
    759  * @package WordPress
    760  * @subpackage Post
    761  * @since 2.7
    762  *
    763  * @param int $post_id A post ID
    764  * @return bool
     734 * Check if post is sticky.
     735 *
     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.
     738 *
     739 * @since 2.7.0
     740 *
     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) {
    … …  
    783761}
    784762
    785 
    786 /**
    787  * sanitize_post() - Sanitize every post field
    788  *
    789  * {@internal Missing Long Description}}
    790  *
    791  * @package WordPress
    792  * @subpackage Post
    793  * @since 2.3
     763/**
     764 * Sanitize every post field.
     765 *
     766 * If the context is 'raw', then the post object or array will just be returned.
     767 *
     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 */
    … …  
    811787
    812788/**
    813  * sanitize_post_field() - Sanitize post field based on context
    814  *
    815  * {@internal Missing Long Description}}
    816  *
    817  * @package WordPress
    818  * @subpackage Post
    819  * @since 2.3
    820  *
    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
     789 * Sanitize post field based on context.
     790 *
     791 * Possible context values are: raw, edit, db, attribute, js, and display. The
     792 * display context is used by default.
     793 *
     794 * @since 2.3.0
     795 *
     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) {
    … …  
    883858
    884859/**
    885  * Make a post sticky
    886  *
    887  * Makes a post stick to the top of the front page
    888  *
    889  * @package WordPress
    890  * @subpackage Post
    891  * @since 2.7
    892  *
    893  * @param int $post_id A post ID
     860 * Make a post sticky.
     861 *
     862 * Sticky posts should be displayed at the top of the front page.
     863 *
     864 * @since 2.7.0
     865 *
     866 * @param int $post_id Post ID.
    894867 */
    895868function stick_post($post_id) {
    … …  
    906879
    907880/**
    908  * Unstick a post
    909  *
    910  * Unstick a post from the front page
    911  *
    912  * @package WordPress
    913  * @subpackage Post
    914  * @since 2.7
    915  *
    916  * @param int $post_id A post ID
     881 * Unstick a post.
     882 *
     883 * Sticky posts should be displayed at the top of the front page.
     884 *
     885 * @since 2.7.0
     886 *
     887 * @param int $post_id Post ID.
    917888 */
    918889function unstick_post($post_id) {
    … …  
    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 *
    … …  
    989958
    990959/**
    991  * wp_count_attachments() - Count number of attachments
    992  *
    993  * {@internal Missing Long Description}}
    994  *
    995  * @package WordPress
    996  * @subpackage Post
    997  * @since 2.5
    998  *
    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
    1001  */
    1002 
     960 * Count number of attachments for the mime type(s).
     961 *
     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.
     966 *
     967 * @since 2.5.0
     968 *
     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.
     971 */
    1003972function wp_count_attachments( $mime_type = '' ) {
    1004973    global $wpdb;
    … …  
    1016985
    1017986/**
    1018  * wp_match_mime_type() - Check a MIME-Type against a list
    1019  *
    1020  * {@internal Missing Long Description}}
    1021  *
    1022  * @package WordPress
    1023  * @subpackage Post
    1024  * @since 2.5
     987 * Check a MIME-Type against a list.
     988 *
     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.
     992 *
     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*)
    … …  
    10531022
    10541023/**
    1055  * wp_get_post_mime_type_where() - Convert MIME types into SQL
    1056  *
    1057  * @package WordPress
    1058  * @subpackage Post
    1059  * @since 2.5
    1060  *
    1061  * @param string|array $mime_types MIME types
    1062  * @return string SQL AND clause
     1024 * Convert MIME types into SQL.
     1025 *
     1026 * @since 2.5.0
     1027 *
     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) {
    … …  
    11001067
    11011068/**
    1102  * wp_delete_post() - Deletes a Post
    1103  *
    1104  * {@internal Missing Long Description}}
    1105  *
    1106  * @package WordPress
    1107  * @subpackage Post
     1069 * Removes a post, attachment, or page.
     1070 *
     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.
     1073 *
    11081074 * @since 1.0.0
    1109  *
    1110  * @param int $postid post ID
    1111  * @return mixed {@internal Missing Description}}
     1075 * @uses do_action() Calls 'deleted_post' hook on post ID.
     1076 *
     1077 * @param int $postid Post ID.
     1078 * @return mixed
    11121079 */
    11131080function wp_delete_post($postid = 0) {
    … …  
    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 *
     1152 * @since 2.1.0
     1153 *
     1154 * @uses wp_get_object_terms() Retrieves the categories. Args details can be found here.
     1155 *
     1156 * @param int $post_id Optional. The Post ID.
     1157 * @param array $args Optional. Overwrite the defaults.
     1158 * @return array
     1159 */
     1160function wp_get_post_categories( $post_id = 0, $args = array() ) {
     1161    $post_id = (int) $post_id;
     1162
     1163    $defaults = array('fields' => 'ids');
     1164    $args = wp_parse_args( $args, $defaults );
     1165
     1166    $cats = wp_get_object_terms($post_id, 'category', $args);
     1167    return $cats;
     1168}
     1169
     1170/**
     1171 * Retrieve the tags for a post.
     1172 *
     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 *
    11851177 * @package WordPress
    11861178 * @subpackage Post
    1187  * @since 2.1
    1188  *
    1189  * @uses wp_get_object_terms() Retrieves the categories. Args details can be found here
     1179 * @since 2.3.0
     1180 *
     1181 * @uses wp_get_object_terms() Gets the tags for returning. Args can be found here
    11901182 *
    11911183 * @param int $post_id Optional. The Post ID
    11921184 * @param array $args Optional. Overwrite the defaults
    1193  * @return array {@internal Missing Description}}
    1194  */
    1195 function wp_get_post_categories( $post_id = 0, $args = array() ) {
    1196     $post_id = (int) $post_id;
    1197 
    1198     $defaults = array('fields' => 'ids');
    1199     $args = wp_parse_args( $args, $defaults );
    1200 
    1201     $cats = wp_get_object_terms($post_id, 'category', $args);
    1202     return $cats;
    1203 }
    1204 
    1205 /**
    1206  * wp_get_post_tags() - Retrieve the post tags
    1207  *
    1208  * @package WordPress
    1209  * @subpackage Post
    1210  * @since 2.3
    1211  *
    1212  * @uses wp_get_object_terms() Gets the tags for returning. Args can be found here
    1213  *
    1214  * @param int $post_id Optional. The Post ID
    1215  * @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() ) {
    … …  
    12281197
    12291198/**
    1230  * wp_get_recent_posts() - Get the $num most recent posts
    1231  *
    1232  * {@internal Missing Long Description}}
    1233  *
    1234  * @package WordPress
    1235  * @subpackage Post
     1199 * Retrieve number of recent posts.
     1200 *
    12361201 * @since 1.0.0
    1237  *
    1238  * @param int $num number of posts to get
    1239  * @return array {@internal Missing Description}}
     1202 * @uses $wpdb
     1203 *
     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) {
    … …  
    12511217    $result = $wpdb->get_results($sql,ARRAY_A);
    12521218
    1253     return $result?$result:array();
    1254 }
    1255 
    1256 /**
    1257  * wp_get_single_post() - Get one post
    1258  *
    1259  * {@internal Missing Long Description}}
    1260  *
    1261  * @package WordPress
    1262  * @subpackage Post
     1219    return $result ? $result : array();
     1220}
     1221
     1222/**
     1223 * Retrieve a single post, based on post ID.
     1224 *
     1225 * Has categories in 'post_category' property or key. Has tags in 'tags_input'
     1226 * property or key.
     1227 *
    12631228 * @since 1.0.0
    1264  * @uses $wpdb
    1265  *
    1266  * @param int $postid post ID
    1267  * @param string $mode How to return result, either OBJECT, ARRAY_N, or ARRAY_A
     1229 *
     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 */
    … …  
    12871251
    12881252/**
    1289  * wp_insert_post() - Insert a post
    1290  *
    1291  * {@internal Missing Long Description}}
    1292  *
    1293  * @package WordPress
    1294  * @subpackage Post
     1253 * Insert a post.
     1254 *
     1255 * If the $postarr parameter has 'ID' set to a value, then post will be updated.
     1256 *
     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.
     1260 *
     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 *
    12951279 * @since 1.0.0
    1296  *
    12971280 * @uses $wpdb
    12981281 * @uses $wp_rewrite
    12991282 * @uses $user_ID
    1300  * @uses $allowedtags
    1301  *
    1302  * @param array $postarr post contents
    1303  * @return int post ID or 0 on error
     1283 *
     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) {
    … …  
    15081491
    15091492/**
    1510  * wp_update_post() - Update a post
    1511  *
    1512  * {@internal Missing Long Description}}
    1513  *
    1514  * @package WordPress
    1515  * @subpackage Post
     1493 * Update a post with new post data.
     1494 *
     1495 * The date does not have to be set for drafts. You can set the date and it will
     1496 * not be overridden.
     1497 *
    15161498 * @since 1.0.0
    1517  * @uses $wpdb
    1518  *
    1519  * @param array $postarr post data
    1520  * @return int {@internal Missing Description}}
     1499 *
     1500 * @param array|object $postarr Post data.
     1501 * @return int 0 on failure, Post ID on success.
    15211502 */
    15221503function wp_update_post($postarr = array()) {
    … …  
    15591540
    15601541/**
    1561  * wp_publish_post() - Mark a post as "published"
    1562  *
    1563  * {@internal Missing Long Description}}
    1564  *
    1565  * @package WordPress
    1566  * @subpackage Post
    1567  * @since 2.1
     1542 * Publish a post by transitioning the post status.
     1543 *
     1544 * @since 2.1.0
    15681545 * @uses $wpdb
    1569  *
    1570  * @param int $post_id Post ID
    1571  * @return int|null {@internal Missing Description}}
     1546 * @uses do_action() Calls 'edit_post', 'save_post', and 'wp_insert_post' on post_id and post data.
     1547 *
     1548 * @param int $post_id Post ID.
     1549 * @return null
    15721550 */
    15731551function wp_publish_post($post_id) {
    … …  
    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.
    1605  *
    1606  * {@internal Missing Long Description}}
     1580 * Publish future post and make sure post ID has future post status.
     1581 *
     1582 * Invoked by cron 'publish_future_post' event. This safeguard prevents cron
     1583 * from publishing drafts, etc.
     1584 *
     1585 * @since 2.5.0
     1586 *
     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.
     1589 */
     1590function check_and_publish_future_post($post_id) {
     1591
     1592    $post = get_post($post_id);
     1593
     1594    if ( empty($post) )
     1595        return;
     1596
     1597    if ( 'future' != $post->post_status )
     1598        return;
     1599
     1600    return wp_publish_post($post_id);
     1601}
     1602
     1603/**
     1604 * Adds tags to a post.
     1605 *
     1606 * @uses wp_set_post_tags() Same first two parameters, but the last parameter is always set to true.
    16071607 *
    16081608 * @package WordPress
    16091609 * @subpackage Post
    1610  * @since 2.5
    1611  * @uses $wpdb
     1610 * @since 2.3.0
    16121611 *
    16131612 * @param int $post_id Post ID
    1614  * @return int|null {@internal Missing Description}}
    1615  */
    1616 function check_and_publish_future_post($post_id) {
    1617 
    1618     $post = get_post($post_id);
    1619 
    1620     if ( empty($post) )
    1621         return;
    1622 
    1623     if ( 'future' != $post->post_status )
    1624         return;
    1625 
    1626     return wp_publish_post($post_id);
    1627 }
    1628 
    1629 /**
    1630  * wp_add_post_tags() - Adds the tags to a post
    1631  *
    1632  * @uses wp_set_post_tags() Same first two paraeters, but the last parameter is always set to true.
    1633  *
    1634  * @package WordPress
    1635  * @subpackage Post
    1636  * @since 2.3
    1637  *
    1638  * @param int $post_id Optional. Post ID
    1639  * @param string $tags The tags to set for the post
     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 */
    … …  
    16441618}
    16451619
    1646 /**
    1647  * wp_set_post_tags() - Set the tags for a post
    1648  *
    1649  * {@internal Missing Long Description}}
    1650  *
    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
     1620
     1621/**
     1622 * Set the tags for a post.
     1623 *
     1624 * @since 2.3.0
     1625 * @uses wp_set_object_terms() Sets the tags for the post.
     1626 *
     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
    … …  
    16731644
    16741645/**
    1675  * wp_set_post_categories() - Set categories for a post
    1676  *
    1677  * {@internal Missing Long Description}}
    1678  *
    1679  * @package WordPress
    1680  * @subpackage Post
    1681  * @since 2.1
    1682  * @uses $wpdb
    1683  *
    1684  * @param int $post_ID post ID
    1685  * @param array $post_categories
    1686  * @return bool|mixed {@internal Missing Description}}
     1646 * Set categories for a post.
     1647 *
     1648 * If the post categories parameter is not set, then the default category is
     1649 * going used.
     1650 *
     1651 * @since 2.1.0
     1652 *
     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()) {
    … …  
    16981667
    16991668    return wp_set_object_terms($post_ID, $post_categories, 'category');
    1700 }   // wp_set_post_categories()
    1701 
    1702 /**
    1703  * wp_transition_post_status() - Change the post transition status
    1704  *
    1705  * {@internal Missing Long Description}}
    1706  *
    1707  * @package WordPress
    1708  * @subpackage Post
    1709  * @since 2.3
    1710  *
    1711  * @param string $new_status {@internal Missing Description}}
    1712  * @param string $old_status {@internal Missing Description}}
    1713  * @param int $post {@internal Missing Description}}
     1669}
     1670
     1671/**
     1672 * Transition the post status of a post.
     1673 *
     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.
     1680 *
     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.
     1684 *
     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) {
    … …  
    17261702
    17271703/**
    1728  * add_ping() - Add a URL to those already pung
    1729  *
    1730  * {@internal Missing Long Description}}
    1731  *
    1732  * @package WordPress
    1733  * @subpackage Post
    1734  * @since 1.5
     1704 * Add a URL to those already pung.
     1705 *
     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) {
    … …  
    17531725
    17541726/**
    1755  * get_enclosed() - Get enclosures already enclosed for a post
    1756  *
    1757  * {@internal Missing Long Description}}
    1758  *
    1759  * @package WordPress
    1760  * @subpackage Post
    1761  * @since 1.5
     1727 * Retrieve enclosures already enclosed for a post.
     1728 *
     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) {
    … …  
    17841752
    17851753/**
    1786  * get_pung() - Get URLs already pinged for a post
    1787  *
    1788  * {@internal Missing Long Description}}
    1789  *
    1790  * @package WordPress
    1791  * @subpackage Post
    1792  * @since 1.5
     1754 * Retrieve URLs already pinged for a post.
     1755 *
     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) {
    … …  
    18061770
    18071771/**
    1808  * get_to_ping() - Get any URLs in the todo list
    1809  *
    1810  * {@internal Missing Long Description}}
    1811  *
    1812  * @package WordPress
    1813  * @subpackage Post
    1814  * @since 1.5
     1772 * Retrieve URLs that need to be pinged.
     1773 *
     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) {
    … …  
    18281788
    18291789/**
    1830  * trackback_url_list() - Do trackbacks for a list of urls
    1831  *
    1832  * {@internal Missing Long Description}}
    1833  *
    1834  * @package WordPress
    1835  * @subpackage Post
     1790 * Do trackbacks for a list of URLs.
     1791 *
    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);
    … …  
    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) {
    … …  
    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);
    1860         }
    1861         }
     1814            $tb_url = trim($tb_url);
     1815            trackback($tb_url, stripslashes($post_title), $excerpt, $post_id);
     1816        }
     1817    }
    18621818}
    18631819
    … …  
    18671823
    18681824/**
    1869  * get_all_page_ids() - Get a list of page IDs
    1870  *
    1871  * {@internal Missing Long Description}}
    1872  *
    1873  * @package WordPress
    1874  * @subpackage Post
    1875  * @since 2.0
     1825 * Get a list of page IDs.
     1826 *
     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() {
    … …  
    18901842
    18911843/**
    1892  * get_page() - Retrieves page data given a page ID or page object
    1893  *
    1894  * {@internal Missing Long Description}}
    1895  *
    1896  * @package WordPress
    1897  * @subpackage Post
     1844 * Retrieves page data given a page ID or page object.
     1845 *
    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') {
    … …  
    19171865
    19181866/**
    1919  * get_page_by_path() - Retrieves a page given its path
    1920  *
    1921  * {@internal Missing Long Description}}
    1922  *
    1923  * @package WordPress
    1924  * @subpackage Post
    1925  * @since 2.1
     1867 * Retrieves a page given its path.
     1868 *
     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) {
    … …  
    19451889
    19461890    if ( empty($pages) )
    1947         return NULL;
     1891        return null;
    19481892
    19491893    foreach ($pages as $page) {
    … …  
    19591903    }
    19601904
    1961     return NULL;
    1962 }
    1963 
    1964 /**
    1965  * get_page_by_title() - Retrieve a page given its title
    1966  *
    1967  * {@internal Missing Long Description}}
    1968  *
    1969  * @package WordPress
    1970  * @subpackage Post
    1971  * @since 2.1
     1905    return null;
     1906}
     1907
     1908/**
     1909 * Retrieve a page given its title.
     1910 *
     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) {
    … …  
    19821922        return get_page($page, $output);
    19831923
    1984     return NULL;
    1985 }
    1986 
    1987 /**
    1988  * get_page_children() - Retrieve child pages
    1989  *
    1990  * {@internal Missing Long Description}}
    1991  *
    1992  * @package WordPress
    1993  * @subpackage Post
     1924    return null;
     1925}
     1926
     1927/**
     1928 * Retrieve child pages from list of pages matching page ID.
     1929 *
     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.
     1933 *
    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) {
    … …  
    20111951
    20121952/**
    2013  * get_page_hierarchy() - {@internal Missing Short Description}}
    2014  *
    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.
    2017  *
    2018  * @package WordPress
    2019  * @subpackage Post
    2020  * @since 2.0
    2021  *
    2022  * @param array $posts posts array
    2023  * @param int $parent parent page ID
    2024  * @return array {@internal Missing Description}}
     1953 * Order the pages with children under parents in a flat list.
     1954 *
     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.
     1957 *
     1958 * @since 2.0.0
     1959 *
     1960 * @param array $posts Posts array.
     1961 * @param int $parent Parent page ID.
     1962 * @return array
    20251963 */
    20261964function get_page_hierarchy($posts, $parent = 0) {
    … …  
    20371975
    20381976/**
    2039  * get_page_uri() - Builds a page URI
    2040  *
    2041  * {@internal Missing Long Description}}
    2042  *
    2043  * @package WordPress
    2044  * @subpackage Post
    2045  * @since 1.5
    2046  *
    2047  * @param int $page_id page ID
    2048  * @return string {@internal Missing Description}}
     1977 * Builds URI for a page.
     1978 *
     1979 * Sub pages will be in the "directory" under the parent page post name.
     1980 *
     1981 * @since 1.5.0
     1982 *
     1983 * @param int $page_id Page ID.
     1984 * @return string Page URI.
    20491985 */
    20501986function get_page_uri($page_id) {
    … …  
    20652001
    20662002/**
    2067  * get_pages() - Retrieve a list of pages
    2068  *
    2069  * {@internal Missing Long Description}}
    2070  *
    2071  * @package WordPress
    2072  * @subpackage Post
    2073  * @since 1.5
     2003 * Retrieve a list of pages.
     2004 *
     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'.
     2008 *
     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 */
    … …  
    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);
    … …  
    21992135
    22002136/**
    2201  * is_local_attachment() - Check if the attachment URI is local one and is really an attachment.
    2202  *
    2203  * {@internal Missing Long Description}}
    2204  *
    2205  * @package WordPress
    2206  * @subpackage Post
    2207  * @since 2.0
     2137 * Check if the attachment URI is local one and is really an attachment.
     2138 *
     2139 * @since 2.0.0
    22082140 *
    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) {
    … …  
    22242156
    22252157/**
    2226  * wp_insert_attachment() - Insert an attachment
    2227  *
    2228  * {@internal Missing Long Description}}
    2229  *
    2230  * @package WordPress
    2231  * @subpackage Post
    2232  * @since 2.0
    2233  *
     2158 * Insert an attachment.
     2159 *
     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'.
     2163 *
     2164 * You can set the dates for the attachment manually by setting the 'post_date'
     2165 * and 'post_date_gmt' keys' values.
     2166 *
     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) {
    … …  
    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) ) {
    … …  
    23682326
    23692327/**
    2370  * wp_delete_attachment() - Delete an attachment
    2371  *
    2372  * {@internal Missing Long Description}}
    2373  *
    2374  * @package WordPress
    2375  * @subpackage Post
    2376  * @since 2.0
     2328 * Delete an attachment.
     2329 *
     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).
     2333 *
     2334 * @since 2.0.0
    23772335 * @uses $wpdb
    2378  *
    2379  * @param int $postid attachment Id
    2380  * @return mixed {@internal Missing Description}}
     2336 * @uses do_action() Calls 'delete_attachment' hook on Attachment ID.
     2337 *
     2338 * @param int $postid Attachment ID.
     2339 * @return mixed False on failure. Post data on success.
    23812340 */
    23822341function wp_delete_attachment($postid) {
    … …  
    24322391
    24332392/**
    2434  * wp_get_attachment_metadata() - Retrieve metadata for an attachment
    2435  *
    2436  * {@internal Missing Long Description}}
    2437  *
    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}}
     2393 * Retrieve attachment meta field for attachment ID.
     2394 *
     2395 * @since 2.1.0
     2396 *
     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 ) {
    … …  
    24562411
    24572412/**
    2458  * wp_update_attachment_metadata() - Update metadata for an attachment
    2459  *
    2460  * {@internal Missing Long Description}}
    2461  *
    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}}
     2413 * Update metadata for an attachment.
     2414 *
     2415 * @since 2.1.0
     2416 *
     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 ) {
    … …  
    24792430
    24802431/**
    2481  * wp_get_attachment_url() - Retrieve the URL for an attachment
    2482  *
    2483  * {@internal Missing Long Description}}
    2484  *
    2485  * @package WordPress
    2486  * @subpackage Post
    2487  * @since 2.1
    2488  *
    2489  * @param int $post_id attachment ID
    2490  * @return string {@internal Missing Description}}
     2432 * Retrieve the URL for an attachment.
     2433 *
     2434 * @since 2.1.0
     2435 *
     2436 * @param int $post_id Attachment ID.
     2437 * @return string
    24912438 */
    24922439function wp_get_attachment_url( $post_id = 0 ) {
    … …  
    25042451
    25052452/**
    2506  * wp_get_attachment_thumb_file() - Retrieve thumbnail for an attachment
    2507  *
    2508  * {@internal Missing Long Description}}
    2509  *
    2510  * @package WordPress
    2511  * @subpackage Post
    2512  * @since 2.1
    2513  *
    2514  * @param int $post_id attachment ID
    2515  * @return mixed {@internal Missing Description}}
     2453 * Retrieve thumbnail for an attachment.
     2454 *
     2455 * @since 2.1.0
     2456 *
     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 ) {
    … …  
    25302473
    25312474/**
    2532  * wp_get_attachment_thumb_url() - Retrieve URL for an attachment thumbnail
    2533  *
    2534  * {@internal Missing Long Description}}
    2535  *
    2536  * @package WordPress
    2537  * @subpackage Post
    2538  * @since 2.1
    2539  *
    2540  * @param int $post_id attachment ID
    2541  * @return string {@internal Missing Description}}
     2475 * Retrieve URL for an attachment thumbnail.
     2476 *
     2477 * @since 2.1.0
     2478 *
     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 ) {
    … …  
    25612500
    25622501/**
    2563  * wp_attachment_is_image() - Check if the attachment is an image
    2564  *
    2565  * {@internal Missing Long Description}}
    2566  *
    2567  * @package WordPress
    2568  * @subpackage Post
    2569  * @since 2.1
    2570  *
    2571  * @param int $post_id attachment ID
    2572  * @return bool {@internal Missing Description}}
     2502 * Check if the attachment is an image.
     2503 *
     2504 * @since 2.1.0
     2505 *
     2506 * @param int $post_id Attachment ID
     2507 * @return bool
    25732508 */
    25742509function wp_attachment_is_image( $post_id = 0 ) {
    … …  
    25902525
    25912526/**
    2592  * wp_mime_type_icon() - Retrieve the icon for a MIME type
    2593  *
    2594  * {@internal Missing Long Description}}
    2595  *
    2596  * @package WordPress
    2597  * @subpackage Post
    2598  * @since 2.1
     2527 * Retrieve the icon for a MIME type.
     2528 *
     2529 * @since 2.1.0
    25992530 *
    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 ) {
    … …  
    26802611
    26812612/**
    2682  * wp_check_for_changed_slugs() - {@internal Missing Short Description}}
    2683  *
    2684  * {@internal Missing Long Description}}
    2685  *
    2686  * @package WordPress
    2687  * @subpackage Post
    2688  * @since 2.1
    2689  *
    2690  * @param int $post_id The Post ID
     2613 * Checked for changed slugs for published posts and save old slug.
     2614 *
     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.
     2618 *
     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.
     2622 *
     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 */
    … …  
    27192657
    27202658/**
    2721  * get_private_posts_cap_sql() - {@internal Missing Short Description}}
    2722  *
    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.
    2728  *
    2729  * @package WordPress
    2730  * @subpackage Post
    2731  * @since 2.2
     2659 * Retrieve the private post SQL based on capability.
     2660 *
     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.
     2665 *
     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.
     2669 *
     2670 * @since 2.2.0
    27322671 *
    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'.
    … …  
    27742713
    27752714/**
    2776  * get_lastpostdate() - {@internal Missing Short Description}}
    2777  *
    2778  * {@internal Missing Long Description}}
    2779  *
    2780  * @package WordPress
    2781  * @subpackage Post
     2715 * Retrieve the date the the last post was published.
     2716 *
     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.
     2720 *
    27822721 * @since 0.71
    27832722 *
    … …  
    28152754
    28162755/**
    2817  * get_lastpostmodified() - {@internal Missing Short Description}}
    2818  *
    2819  * {@internal Missing Long Description}}
    2820  *
    2821  * @package WordPress
    2822  * @subpackage Post
    2823  * @since 1.2
    2824  *
     2756 * Retrieve last post modified date depending on timezone.
     2757 *
     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.
     2761 *
     2762 * @since 1.2.0
    28252763 * @uses $wpdb
    28262764 * @uses $blog_id
    … …  
    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'.
    … …  
    28602797
    28612798/**
    2862  * update_post_cache() - Updates posts in cache
    2863  *
    2864  * @usedby update_page_cache() update_page_cache() aliased by this function.
     2799 * Updates posts in cache.
     2800 *
     2801 * @usedby update_page_cache() Aliased by this function.
    28652802 *
    28662803 * @package WordPress
    … …  
    28792816
    28802817/**
    2881  * clean_post_cache() - Will clean the post in the cache
    2882  *
    2883  * Cleaning means delete from the cache of the post. Will call to clean
    2884  * the term object cache associated with the post ID.
     2818 * Will clean the post in the cache.
     2819 *
     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.
    … …  
    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
    … …  
    29272864
    29282865/**
    2929  * clean_page_cache() - Will clean the page in the cache
    2930  *
    2931  * Clean (read: delete) page from cache that matches $id. Will also clean
    2932  * cache associated with 'all_page_ids' and 'get_pages'.
     2866 * Will clean the page in the cache.
     2867 *
     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.
    … …  
    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
    … …  
    29812918
    29822919/**
    2983  * update_postmeta_cache() - {@internal Missing Short Description}}
    2984  *
    2985  * {@internal Missing Long Description}}
     2920 * Updates metadata cache for list of post IDs.
     2921 *
     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) {
    … …  
    30522991
    30532992/**
    3054  * _transition_post_status() - Hook {@internal Missing Short Description}}
    3055  *
    3056  * {@internal Missing Long Description}}
    3057  *
    3058  * @package WordPress
    3059  * @subpackage Post
    3060  * @since 2.3
    3061  *
     2993 * Hook for managing future post transitions to published.
     2994 *
     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 */
    … …  
    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
    3090  *
    3091  * @param int $post_id Not Used. Can be set to null.
     3022 * @since 2.3.0
     3023 *
     3024 * @param int $deprecated Not Used. Can be set to null.
    30923025 * @param object $post Object type containing the post information
    30933026 */
    … …  
    30983031
    30993032/**
    3100  * _publish_post_hook() - Hook {@internal Missing Short Description}}
    3101  *
    3102  * {@internal Missing Long Description}}
    3103  *
    3104  * @package WordPress
    3105  * @subpackage Post
    3106  * @since 2.3
    3107  *
     3033 * Hook to schedule pings and enclosures when a post is published.
     3034 *
     3035 * @since 2.3.0
    31083036 * @uses $wpdb
    31093037 * @uses XMLRPC_REQUEST
    … …  
    31333061
    31343062/**
    3135  * _save_post_hook() - Hook used to prevent page/post cache and rewrite rules from staying dirty
    3136  *
    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.
    3141  *
    3142  * The $post parameter, only uses 'post_type' property and 'page_template' property.
    3143  *
    3144  * @package WordPress
    3145  * @subpackage Post
    3146  * @since 2.3
    3147  *
     3063 * Hook used to prevent page/post cache and rewrite rules from staying dirty.
     3064 *
     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.
     3070 *
     3071 * The $post parameter, only uses 'post_type' property and 'page_template'
     3072 * property.
     3073 *
     3074 * @since 2.3.0
    31483075 * @uses $wp_rewrite Flushes Rewrite Rules.
    31493076 *
    … …  
    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;
    … …  
    31843126}
    31853127
    3186 /* Post Revisions */
    3187 
    3188 /**
    3189  * _wp_post_revision_fields() - determines which fields of posts are to be saved in revisions
    3190  *
    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.
     3128/**
     3129 * Determines which fields of posts are to be saved in revisions.
     3130 *
     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
    3198  *
    3199  * @param array $post optional a post array to be processed for insertion as a post revision
     3136 * @subpackage Post_Revisions
     3137 * @since 2.6.0
     3138 * @access private
     3139 *
     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 ) {
    … …  
    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.
     3182 *
     3183 * Typically used immediately prior to post updates.
    32413184 *
    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 ) {
    … …  
    32913234
    32923235/**
    3293  * wp_get_post_autosave() - returns the autosaved data of the specified post.
    3294  *
    3295  * Returns a post object containing the information that was autosaved for the specified post.
     3236 * Retrieve the autosaved data of the specified post.
     3237 *
     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
    3300  *
    3301  * @param int $post_id The post ID
    3302  * @return object|bool the autosaved data or false on failure or when no autosave exists
     3242 * @subpackage Post_Revisions
     3243 * @since 2.6.0
     3244 *
     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 ) {
    … …  
    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 
    3335 /**
    3336  * wp_is_post_revision() - Determines if the specified post is a revision.
     3286/**
     3287 * Determines if the specified post is a revision.
    33373288 *
    33383289 * @package WordPress
    3339  * @subpackage Post Revisions
    3340  * @since 2.6
    3341  *
    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
     3290 * @subpackage Post_Revisions
     3291 * @since 2.6.0
     3292 *
     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 ) {
    … …  
    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
    3357  *
    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
     3306 * @subpackage Post_Revisions
     3307 * @since 2.6.0
     3308 *
     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 ) {
    … …  
    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 ) {
    … …  
    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') {
    … …  
    34373388
    34383389/**
    3439  * wp_restore_post_revision() - Restores a post to the specified revision
    3440  *
    3441  * Can restore a past using all fields of the post revision, or only selected fields.
     3390 * Restores a post to the specified revision.
     3391 *
     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 ) {
    … …  
    34793431
    34803432/**
    3481  * wp_delete_post_revision() - Deletes a revision.
    3482  *
    3483  * Deletes the row from the posts table corresponding to the specified revision
     3433 * Deletes a revision.
     3434 *
     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 ) {
    … …  
    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 */
Note: See TracChangeset for help on using the changeset viewer.