WordPress.org

Make WordPress Core

Changeset 8203


Ignore:
Timestamp:
06/27/08 15:32:57 (6 years ago)
Author:
ryan
Message:

phpdoc updates for post.php from jacobsantos. fixes #3982

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/post.php

    r8173 r8203  
    1313 
    1414/** 
    15  * get_attached_file() - Get metadata for an attached file 
    16  * 
    17  * {@internal Missing Long Description}} 
     15 * Retrieve attached file path based on attachment ID. 
     16 * 
     17 * You can optionally send it through the 'get_attached_file' filter, but by 
     18 * default it will just return the file path unfiltered. 
     19 * 
     20 * The function works by getting the single post meta name, named 
     21 * '_wp_attached_file' and returning it. This is a convenience function to 
     22 * prevent looking up the meta name and provide a mechanism for sending the 
     23 * attached filename through a filter. 
    1824 * 
    1925 * @package WordPress 
    2026 * @subpackage Post 
    2127 * @since 2.0 
     28 * @uses apply_filters() Calls 'get_attached_file' on file path and attachment ID 
    2229 * 
    2330 * @param int $attachment_id Attachment ID 
    2431 * @param bool $unfiltered Whether to apply filters or not 
    25  * @return array {@internal Missing Description}} 
     32 * @return string The file path to the attached file. 
    2633 */ 
    2734function get_attached_file( $attachment_id, $unfiltered = false ) { 
     
    3340 
    3441/** 
    35  * update_attached_file() - Update attached file metadata 
    36  * 
    37  * {@internal Missing Long Description}} 
     42 * Update attachment file path based on attachment ID. 
     43 * 
     44 * Used to update the file path of the attachment, which uses post meta name 
     45 * '_wp_attached_file' to store the path of the attachment. 
    3846 * 
    3947 * @package WordPress 
    4048 * @subpackage Post 
    4149 * @since 2.1 
     50 * @uses apply_filters() Calls 'update_attached_file' on file path and attachment ID 
    4251 * 
    4352 * @param int $attachment_id Attachment ID 
    44  * @param string $file {@internal Missing Description}} 
    45  * @return bool|mixed {@internal Missing Description}} 
     53 * @param string $file File path for the attachment 
     54 * @return bool False on failure, true on success. 
    4655 */ 
    4756function update_attached_file( $attachment_id, $file ) { 
     
    5564 
    5665/** 
    57  * get_children() - Get post children 
    58  * 
    59  * {@internal Missing Long Description}} 
     66 * Retrieve all children of the post parent ID. 
     67 * 
     68 * Normally, without any enhancements, the children would apply to pages. In the 
     69 * context of the inner workings of WordPress, pages, posts, and attachments 
     70 * share the same table, so therefore the functionality could apply to any one 
     71 * of them. It is then noted that while this function does not work on posts, it 
     72 * does not mean that it won't work on posts. It is recommended that you know 
     73 * what context you wish to retrieve the children of. 
     74 * 
     75 * Attachments may also be made the child of a post, so if that is an accurate 
     76 * statement (which needs to be verified), it would then be possible to get 
     77 * all of the attachments for a post. Attachments have since changed since 
     78 * version 2.5, so this is most likely unaccurate, but serves generally as an 
     79 * example of what is possible. 
     80 * 
     81 * 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. 
     86 * 
     87 * The 'post_parent' is the most important argument and important attention 
     88 * needs to be paid to the $args parameter. If you pass either an object or an 
     89 * integer (number), then just the 'post_parent' is grabbed and everything else 
     90 * is lost. If you don't specify any arguments, then it is assumed that you are 
     91 * in The Loop and the post parent will be grabbed for from the current post. 
     92 * 
     93 * The 'post_parent' argument is the ID to get the children. The 'numberposts' 
     94 * is the amount of posts to retrieve that has a default of '-1', which is 
     95 * used to get all of the posts. Giving a number higher than 0 will only 
     96 * retrieve that amount of posts. 
     97 * 
     98 * The 'post_type' and 'post_status' arguments can be used to choose what 
     99 * criteria of posts to retrieve. The 'post_type' can be anything, but WordPress 
     100 * post types are 'post', 'pages', and 'attachments'. The 'post_status' 
     101 * argument will accept any post status within the write administration panels. 
     102 * 
     103 * @see get_posts() Has additional arguments that can be replaced. 
     104 * @internal Claims made in the long description might be inaccurate. 
    60105 * 
    61106 * @package WordPress 
     
    63108 * @since 2.0 
    64109 * 
    65  * @param mixed $args {@internal Missing Description}} 
    66  * @param string $output {@internal Missing Description}} 
    67  * @return mixed {@internal Missing Description}} 
     110 * @param mixed $args Optional. User defined arguments for replacing the defaults. 
     111 * @param string $output Optional. Constant for return type, either OBJECT (default), ARRAY_A, ARRAY_N. 
     112 * @return array|bool False on failure and the type will be determined by $output parameter. 
    68113 */ 
    69114function &get_children($args = '', $output = OBJECT) { 
     
    112157 
    113158/** 
    114  * get_extended() - get extended entry info (<!--more-->) 
    115  * 
    116  * {@internal Missing Long Description}} 
    117  * 
    118  * @package WordPress 
    119  * @subpackage Post 
    120  * @since 1.0.1 
     159 * get_extended() - Get extended entry info (<!--more-->) 
     160 * 
     161 * {@internal Missing Long Description}} 
     162 * 
     163 * @package WordPress 
     164 * @subpackage Post 
     165 * @since 1.0.0 
    121166 * 
    122167 * @param string $post {@internal Missing Description}} 
     
    148193 * @since 1.5.1 
    149194 * @uses $wpdb 
     195 * @link http://codex.wordpress.org/Function_Reference/get_post 
    150196 * 
    151197 * @param int|object &$post post ID or post object 
     
    194240 
    195241/** 
    196  * get_post_ancestors() - Retrieve ancestors for a post 
     242 * Retrieve ancestors of a post. 
    197243 * 
    198244 * @package WordPress 
     
    200246 * @since 2.5 
    201247 * 
    202  * @param int|object $post post ID or post object 
    203  * @return array of ancestor IDs 
     248 * @param int|object $post Post ID or post object 
     249 * @return array Ancestor IDs or empty array if none are found. 
    204250 */ 
    205251function get_post_ancestors($post) { 
     
    213259 
    214260/** 
    215  * get_post_field() - Retrieve a field based on a post ID. 
     261 * Retrieve data from a post field based on Post ID. 
     262 * 
     263 * Examples of the post field will be, 'post_type', 'post_status', 'content', 
     264 * etc and based off of the post object property or key names. 
     265 * 
     266 * The context values are based off of the taxonomy filter functions and 
     267 * supported values are found within those functions. 
    216268 * 
    217269 * @package WordPress 
    218270 * @subpackage Post 
    219271 * @since 2.3 
    220  * 
    221  * @param string $field {@internal Missing Description}} 
     272 * @uses sanitize_post_field() See for possible $context values. 
     273 * 
     274 * @param string $field Post field name 
    222275 * @param id $post Post ID 
    223  * @param string $context Optional. How to filter the field 
     276 * @param string $context Optional. How to filter the field. Default is display. 
    224277 * @return WP_Error|string Value in post field or WP_Error on failure 
    225278 */ 
     
    241294 
    242295/** 
    243  * get_post_mime_type() - Takes a post ID, returns its mime type. 
     296 * Retrieve the mime type of an attachment based on the ID. 
     297 * 
     298 * This function can be used with any post type, but it makes more sense with 
     299 * attachments. 
    244300 * 
    245301 * @package WordPress 
     
    247303 * @since 2.0 
    248304 * 
    249  * @param int $ID Post ID 
     305 * @param int $ID Optional. Post ID. 
    250306 * @return bool|string False on failure or returns the mime type 
    251307 */ 
     
    260316 
    261317/** 
    262  * get_post_status() - Takes a post ID and returns its status 
    263  * 
    264  * {@internal Missing Long Description}} 
     318 * Retrieve the post status based on the Post ID. 
     319 * 
     320 * If the post ID is of an attachment, then the parent post status will be given 
     321 * instead. 
    265322 * 
    266323 * @package WordPress 
     
    268325 * @since 2.0 
    269326 * 
    270  * @param int $ID {@internal Missing Description}} 
    271  * @return string|bool post status or false 
     327 * @param int $ID Post ID 
     328 * @return string|bool Post status or false on failure. 
    272329 */ 
    273330function get_post_status($ID = '') { 
     
    285342 
    286343/** 
    287  * get_post_statuses( ) - Retuns the possible user post status values 
     344 * Retrieve all of the WordPress supported post statuses. 
    288345 * 
    289346 * Posts have a limited set of valid status values, this provides the 
     
    294351 * @since 2.5 
    295352 * 
    296  * @return array 
     353 * @return array List of post statuses. 
    297354 */ 
    298355function get_post_statuses( ) { 
     
    308365 
    309366/** 
    310  * get_page_statuses( ) - Retuns the possible user page status values 
     367 * Retrieve all of the WordPress support page statuses. 
    311368 * 
    312369 * Pages have a limited set of valid status values, this provides the 
     
    317374 * @since 2.5 
    318375 * 
    319  * @return array 
     376 * @return array List of page statuses. 
    320377 */ 
    321378function get_page_statuses( ) { 
     
    397454 * @since 1.2 
    398455 * @uses $wpdb 
     456 * @link http://codex.wordpress.org/Template_Tags/get_posts 
    399457 * 
    400458 * @param array $args {@internal Missing Description}} 
     
    443501 * @since 1.5 
    444502 * @uses $wpdb 
     503 * @link http://codex.wordpress.org/Function_Reference/add_post_meta 
    445504 * 
    446505 * @param int $post_id post ID 
     
    477536 * @since 1.5 
    478537 * @uses $wpdb 
     538 * @link http://codex.wordpress.org/Function_Reference/delete_post_meta 
    479539 * 
    480540 * @param int $post_id post ID 
     
    519579 * @since 1.5 
    520580 * @uses $wpdb 
     581 * @link http://codex.wordpress.org/Function_Reference/get_post_meta 
    521582 * 
    522583 * @param int $post_id post ID 
     
    562623 * @since 1.5 
    563624 * @uses $wpdb 
     625 * @link http://codex.wordpress.org/Function_Reference/update_post_meta 
    564626 * 
    565627 * @param int $post_id post ID 
     
    623685 * @subpackage Post 
    624686 * @since 1.2 
     687 * @link http://codex.wordpress.org/Function_Reference/get_post_custom 
    625688 * 
    626689 * @uses $id 
     
    650713 * @subpackage Post 
    651714 * @since 1.2 
     715 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_keys 
    652716 * 
    653717 * @param int $post_id post ID 
     
    664728} 
    665729 
    666  
     730/** 
     731 * get_post_custom_values() - Retrieve values for a custom post field 
     732 * 
     733 * @package WordPress 
     734 * @subpackage Post 
     735 * @since 1.2 
     736 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_values 
     737 * 
     738 * @param string $key field name 
     739 * @param int $post_id post ID 
     740 * @return mixed {@internal Missing Description}} 
     741 */ 
    667742function get_post_custom_values( $key = '', $post_id = 0 ) { 
    668743    $custom = get_post_custom($post_id); 
     
    671746} 
    672747 
     748/** 
     749 * sanitize_post() - Sanitize every post field 
     750 * 
     751 * {@internal Missing Long Description}} 
     752 * 
     753 * @package WordPress 
     754 * @subpackage Post 
     755 * @since 2.3 
     756 * 
     757 * @param object|array $post The Post Object or Array 
     758 * @param string $context How to sanitize post fields 
     759 * @return object|array The now sanitized Post Object or Array (will be the same type as $post) 
     760 */ 
    673761function sanitize_post($post, $context = 'display') { 
    674762    if ( 'raw' == $context ) 
     
    757845 
    758846/** 
    759  * Count number of posts of a post type and is permissible. 
    760  * 
    761  * This function provides an efficient method of finding the amount 
    762  * of post's type a blog has. Another method is to count the amount 
    763  * of items in get_posts(), but that method has a lot of overhead 
    764  * with doing so. Therefore, when developing for 2.5+, use this 
    765  * function instead. 
    766  * 
    767  * The $perm parameter checks for 'readable' value and if the user 
    768  * can read private posts, it will display that for the user that 
    769  * is signed in. 
     847 * Count number of posts of a post type and is user has permissions to view. 
     848 * 
     849 * This function provides an efficient method of finding the amount of post's 
     850 * type a blog has. Another method is to count the amount of items in 
     851 * get_posts(), but that method has a lot of overhead with doing so. Therefore, 
     852 * when developing for 2.5+, use this function instead. 
     853 * 
     854 * The $perm parameter checks for 'readable' value and if the user can read 
     855 * private posts, it will display that for the user that is signed in. 
    770856 * 
    771857 * @package WordPress 
     
    9301016 * @package WordPress 
    9311017 * @subpackage Post 
    932  * @since 1.0.1 
     1018 * @since 1.0.0 
    9331019 * 
    9341020 * @param int $postid post ID 
     
    10581144 * @package WordPress 
    10591145 * @subpackage Post 
    1060  * @since 1.0.1 
     1146 * @since 1.0.0 
    10611147 * 
    10621148 * @param int $num number of posts to get 
     
    10851171 * @package WordPress 
    10861172 * @subpackage Post 
    1087  * @since 1.0.1 
     1173 * @since 1.0.0 
    10881174 * @uses $wpdb 
    10891175 * 
     
    11171203 * @package WordPress 
    11181204 * @subpackage Post 
    1119  * @since 1.0.1 
     1205 * @since 1.0.0 
    11201206 * 
    11211207 * @uses $wpdb 
     
    13371423 * @package WordPress 
    13381424 * @subpackage Post 
    1339  * @since 1.0.1 
     1425 * @since 1.0.0 
    13401426 * @uses $wpdb 
    13411427 * 
     
    14501536} 
    14511537 
     1538/** 
     1539 * wp_add_post_tags() - Adds the tags to a post 
     1540 * 
     1541 * @uses wp_set_post_tags() Same first two paraeters, but the last parameter is always set to true. 
     1542 * 
     1543 * @package WordPress 
     1544 * @subpackage Post 
     1545 * @since 2.3 
     1546 * 
     1547 * @param int $post_id Optional. Post ID 
     1548 * @param string $tags The tags to set for the post 
     1549 * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise 
     1550 */ 
    14521551function wp_add_post_tags($post_id = 0, $tags = '') { 
    14531552    return wp_set_post_tags($post_id, $tags, true); 
    14541553} 
    14551554 
     1555/** 
     1556 * wp_set_post_tags() - Set the tags for a post 
     1557 * 
     1558 * {@internal Missing Long Description}} 
     1559 * 
     1560 * @package WordPress 
     1561 * @subpackage Post 
     1562 * @since 2.3 
     1563 * @uses $wpdb 
     1564 * 
     1565 * @param int $post_id post ID 
     1566 * @param string $tags The tags to set for the post 
     1567 * @param bool $append If true, don't delete existing tags, just add on. If false, replace the tags with the new tags. 
     1568 * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise 
     1569 */ 
    14561570function wp_set_post_tags( $post_id = 0, $tags = '', $append = false ) { 
    1457     /* $append - true = don't delete existing tags, just add on, false = replace the tags with the new tags */ 
    14581571 
    14591572    $post_id = (int) $post_id; 
     
    15481661} 
    15491662 
    1550 function get_enclosed($post_id) { // Get enclosures already enclosed for a post 
     1663/** 
     1664 * get_enclosed() - Get enclosures already enclosed for a post 
     1665 * 
     1666 * {@internal Missing Long Description}} 
     1667 * 
     1668 * @package WordPress 
     1669 * @subpackage Post 
     1670 * @since 1.5 
     1671 * @uses $wpdb 
     1672 * 
     1673 * @param int $post_id post ID 
     1674 * @return array {@internal Missing Description}} 
     1675 */ 
     1676function get_enclosed($post_id) { 
    15511677    $custom_fields = get_post_custom( $post_id ); 
    15521678    $pung = array(); 
     
    16171743 * @package WordPress 
    16181744 * @subpackage Post 
    1619  * @since 1.0.1 
     1745 * @since 1.0.0 
    16201746 * 
    16211747 * @param string $tb_list comma separated list of URLs 
Note: See TracChangeset for help on using the changeset viewer.