WordPress.org

Make WordPress Core

Ticket #8805: 8805.3.diff

File 8805.3.diff, 15.6 KB (added by CharlesClarkson, 9 years ago)

More changes for documentation for post.php.

  • wp-includes/post.php

     
    417417 * @uses $wpdb
    418418 *
    419419 * @param int $post_id Post ID to change post type. Not actually optional.
    420  * @param string $post_type Optional, default is post. Supported values are 'post' or 'page' to name a few.
     420 * @param string $post_type Optional, default is post. Supported values are 'post' or 'page' to
     421 *  name a few.
    421422 * @return int Amount of rows changed. Should be 1 for success and 0 for failure.
    422423 */
    423424function set_post_type( $post_id = 0, $post_type = 'post' ) {
     
    456457 * @uses WP_Query::query() See for more default arguments and information.
    457458 * @link http://codex.wordpress.org/Template_Tags/get_posts
    458459 *
    459  * @param array $args Optional. Override defaults.
     460 * @param array $args Optional. Overrides defaults.
    460461 * @return array List of posts.
    461462 */
    462463function get_posts($args = null) {
     
    592593 * @param int $post_id Post ID.
    593594 * @param string $key The meta key to retrieve.
    594595 * @param bool $single Whether to return a single value.
    595  * @return mixed Will be an array if $single is false. Will be value of meta data field if $single is true.
     596 * @return mixed Will be an array if $single is false. Will be value of meta data field if $single
     597 *  is true.
    596598 */
    597599function get_post_meta($post_id, $key, $single = false) {
    598600        if ( !$key )
     
    827829/**
    828830 * Sanitize post field based on context.
    829831 *
    830  * Possible context values are: raw, edit, db, attribute, js, and display. The
    831  * display context is used by default.
     832 * Possible context values are:  'raw', 'edit', 'db', 'display', 'attribute' and 'js'. The
     833 * 'display' context is used by default. 'attribute' and 'js' contexts are treated like 'display'
     834 * when calling filters.
    832835 *
    833836 * @since 2.3.0
     837 * @uses apply_filters() Calls 'edit_$field' and '${field_no_prefix}_edit_pre' passing $value and
     838 *  $post_id if $context == 'edit' and field name prefix == 'post_'.
    834839 *
     840 * @uses apply_filters() Calls 'edit_post_$field' passing $value and $post_id if $context == 'db'.
     841 * @uses apply_filters() Calls 'pre_$field' passing $value if $context == 'db' and field name prefix == 'post_'.
     842 * @uses apply_filters() Calls '${field}_pre' passing $value if $context == 'db' and field name prefix != 'post_'.
     843 *
     844 * @uses apply_filters() Calls '$field' passing $value, $post_id and $context if $context == anything
     845 *  other than 'raw', 'edit' and 'db' and field name prefix == 'post_'.
     846 * @uses apply_filters() Calls 'post_$field' passing $value if $context == anything other than 'raw',
     847 *  'edit' and 'db' and field name prefix != 'post_'.
     848 *
    835849 * @param string $field The Post Object field name.
    836850 * @param mixed $value The Post Object value.
    837851 * @param int $post_id Post ID.
    838  * @param string $context How to sanitize post fields.
     852 * @param string $context How to sanitize post fields. Looks for 'raw', 'edit', 'db', 'display',
     853 *               'attribute' and 'js'.
    839854 * @return mixed Sanitized value.
    840855 */
    841856function sanitize_post_field($field, $value, $post_id, $context) {
     
    10311046 *
    10321047 * @since 2.5.0
    10331048 *
    1034  * @param string|array $wildcard_mime_types e.g. audio/mpeg or image (same as image/*) or flash (same as *flash*)
     1049 * @param string|array $wildcard_mime_types e.g. audio/mpeg or image (same as image/*) or
     1050 *  flash (same as *flash*).
    10351051 * @param string|array $real_mime_types post_mime_type values
    10361052 * @return array array(wildcard=>array(real types))
    10371053 */
     
    11111127 * This includes comments, post meta fields, and terms associated with the post.
    11121128 *
    11131129 * @since 1.0.0
    1114  * @uses do_action() Calls 'deleted_post' hook on post ID.
     1130 * @uses do_action() on 'delete_post' before deletion unless post type is 'attachment'.
     1131 * @uses do_action() on 'deleted_post' after deletion unless post type is 'attachment'.
     1132 * @uses wp_delete_attachment() if post type is 'attachment'.
    11151133 *
    11161134 * @param int $postid Post ID.
    1117  * @return mixed
     1135 * @return mixed False on failure
    11181136 */
    11191137function wp_delete_post($postid = 0) {
    11201138        global $wpdb, $wp_rewrite;
     
    12121230 * Retrieve the tags for a post.
    12131231 *
    12141232 * There is only one default for this function, called 'fields' and by default
    1215  * is set to 'all'. There are other defaults that can be override in
     1233 * is set to 'all'. There are other defaults that can be overridden in
    12161234 * {@link wp_get_object_terms()}.
    12171235 *
    12181236 * @package WordPress
     
    12331251 * Retrieve the terms for a post.
    12341252 *
    12351253 * There is only one default for this function, called 'fields' and by default
    1236  * is set to 'all'. There are other defaults that can be override in
     1254 * is set to 'all'. There are other defaults that can be overridden in
    12371255 * {@link wp_get_object_terms()}.
    12381256 *
    12391257 * @package WordPress
     
    13221340 * setting the value for 'comment_status' key.
    13231341 *
    13241342 * The defaults for the parameter $postarr are:
    1325  *     'post_status' - Default is 'draft'.
    1326  *     'post_type' - Default is 'post'.
    1327  *     'post_author' - Default is current user ID. The ID of the user, who added
    1328  *         the post.
    1329  *     'ping_status' - Default is the value in default ping status option.
    1330  *         Whether the attachment can accept pings.
    1331  *     'post_parent' - Default is 0. Set this for the post it belongs to, if
    1332  *         any.
    1333  *     'menu_order' - Default is 0. The order it is displayed.
    1334  *     'to_ping' - Whether to ping.
    1335  *     'pinged' - Default is empty string.
    1336  *     'post_password' - Default is empty string. The password to access the
    1337  *         attachment.
    1338  *     'guid' - Global Unique ID for referencing the attachment.
     1343 *     'post_status'   - Default is 'draft'.
     1344 *     'post_type'     - Default is 'post'.
     1345 *     'post_author'   - Default is current user ID ($user_ID). The ID of the user who added the post.
     1346 *     'ping_status'   - Default is the value in 'default_ping_status' option.
     1347 *                       Whether the attachment can accept pings.
     1348 *     'post_parent'   - Default is 0. Set this for the post it belongs to, if any.
     1349 *     'menu_order'    - Default is 0. The order it is displayed.
     1350 *     'to_ping'       - Whether to ping.
     1351 *     'pinged'        - Default is empty string.
     1352 *     'post_password' - Default is empty string. The password to access the attachment.
     1353 *     'guid'          - Global Unique ID for referencing the attachment.
    13391354 *     'post_content_filtered' - Post content filtered.
    1340  *     'post_excerpt' - Post excerpt.
     1355 *     'post_excerpt'  - Post excerpt.
    13411356 *
    13421357 * @since 1.0.0
     1358 * @link http://core.trac.wordpress.org/ticket/9084 Bug report on 'wp_insert_post_data' filter.
    13431359 * @uses $wpdb
    13441360 * @uses $wp_rewrite
    13451361 * @uses $user_ID
    13461362 *
    1347  * @param array $postarr Optional. Override defaults.
     1363 * @uses do_action() Calls 'pre_post_update' on post ID if this is an update.
     1364 * @uses do_action() Calls 'edit_post' action on post ID and post data if this is an update.
     1365 * @uses do_action() Calls 'save_post' and 'wp_insert_post' on post id and post data just before
     1366 *                   returning.
     1367 *
     1368 * @uses apply_filters() Calls 'wp_insert_post_data' passing $data, $postarr prior to database
     1369 *                       update or insert.
     1370 * @uses wp_transition_post_status()
     1371 *
     1372 * @param array $postarr Optional. Overrides defaults.
    13481373 * @param bool $wp_error Optional. Allow return of WP_Error on failure.
    13491374 * @return int|WP_Error The value 0 or WP_Error on failure. The post ID on success.
    13501375 */
     
    17941819 * Calls hooks to transition post status. If the new post status is not the same
    17951820 * as the previous post status, then two hooks will be ran, the first is
    17961821 * 'transition_post_status' with new status, old status, and post data. The
    1797  * next action called is 'OLDSTATUS_to_NEWSTATUS' the NEWSTATUS is the
    1798  * $new_status parameter and the OLDSTATUS is $old_status parameter; it has the
     1822 * next action called is 'OLDSTATUS_to_NEWSTATUS' the 'NEWSTATUS' is the
     1823 * $new_status parameter and the 'OLDSTATUS' is $old_status parameter; it has the
    17991824 * post data.
    18001825 *
    18011826 * The final action will run whether or not the post statuses are the same. The
    1802  * action is named 'NEWSTATUS_POSTTYPE', NEWSTATUS is from the $new_status
    1803  * parameter and POSTTYPE is post_type post data.
     1827 * action is named 'NEWSTATUS_POSTTYPE', 'NEWSTATUS' is from the $new_status
     1828 * parameter and 'POSTTYPE' is post_type post data.
    18041829 *
    18051830 * @since 2.3.0
     1831 * @link http://codex.wordpress.org/Post_Status_Transitions
    18061832 *
     1833 * @uses do_action() Calls 'transition_post_status' on $new_status, $old_status and
     1834 *  $post if there is a status change.
     1835 * @uses do_action() Calls '${old_status}_to_$new_status' on $post if there is a status change.
     1836 * @uses do_action() Calls '${new_status}_$post->post_type' on post ID and $post.
     1837 *
    18071838 * @param string $new_status Transition to this post status.
    18081839 * @param string $old_status Previous post status.
    18091840 * @param object $post Post data.
    18101841 */
    1811 function wp_transition_post_status($new_status, $old_status, $post) {
     1842 function wp_transition_post_status($new_status, $old_status, $post) {
    18121843        if ( $new_status != $old_status ) {
    18131844                do_action('transition_post_status', $new_status, $old_status, $post);
    18141845                do_action("${old_status}_to_$new_status", $post);
     
    20732104/**
    20742105 * Order the pages with children under parents in a flat list.
    20752106 *
    2076  * Fetches the pages returned as a FLAT list, but arranged in order of their
    2077  * hierarchy, i.e., child parents immediately follow their parents.
    2078  *
    20792107 * @since 2.0.0
    20802108 *
    20812109 * @param array $posts Posts array.
    20822110 * @param int $parent Parent page ID.
    2083  * @return array
     2111 * @return array A list arranged by hierarchy. Children immediately follow their parents.
    20842112 */
    20852113function get_page_hierarchy($posts, $parent = 0) {
    20862114        $result = array ( );
     
    23202348 * setting the value for the 'comment_status' key.
    23212349 *
    23222350 * The $object parameter can have the following:
    2323  *     'post_status' - Default is 'draft'. Can not be override, set the same as
    2324  *         parent post.
    2325  *     'post_type' - Default is 'post', will be set to attachment. Can not
    2326  *         override.
    2327  *     'post_author' - Default is current user ID. The ID of the user, who added
    2328  *         the attachment.
    2329  *     'ping_status' - Default is the value in default ping status option.
    2330  *         Whether the attachment can accept pings.
    2331  *     'post_parent' - Default is 0. Can use $parent parameter or set this for
    2332  *         the post it belongs to, if any.
    2333  *     'menu_order' - Default is 0. The order it is displayed.
    2334  *     'to_ping' - Whether to ping.
    2335  *     'pinged' - Default is empty string.
    2336  *     'post_password' - Default is empty string. The password to access the
    2337  *         attachment.
    2338  *     'guid' - Global Unique ID for referencing the attachment.
     2351 *     'post_status'   - Default is 'draft'. Can not be overridden, set the same as parent post.
     2352 *     'post_type'     - Default is 'post', will be set to attachment. Can not override.
     2353 *     'post_author'   - Default is current user ID. The ID of the user, who added the attachment.
     2354 *     'ping_status'   - Default is the value in default ping status option. Whether the attachment
     2355 *                       can accept pings.
     2356 *     'post_parent'   - Default is 0. Can use $parent parameter or set this for the post it belongs
     2357 *                       to, if any.
     2358 *     'menu_order'    - Default is 0. The order it is displayed.
     2359 *     'to_ping'       - Whether to ping.
     2360 *     'pinged'        - Default is empty string.
     2361 *     'post_password' - Default is empty string. The password to access the attachment.
     2362 *     'guid'          - Global Unique ID for referencing the attachment.
    23392363 *     'post_content_filtered' - Attachment post content filtered.
    2340  *     'post_excerpt' - Attachment excerpt.
     2364 *     'post_excerpt'  - Attachment excerpt.
    23412365 *
    23422366 * @since 2.0.0
    23432367 * @uses $wpdb
    23442368 * @uses $user_ID
     2369 * @uses do_action() Calls 'edit_attachment' on $post_ID if this is an update.
     2370 * @uses do_action() Calls 'add_attachment' on $post_ID if this is not an update.
    23452371 *
    23462372 * @param string|array $object Arguments to override defaults.
    23472373 * @param string $file Optional filename.
     
    29963022 * Cleaning means delete from the cache of the post. Will call to clean the term
    29973023 * object cache associated with the post ID.
    29983024 *
     3025 * clean_post_cache() will call itself recursively for each child post.
     3026 *
     3027 * This function not run if $_wp_suspend_cache_invalidation is not empty. See
     3028 * wp_suspend_cache_invalidation().
     3029 *
    29993030 * @package WordPress
    30003031 * @subpackage Cache
    30013032 * @since 2.0.0
    30023033 *
    3003  * @uses do_action() Will call the 'clean_post_cache' hook action.
     3034 * @uses do_action() Calls 'clean_post_cache' on $id before adding children (if any).
    30043035 *
    30053036 * @param int $id The Post ID in the cache to clean
    30063037 */
     
    31753206 * @since 2.3.0
    31763207 * @access private
    31773208 * @uses $wpdb
     3209 * @uses do_action() Calls 'private_to_published' on post ID if this is a 'private_to_published' call.
     3210 * @uses wp_clear_scheduled_hook() with 'publish_future_post' and post ID.
    31783211 *
    31793212 * @param string $new_status New post status
    31803213 * @param string $old_status Previous post status
     
    32003233 * The $post properties used and must exist are 'ID' and 'post_date_gmt'.
    32013234 *
    32023235 * @since 2.3.0
     3236 * @access private
    32033237 *
    32043238 * @param int $deprecated Not Used. Can be set to null.
    32053239 * @param object $post Object type containing the post information
     
    32133247 * Hook to schedule pings and enclosures when a post is published.
    32143248 *
    32153249 * @since 2.3.0
     3250 * @access private
    32163251 * @uses $wpdb
    3217  * @uses XMLRPC_REQUEST
    3218  * @uses APP_REQUEST
    3219  * @uses do_action Calls 'xmlprc_publish_post' action if XMLRPC_REQUEST is defined. Calls 'app_publish_post'
    3220  *      action if APP_REQUEST is defined.
     3252 * @uses XMLRPC_REQUEST and APP_REQUEST constants.
     3253 * @uses do_action() Calls 'xmlprc_publish_post' on post ID if XMLRPC_REQUEST is defined.
     3254 * @uses do_action() Calls 'app_publish_post' on post ID if APP_REQUEST is defined.
    32213255 *
    32223256 * @param int $post_id The ID in the database table of the post being published
    32233257 */
     
    32523286 * property.
    32533287 *
    32543288 * @since 2.3.0
     3289 * @access private
    32553290 * @uses $wp_rewrite Flushes Rewrite Rules.
    32563291 *
    32573292 * @param int $post_id The ID in the database table for the $post
     
    32823317 * complete. The post parent will be an ancestor and the parent of the post
    32833318 * parent will be an ancestor. There will only be two ancestors at the most.
    32843319 *
     3320 * @since unknown
    32853321 * @access private
    3286  * @since unknown
    32873322 * @uses $wpdb
    32883323 *
    32893324 * @param object $_post Post data.
     
    33193354 * @subpackage Post_Revisions
    33203355 * @since 2.6.0
    33213356 * @access private
     3357 * @uses apply_filters() Calls '_wp_post_revision_fields' on 'title', 'content' and 'excerpt' fields.
    33223358 *
    33233359 * @param array $post Optional a post array to be processed for insertion as a post revision.
    33243360 * @param bool $autosave optional Is the revision an autosave?
     
    35733609/**
    35743610 * Restores a post to the specified revision.
    35753611 *
    3576  * Can restore a past using all fields of the post revision, or only selected
    3577  * fields.
     3612 * Can restore a past revision using all fields of the post revision, or only selected fields.
    35783613 *
    35793614 * @package WordPress
    35803615 * @subpackage Post_Revisions
     
    35823617 *
    35833618 * @uses wp_get_post_revision()
    35843619 * @uses wp_update_post()
     3620 * @uses do_action() Calls 'wp_restore_post_revision' on post ID and revision ID if wp_update_post()
     3621 *  is successful.
    35853622 *
    35863623 * @param int|object $revision_id Revision ID or revision object.
    3587  * @param array $fields Optional. What fields to restore from.  Defaults to all.
     3624 * @param array $fields Optional. What fields to restore from. Defaults to all.
    35883625 * @return mixed Null if error, false if no fields to restore, (int) post ID if success.
    35893626 */
    35903627function wp_restore_post_revision( $revision_id, $fields = null ) {