Ticket #8805: 8805.3.diff

File 8805.3.diff, 15.6 KB (added by CharlesClarkson, 3 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 ) {