Ticket #3982: post-phpdoc.diff

File post-phpdoc.diff, 16.5 kB (added by m0n5t3r, 2 years ago)

post.php phpdoc take 1

  • wp-includes/post.php

    old new  
    11<?php 
    2  
    3 // 
    4 // Post functions 
    5 // 
    6  
     2/** 
     3 * Post functions 
     4 * 
     5 * @author Wordpress team (FIXME) 
     6 * @version "$Id$" 
     7 * @copyright (FIXME) 
     8 * @package wordpress 
     9 * @subpackage post 
     10 */ 
     11 
     12/** 
     13 * get metadata for an attached file 
     14 * 
     15 * @filter get_attached_file 
     16 * @param int $attachment_id attachment ID 
     17 * @param bool $unfiltered whether to applu filters or not 
     18 * @return array  
     19 */ 
    720function get_attached_file( $attachment_id, $unfiltered = false ) { 
    821        $file = get_post_meta( $attachment_id, '_wp_attached_file', true ); 
    922        if ( $unfiltered ) 
    …… 
    1124        return apply_filters( 'get_attached_file', $file, $attachment_id ); 
    1225} 
    1326 
     27/** 
     28 * update attached file metadata 
     29 * 
     30 * @filter update_attached_file 
     31 * @param int $attachment_id 
     32 * @param string $file 
     33 * @return bool 
     34 */ 
    1435function update_attached_file( $attachment_id, $file ) { 
    1536        if ( !get_post( $attachment_id ) ) 
    1637                return false; 
    …… 
    2546                return add_post_meta( $attachment_id, '_wp_attached_file', $file ); 
    2647} 
    2748 
     49/** 
     50 * get post children 
     51 * 
     52 * @param mixed $args 
     53 * @param string $output 
     54 * @return mixed 
     55 */ 
    2856function &get_children($args = '', $output = OBJECT) { 
    2957        global $post_cache, $wpdb, $blog_id; 
    3058 
    …… 
    7199        } 
    72100} 
    73101 
    74 // get extended entry info (<!--more-->) 
     102/** 
     103 * get extended entry info (<!--more-->) 
     104 * 
     105 * @param string $post 
     106 * @return array 
     107 */ 
    75108function get_extended($post) { 
    76109        //Match the new style more links 
    77110        if ( preg_match('/<!--more(.*?)-->/', $post, $matches) ) { 
    …… 
    88121        return array('main' => $main, 'extended' => $extended); 
    89122} 
    90123 
    91 // Retrieves post data given a post ID or post object. 
    92 // Handles post caching. 
     124/** 
     125 * Retrieves post data given a post ID or post object. 
     126 * Handles post caching. 
     127 * 
     128 * @param mixed &$post post ID or post object 
     129 * @param string $output 
     130 * @return mixed 
     131 */ 
    93132function &get_post(&$post, $output = OBJECT) { 
    94133        global $post_cache, $wpdb, $blog_id; 
    95134 
    …… 
    133172        } 
    134173} 
    135174 
    136 // Takes a post ID, returns its mime type. 
     175/** 
     176 * Takes a post ID, returns its mime type.  
     177 * 
     178 * @param int $ID 
     179 * @return mixed string or false 
     180 */ 
    137181function get_post_mime_type($ID = '') { 
    138182        $post = & get_post($ID); 
    139183 
    …… 
    143187        return false; 
    144188} 
    145189 
     190/** 
     191 * Takes a post ID and returns its status 
     192 * 
     193 * @param int $ID 
     194 * @return mixed post status or false 
     195 */ 
    146196function get_post_status($ID = '') { 
    147197        $post = get_post($ID); 
    148198 
    …… 
    156206        return false; 
    157207} 
    158208 
     209/** 
     210 * Returns post type 
     211 * 
     212 * @param mixed $post post object or post ID 
     213 * @return mixed post type or false 
     214 */ 
    159215function get_post_type($post = false) { 
    160216        global $wpdb, $posts; 
    161217 
    …… 
    170226        return false; 
    171227} 
    172228 
     229/** 
     230 * returns a number of posts 
     231 * 
     232 * @param array $args 
     233 * @return array  
     234 */ 
    173235function get_posts($args) { 
    174236        global $wpdb; 
    175237 
    …… 
    254316        return $posts; 
    255317} 
    256318 
    257 // 
    258 // Post meta functions 
    259 // 
    260  
     319/** 
     320 * adds metadata for post 
     321 *  
     322 * @param int $post_id post ID 
     323 * @param string $key  
     324 * @param mixed $value  
     325 * @param bool $unique whether to check for a value with the same key 
     326 * @return bool 
     327 */ 
    261328function add_post_meta($post_id, $key, $value, $unique = false) { 
    262329        global $wpdb, $post_meta_cache, $blog_id; 
    263330 
    …… 
    279346        return true; 
    280347} 
    281348 
     349/** 
     350 * delete post metadata 
     351 *  
     352 * @param int $post_id post ID 
     353 * @param string $key  
     354 * @param mixed $value  
     355 * @return bool 
     356 */ 
    282357function delete_post_meta($post_id, $key, $value = '') { 
    283358        global $wpdb, $post_meta_cache, $blog_id; 
    284359 
    …… 
    309384        return true; 
    310385} 
    311386 
     387/** 
     388 * get a post meta field 
     389 *  
     390 * @param int $post_id post ID 
     391 * @param string $key  
     392 * @param bool $single whether to return a single value 
     393 * @return mixed 
     394 */ 
    312395function get_post_meta($post_id, $key, $single = false) { 
    313396        global $wpdb, $post_meta_cache, $blog_id; 
    314397 
    …… 
    335418        } 
    336419} 
    337420 
     421/** 
     422 * update a post meta field 
     423 *  
     424 * @param int $post_id post ID 
     425 * @param string $key  
     426 * @param mixed $value  
     427 * @param mixed $prev_value previous value (for differentiating between meta fields with the same key and post ID) 
     428 * @return bool 
     429 */ 
    338430function update_post_meta($post_id, $key, $value, $prev_value = '') { 
    339431        global $wpdb, $post_meta_cache, $blog_id; 
    340432 
    …… 
    371463} 
    372464 
    373465 
     466/** 
     467 * retrieve post custom fields 
     468 *  
     469 * @param int $post_id post ID 
     470 * @return array 
     471 */ 
    374472function get_post_custom($post_id = 0) { 
    375473        global $id, $post_meta_cache, $wpdb, $blog_id; 
    376474 
    …… 
    385483        return $post_meta_cache[$blog_id][$post_id]; 
    386484} 
    387485 
     486/** 
     487 * retrieve post custom field names 
     488 *  
     489 * @param int $post_id post ID 
     490 * @return array 
     491 */ 
    388492function get_post_custom_keys( $post_id = 0 ) { 
    389493        $custom = get_post_custom( $post_id ); 
    390494 
    …… 
    396500} 
    397501 
    398502 
     503/** 
     504 * retrieve values for a custom post field 
     505 *  
     506 * @param string $key field name 
     507 * @param int $post_id post ID 
     508 * @return mixed 
     509 */ 
    399510function get_post_custom_values( $key = '', $post_id = 0 ) { 
    400511        $custom = get_post_custom($post_id); 
    401512 
    402513        return $custom[$key]; 
    403514} 
    404515 
     516/** 
     517 * delete post 
     518 *  
     519 * @action delete_post 
     520 * @action edit_category 
     521 * @param int $postid post ID 
     522 * @return mixed 
     523 */ 
    405524function wp_delete_post($postid = 0) { 
    406525        global $wpdb, $wp_rewrite; 
    407526        $postid = (int) $postid; 
    …… 
    446565        return $post; 
    447566} 
    448567 
     568/** 
     569 * retrieve the list of categories for a post 
     570 *  
     571 * @param int $post_id post ID 
     572 * @return array 
     573 */ 
    449574function wp_get_post_categories($post_id = 0) { 
    450575        $cats = &get_the_category($post_id); 
    451576        $cat_ids = array(); 
    …… 
    454579        return array_unique($cat_ids); 
    455580} 
    456581 
     582/** 
     583 * get the $num most recent posts 
     584 *  
     585 * @param int $num number of posts to get 
     586 * @return array 
     587 */ 
    457588function wp_get_recent_posts($num = 10) { 
    458589        global $wpdb; 
    459590 
    …… 
    468599        return $result?$result:array(); 
    469600} 
    470601 
     602/** 
     603 * get one post 
     604 *  
     605 * @param int $postid post ID 
     606 * @param string $mode what to return 
     607 * @return mixed 
     608 */ 
    471609function wp_get_single_post($postid = 0, $mode = OBJECT) { 
    472610        global $wpdb; 
    473611 
    …… 
    484622        return $post; 
    485623} 
    486624 
     625/** 
     626 * insert a post 
     627 * 
     628 * @filter content_save_pre 
     629 * @filter content_filtered_save_pre 
     630 * @filter excerpt_save_pre 
     631 * @filter title_save_pre 
     632 * @filter category_save_pre 
     633 * @filter status_save_pre 
     634 * @filter name_save_pre 
     635 * @filter comment_status_pre 
     636 * @filter ping_status_pre 
     637 * @action private_to_published 
     638 * @action edit_post 
     639 * @action publish_post 
     640 * @action xmlrpc_publish_post 
     641 * @action app_publish_post 
     642 * @action publish_page 
     643 * @action save_post 
     644 * @action wp_insert_post 
     645 * @param array $postarr post contents 
     646 * @return int post ID or 0 on error 
     647 */ 
    487648function wp_insert_post($postarr = array()) { 
    488649        global $wpdb, $wp_rewrite, $allowedtags, $user_ID; 
    489650 
    …… 
    712873        return $post_ID; 
    713874} 
    714875 
     876/** 
     877 * update a post 
     878 *  
     879 * @param array $postarr post data 
     880 * @return int 
     881 */ 
    715882function wp_update_post($postarr = array()) { 
    716883        global $wpdb; 
    717884 
    …… 
    752919        return wp_insert_post($postarr); 
    753920} 
    754921 
     922/** 
     923 * mark a post as "published" 
     924 *  
     925 * @param int $post_id post ID 
     926 * @return mixed int or void 
     927 */ 
    755928function wp_publish_post($post_id) { 
    756929        $post = get_post($post_id); 
    757930 
    758         if ( empty($post) ) 
     931        if ( empty($post) ) //FIXME: inconsistent error handling, should return 0 
    759932                return; 
    760933 
    761934        if ( 'publish' == $post->post_status ) 
    …… 
    764937        return wp_update_post(array('post_status' => 'publish', 'ID' => $post_id, 'no_filter' => true)); 
    765938} 
    766939 
     940/** 
     941 * set categories for a post 
     942 * 
     943 * @action edit_category 
     944 * @param int $post_ID post ID 
     945 * @param array $post_categories  
     946 */ 
    767947function wp_set_post_categories($post_ID = 0, $post_categories = array()) { 
    768948        global $wpdb; 
    769949        // If $post_categories isn't already an array, make it one: 
    …… 
    8201000        } 
    8211001}       // wp_set_post_categories() 
    8221002 
    823 // 
    824 // Trackback and ping functions 
    825 // 
     1003/** 
     1004 * Trackback and ping functions 
     1005 */ 
    8261006 
    827 function add_ping($post_id, $uri) { // Add a URL to those already pung 
     1007/** 
     1008 * add URL to the pinged URLs list 
     1009 * 
     1010 * @filter add_ping 
     1011 * @param int $post_id post ID 
     1012 * @param string $uri  
     1013 * @return mixed 
     1014 */ 
     1015function add_ping($post_id, $uri) {  
    8281016        global $wpdb; 
    8291017        $pung = $wpdb->get_var("SELECT pinged FROM $wpdb->posts WHERE ID = $post_id"); 
    8301018        $pung = trim($pung); 
    …… 
    8351023        return $wpdb->query("UPDATE $wpdb->posts SET pinged = '$new' WHERE ID = $post_id"); 
    8361024} 
    8371025 
    838 function get_enclosed($post_id) { // Get enclosures already enclosed for a post 
     1026/** 
     1027 * Get enclosures already enclosed for a post 
     1028 * 
     1029 * @filter get_enclosed 
     1030 * @param int $post_id post ID 
     1031 * @return array 
     1032 */ 
     1033function get_enclosed($post_id) { 
    8391034        global $wpdb; 
    8401035        $custom_fields = get_post_custom( $post_id ); 
    8411036        $pung = array(); 
    …… 
    8541049        return $pung; 
    8551050} 
    8561051 
    857 function get_pung($post_id) { // Get URLs already pung for a post 
     1052/** 
     1053 * Get URLs already pinged for a post 
     1054 * 
     1055 * @filter get_pung 
     1056 * @param int $post_id post ID 
     1057 * @return array 
     1058 */ 
     1059function get_pung($post_id) { 
    8581060        global $wpdb; 
    8591061        $pung = $wpdb->get_var("SELECT pinged FROM $wpdb->posts WHERE ID = $post_id"); 
    8601062        $pung = trim($pung); 
    …… 
    8631065        return $pung; 
    8641066} 
    8651067 
    866 function get_to_ping($post_id) { // Get any URLs in the todo list 
     1068/** 
     1069 * Get any URLs in the todo list 
     1070 * 
     1071 * @filter get_to_ping 
     1072 * @param int $post_id post ID 
     1073 * @return array 
     1074 */ 
     1075function get_to_ping($post_id) { 
    8671076        global $wpdb; 
    8681077        $to_ping = $wpdb->get_var("SELECT to_ping FROM $wpdb->posts WHERE ID = $post_id"); 
    8691078        $to_ping = trim($to_ping); 
    …… 
    8721081        return $to_ping; 
    8731082} 
    8741083 
    875 // do trackbacks for a list of urls 
    876 // accepts a comma-separated list of trackback urls and a post id 
     1084/** 
     1085 * do trackbacks for a list of urls 
     1086 *  
     1087 * @param string $tb_list comma separated list of URLs 
     1088 * @param int $post_id post ID 
     1089 */ 
    8771090function trackback_url_list($tb_list, $post_id) { 
    8781091        if (!empty($tb_list)) { 
    8791092                // get post data 
    …… 
    8971110                } 
    8981111} 
    8991112 
    900 // 
    901 // Page functions 
    902 // 
     1113/** 
     1114 * Page functions 
     1115 */ 
    9031116 
     1117/** 
     1118 * get a list of page IDs 
     1119 * handles caching 
     1120 *  
     1121 * @return array 
     1122 */ 
    9041123function get_all_page_ids() { 
    9051124        global $wpdb; 
    9061125 
    …… 
    9131132} 
    9141133 
    9151134 
    916 // Retrieves page data given a page ID or page object. 
    917 // Handles page caching. 
     1135/** 
     1136 * retrieves page data given a page ID or page object 
     1137 *  
     1138 * @param mixed &$page page object or page ID 
     1139 * @param string $output what to output 
     1140 * @return mixed 
     1141 */ 
    9181142function &get_page(&$page, $output = OBJECT) { 
    9191143        global $wpdb, $blog_id; 
    9201144 
    …… 
    9671191        } 
    9681192} 
    9691193 
     1194/** 
     1195 * retrieves a page given its path 
     1196 *  
     1197 * @param string $page_path page path 
     1198 * @param string $output output type 
     1199 * @return mixed 
     1200 */ 
    9701201function get_page_by_path($page_path, $output = OBJECT) { 
    9711202        global $wpdb; 
    9721203        $page_path = rawurlencode(urldecode($page_path)); 
    …… 
    9981229        return NULL; 
    9991230} 
    10001231 
     1232/** 
     1233 * retrieve a page given its title  
     1234 *  
     1235 * @param string $page_title page title  
     1236 * @param string $output output type 
     1237 * @return mixed 
     1238 */ 
    10011239function get_page_by_title($page_title, $output = OBJECT) { 
    10021240        global $wpdb; 
    10031241        $page_title = $wpdb->escape($page_title); 
    …… 
    10081246        return NULL; 
    10091247} 
    10101248 
     1249/** 
     1250 * retrieve child pages 
     1251 *  
     1252 * @param int $page_id page ID 
     1253 * @param array $pages list of pages 
     1254 * @return array 
     1255 */ 
    10111256function &get_page_children($page_id, $pages) { 
    10121257        global $page_cache, $blog_id; 
    10131258 
    …… 
    10251270        return $page_list; 
    10261271} 
    10271272 
    1028 //fetches the pages returned as a FLAT list, but arranged in order of their hierarchy, i.e., child parents 
    1029 //immediately follow their parents 
     1273/** 
     1274 * fetches the pages returned as a FLAT list, but arranged in order of their hierarchy, i.e., child parents 
     1275 * immediately follow their parents 
     1276 *  
     1277 * @param array $posts posts array 
     1278 * @param int $parent parent page ID 
     1279 * @return array 
     1280 */ 
    10301281function get_page_hierarchy($posts, $parent = 0) { 
    10311282        $result = array ( ); 
    10321283        if ($posts) { foreach ($posts as $post) { 
    …… 
    10391290        return $result; 
    10401291} 
    10411292 
     1293/** 
     1294 * builds a page URI 
     1295 *  
     1296 * @param int $page_id page ID 
     1297 * @return string 
     1298 */ 
    10421299function get_page_uri($page_id) { 
    10431300        $page = get_page($page_id); 
    10441301        $uri = urldecode($page->post_name); 
    …… 
    10551312        return $uri; 
    10561313} 
    10571314 
     1315/** 
     1316 * retrieve a list of pages 
     1317 * 
     1318 * @filter get_pages 
     1319 * @param mixed $args array or query string 
     1320 * @return array 
     1321 */ 
    10581322function &get_pages($args = '') { 
    10591323        global $wpdb; 
    10601324 
    …… 
    11581422        return $pages; 
    11591423} 
    11601424 
     1425/** 
     1426 * build page URI index 
     1427 *  
     1428 */ 
    11611429function generate_page_uri_index() { 
    11621430        global $wpdb; 
    11631431 
    …… 
    11961464        } 
    11971465} 
    11981466 
    1199 // 
    1200 // Attachment functions 
    1201 // 
     1467/** 
     1468 * Attachment functions 
     1469 */ 
    12021470 
     1471/** 
     1472 * check if the attachment URI is a local one and it is really an attachment 
     1473 *  
     1474 * @param string $url URL to check 
     1475 * @return bool 
     1476 */ 
    12031477function is_local_attachment($url) { 
    12041478        if (strpos($url, get_bloginfo('url')) === false) 
    12051479                return false; 
    …… 
    12131487        return false; 
    12141488} 
    12151489 
     1490/** 
     1491 * insert an attachment 
     1492 * 
     1493 * @filter content_save_pre 
     1494 * @filter content_filtered_save_pre 
     1495 * @filter excerpt_save_pre 
     1496 * @filter title_save_pre 
     1497 * @filter category_save_pre 
     1498 * @filter name_save_pre 
     1499 * @filter comment_status_pre 
     1500 * @filter ping_status_pre 
     1501 * @filter post_mime_type_pre 
     1502 * @action edit_attachment 
     1503 * @action add_attachment 
     1504 * @param object $object attachment object 
     1505 * @param string $file filename 
     1506 * @param int $post_parent parent post ID 
     1507 * @return int 
     1508 */ 
    12161509function wp_insert_attachment($object, $file = false, $post_parent = 0) { 
    12171510        global $wpdb, $user_ID; 
    12181511 
    …… 
    13681661        return $post_ID; 
    13691662} 
    13701663 
     1664/** 
     1665 * delete an attachment 
     1666 * 
     1667 * @filter wp_delete_file 
     1668 * @action delete_attachment 
     1669 * @param int $postid attachment Id 
     1670 * @return mixed 
     1671 */ 
    13711672function wp_delete_attachment($postid) { 
    13721673        global $wpdb; 
    13731674        $postid = (int) $postid; 
    …… 
    14081709        return $post; 
    14091710} 
    14101711 
     1712/** 
     1713 * retrieve metadata for an attachment 
     1714 * 
     1715 * @filter wp_get_attachment_metadata 
     1716 * @param int $post_id attachment ID 
     1717 * @param bool $unfiltered if true, filters are not ran 
     1718 * @return array 
     1719 */ 
    14111720function wp_get_attachment_metadata( $post_id, $unfiltered = false ) { 
    14121721        $post_id = (int) $post_id; 
    14131722        if ( !$post =& get_post( $post_id ) ) 
    …… 
    14191728        return apply_filters( 'wp_get_attachment_metadata', $data, $post->ID ); 
    14201729} 
    14211730 
     1731/** 
     1732 * update metadata for an attachment 
     1733 * 
     1734 * @filter wp_update_attachment_metadata 
     1735 * @param int $post_id attachment ID 
     1736 * @param array $data attachment data 
     1737 * @return int 
     1738 */ 
    14221739function wp_update_attachment_metadata( $post_id, $data ) { 
    14231740        $post_id = (int) $post_id; 
    14241741        if ( !$post =& get_post( $post_id ) ) 
    …… 
    14341751                return add_post_meta( $post->ID, '_wp_attachment_metadata', $data ); 
    14351752} 
    14361753 
     1754/** 
     1755 * retrieve the URL for an attachment 
     1756 *  
     1757 * @filter wp_get_attachment_url 
     1758 * @param int $post_id attachment ID 
     1759 * @return string 
     1760 */ 
    14371761function wp_get_attachment_url( $post_id = 0 ) { 
    14381762        $post_id = (int) $post_id; 
    14391763        if ( !$post =& get_post( $post_id ) ) 
    …… 
    14471771        return apply_filters( 'wp_get_attachment_url', $url, $post->ID ); 
    14481772} 
    14491773 
     1774/** 
     1775 * retrieve thumbnail for an attachment 
     1776 * 
     1777 * @filter wp_get_attachment_thumb_file 
     1778 * @param int $post_id attachment ID 
     1779 * @return mixed 
     1780 */ 
    14501781function wp_get_attachment_thumb_file( $post_id = 0 ) { 
    14511782        $post_id = (int) $post_id; 
    14521783        if ( !$post =& get_post( $post_id ) ) 
    …… 
    14611792        return false; 
    14621793} 
    14631794 
     1795/** 
     1796 * retrieve URL for an attachment thumbnail 
     1797 * 
     1798 * @filter wp_get_attachment_thumb_url 
     1799 * @param int $post_id attachment ID 
     1800 * @return string 
     1801 */ 
    14641802function wp_get_attachment_thumb_url( $post_id = 0 ) { 
    14651803        $post_id = (int) $post_id; 
    14661804        if ( !$post =& get_post( $post_id ) ) 
    …… 
    14761814        return apply_filters( 'wp_get_attachment_thumb_url', $url, $post->ID ); 
    14771815} 
    14781816 
     1817/** 
     1818 * check if the attachment is an image 
     1819 *  
     1820 * @param int $post_id attachment ID 
     1821 * @return bool 
     1822 */ 
    14791823function wp_attachment_is_image( $post_id = 0 ) { 
    14801824        $post_id = (int) $post_id; 
    14811825        if ( !$post =& get_post( $post_id ) ) 
    …… 
    14931837        return false; 
    14941838} 
    14951839 
     1840/** 
     1841 * retrieve the icon for a MIME type 
     1842 * 
     1843 * @filter icon_dir 
     1844 * @filter icon_dir_uri 
     1845 * @filter wp_mime_type_icon 
     1846 * @param string $mime MIME type 
     1847 * @return string 
     1848 */ 
    14961849function wp_mime_type_icon( $mime = 0 ) { 
    14971850        $post_id = 0; 
    14981851        if ( is_numeric($mime) ) { 
    …… 
    15321885        return apply_filters( 'wp_mime_type_icon', $src, $mime, $post_id ); // Last arg is 0 if function pass mime type. 
    15331886} 
    15341887 
     1888/** 
     1889 * store slug history as custom fields; only looks at published posts 
     1890 *  
     1891 * @param int $post_id post ID 
     1892 * @return int 
     1893 */ 
    15351894function wp_check_for_changed_slugs($post_id) { 
    15361895        if ( !strlen($_POST['wp-old-slug']) ) 
    15371896                return $post_id;