Changeset 6379

Show
Ignore:
Timestamp:
12/14/07 00:28:34 (9 months ago)
Author:
ryan
Message:

post phpdoc from m0n5t3r and darkdragon. see #3982

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/wp-includes/post.php

    r6377 r6379  
    11<?php 
    2  
    3 // 
    4 // Post functions 
    5 // 
    6  
     2/** 
     3 * Post functions and post utility function 
     4 * 
     5 * @package WordPress 
     6 * @subpackage Post 
     7 * @since 1.5 
     8 */ 
     9 
     10/** 
     11 * get_attached_file() - Get metadata for an attached file 
     12 * 
     13 * {@internal Missing Long Description}} 
     14 * 
     15 * @package WordPress 
     16 * @subpackage Post 
     17 * @since 2.0 
     18 * 
     19 * @param int $attachment_id Attachment ID 
     20 * @param bool $unfiltered Whether to apply filters or not 
     21 * @return array {@internal Missing Description}} 
     22 */ 
    723function get_attached_file( $attachment_id, $unfiltered = false ) { 
    824    $file = get_post_meta( $attachment_id, '_wp_attached_file', true ); 
    …… 
    1228} 
    1329 
     30/** 
     31 * update_attached_file() - Update attached file metadata 
     32 * 
     33 * {@internal Missing Long Description}} 
     34 * 
     35 * @package WordPress 
     36 * @subpackage Post 
     37 * @since 2.1 
     38 * 
     39 * @param int $attachment_id Attachment ID 
     40 * @param string $file {@internal Missing Description}} 
     41 * @return bool|mixed {@internal Missing Description}} 
     42 */ 
    1443function update_attached_file( $attachment_id, $file ) { 
    1544    if ( !get_post( $attachment_id ) ) 
    …… 
    2655} 
    2756 
     57/** 
     58 * get_children() - Get post children 
     59 * 
     60 * {@internal Missing Long Description}} 
     61 * 
     62 * @package WordPress 
     63 * @subpackage Post 
     64 * @since 2.0 
     65 * 
     66 * @param mixed $args {@internal Missing Description}} 
     67 * @param string $output {@internal Missing Description}} 
     68 * @return mixed {@internal Missing Description}} 
     69 */ 
    2870function &get_children($args = '', $output = OBJECT) { 
    2971    if ( empty( $args ) ) { 
    …… 
    71113} 
    72114 
    73 // get extended entry info (<!--more-->) 
     115/** 
     116 * get_extended() - get extended entry info (<!--more-->) 
     117 * 
     118 * {@internal Missing Long Description}} 
     119 * 
     120 * @package WordPress 
     121 * @subpackage Post 
     122 * @since 1.0.1 
     123 * 
     124 * @param string $post {@internal Missing Description}} 
     125 * @return array {@internal Missing Description}} 
     126 */ 
    74127function get_extended($post) { 
    75128    //Match the new style more links 
    …… 
    88141} 
    89142 
    90 // Retrieves post data given a post ID or post object. 
    91 // Handles post caching. 
     143/** 
     144 * get_post() - Retrieves post data given a post ID or post object. 
     145 * 
     146 * {@internal Missing Long Description}} 
     147 * 
     148 * @package WordPress 
     149 * @subpackage Post 
     150 * @since 1.5.1 
     151 * @uses $wpdb 
     152 * 
     153 * @param int|object &$post post ID or post object 
     154 * @param string $output {@internal Missing Description}} 
     155 * @param string $filter {@internal Missing Description}} 
     156 * @return mixed {@internal Missing Description}} 
     157 */ 
    92158function &get_post(&$post, $output = OBJECT, $filter = 'raw') { 
    93159    global $wpdb; 
    …… 
    122188} 
    123189 
     190/** 
     191 * get_post_field() - Retrieve a field based on a post ID. 
     192 * 
     193 * @package WordPress 
     194 * @subpackage Post 
     195 * @since 2.3 
     196 * 
     197 * @param string $field {@internal Missing Description}} 
     198 * @param id $post Post ID 
     199 * @param string $context Optional. How to filter the field 
     200 * @return WP_Error|string Value in post field or WP_Error on failure 
     201 */ 
    124202function get_post_field( $field, $post, $context = 'display' ) { 
    125203    $post = (int) $post; 
    …… 
    138216} 
    139217 
    140 // Takes a post ID, returns its mime type. 
     218/** 
     219 * get_post_mime_type() - Takes a post ID, returns its mime type. 
     220 * 
     221 * @package WordPress 
     222 * @subpackage Post 
     223 * @since 2.0 
     224 * 
     225 * @param int $ID Post ID 
     226 * @return bool|string False on failure or returns the mime type 
     227 */ 
    141228function get_post_mime_type($ID = '') { 
    142229    $post = & get_post($ID); 
    …… 
    148235} 
    149236 
     237/** 
     238 * get_post_status() - Takes a post ID and returns its status 
     239 * 
     240 * {@internal Missing Long Description}} 
     241 * 
     242 * @package WordPress 
     243 * @subpackage Post 
     244 * @since 2.0 
     245 * 
     246 * @param int $ID {@internal Missing Description}} 
     247 * @return string|bool post status or false 
     248 */ 
    150249function get_post_status($ID = '') { 
    151250    $post = get_post($ID); 
    …… 
    161260} 
    162261 
     262/** 
     263 * get_post_type() - Returns post type 
     264 * 
     265 * {@internal Missing Long Description}} 
     266 * 
     267 * @package WordPress 
     268 * @subpackage Post 
     269 * @since 2.1 
     270 * 
     271 * @uses $wpdb 
     272 * @uses $posts {@internal Missing Description}} 
     273 * 
     274 * @param mixed $post post object or post ID 
     275 * @return mixed post type or false 
     276 */ 
    163277function get_post_type($post = false) { 
    164278    global $posts; 
    …… 
    175289} 
    176290 
     291/** 
     292 * get_posts() - Returns a number of posts 
     293 * 
     294 * {@internal Missing Long Description}} 
     295 * 
     296 * @package WordPress 
     297 * @subpackage Post 
     298 * @since 1.2 
     299 * @uses $wpdb 
     300 * 
     301 * @param array $args {@internal Missing Description}} 
     302 * @return array {@internal Missing Description}} 
     303 */ 
    177304function get_posts($args) { 
    178305    global $wpdb; 
    …… 
    258385// 
    259386 
     387/** 
     388 * add_post_meta() - adds metadata for post 
     389 * 
     390 * {@internal Missing Long Description}} 
     391 * 
     392 * @package WordPress 
     393 * @subpackage Post 
     394 * @since 1.5 
     395 * @uses $wpdb 
     396 * 
     397 * @param int $post_id post ID 
     398 * @param string $key {@internal Missing Description}} 
     399 * @param mixed $value {@internal Missing Description}} 
     400 * @param bool $unique whether to check for a value with the same key 
     401 * @return bool {@internal Missing Description}} 
     402 */ 
    260403function add_post_meta($post_id, $meta_key, $meta_value, $unique = false) { 
    261404    global $wpdb; 
    …… 
    281424} 
    282425 
     426/** 
     427 * delete_post_meta() - delete post metadata 
     428 * 
     429 * {@internal Missing Long Description}} 
     430 * 
     431 * @package WordPress 
     432 * @subpackage Post 
     433 * @since 1.5 
     434 * @uses $wpdb 
     435 * 
     436 * @param int $post_id post ID 
     437 * @param string $key {@internal Missing Description}} 
     438 * @param mixed $value {@internal Missing Description}} 
     439 * @return bool {@internal Missing Description}} 
     440 */ 
    283441function delete_post_meta($post_id, $key, $value = '') { 
    284442    global $wpdb; 
    …… 
    308466} 
    309467 
     468/** 
     469 * get_post_meta() - Get a post meta field 
     470 * 
     471 * {@internal Missing Long Description}} 
     472 * 
     473 * @package WordPress 
     474 * @subpackage Post 
     475 * @since 1.5 
     476 * @uses $wpdb 
     477 * 
     478 * @param int $post_id post ID 
     479 * @param string $key The meta key to retrieve 
     480 * @param bool $single Whether to return a single value 
     481 * @return mixed {@internal Missing Description}} 
     482 */ 
    310483function get_post_meta($post_id, $key, $single = false) { 
    311484    $post_id = (int) $post_id; 
    …… 
    336509} 
    337510 
     511/** 
     512 * update_post_meta() - Update a post meta field 
     513 * 
     514 * {@internal Missing Long Description}} 
     515 * 
     516 * @package WordPress 
     517 * @subpackage Post 
     518 * @since 1.5 
     519 * @uses $wpdb 
     520 * 
     521 * @param int $post_id post ID 
     522 * @param string $key {@internal Missing Description}} 
     523 * @param mixed $value {@internal Missing Description}} 
     524 * @param mixed $prev_value previous value (for differentiating between meta fields with the same key and post ID) 
     525 * @return bool {@internal Missing Description}} 
     526 */ 
    338527function update_post_meta($post_id, $meta_key, $meta_value, $prev_value = '') { 
    339528    global $wpdb; 
    …… 
    359548} 
    360549 
    361  
     550/** 
     551 * delete_post_meta_by_key() - Delete everything from post meta matching $post_meta_key 
     552 * 
     553 * @package WordPress 
     554 * @subpackage Post 
     555 * @since 2.3 
     556 * @uses $wpdb 
     557 * 
     558 * @param string $post_meta_key What to search for when deleting 
     559 * @return bool Whether the post meta key was deleted from the database 
     560 */ 
    362561function delete_post_meta_by_key($post_meta_key) { 
    363562    global $wpdb; 
    364563    if ( $wpdb->query($wpdb->prepare("DELETE FROM $wpdb->postmeta WHERE meta_key = %s", $post_meta_key)) ) { 
    365         // TODO Get post_ids and delete cache 
     564        /** @todo Get post_ids and delete cache */ 
    366565        // wp_cache_delete($post_id, 'post_meta'); 
    367566        return true; 
    …… 
    370569} 
    371570 
    372  
     571/** 
     572 * get_post_custom() - Retrieve post custom fields 
     573 * 
     574 * {@internal Missing Long Description}} 
     575 * 
     576 * @package WordPress 
     577 * @subpackage Post 
     578 * @since 1.2 
     579 * 
     580 * @uses $id 
     581 * @uses $wpdb 
     582 * 
     583 * @param int $post_id post ID 
     584 * @return array {@internal Missing Description}} 
     585 */ 
    373586function get_post_custom($post_id = 0) { 
    374587    global $id; 
    …… 
    385598} 
    386599 
     600/** 
     601 * get_post_custom_keys() - Retrieve post custom field names 
     602 * 
     603 * @package WordPress 
     604 * @subpackage Post 
     605 * @since 1.2 
     606 * 
     607 * @param int $post_id post ID 
     608 * @return array|null Either array of the keys, or null if keys would not be retrieved 
     609 */ 
    387610function get_post_custom_keys( $post_id = 0 ) { 
    388611    $custom = get_post_custom( $post_id ); 
    …… 
    424647} 
    425648 
     649/** 
     650 * sanitize_post_field() - Sanitize post field based on context 
     651 * 
     652 * {@internal Missing Long Description}} 
     653 * 
     654 * @package WordPress 
     655 * @subpackage Post 
     656 * @since 2.3 
     657 * 
     658 * @param string $field The Post Object field name 
     659 * @param string $value The Post Object value 
     660 * @param int $postid Post ID 
     661 * @param string $context How to sanitize post fields 
     662 * @return string Sanitized value 
     663 */ 
    426664function sanitize_post_field($field, $value, $post_id, $context) { 
    427665    $int_fields = array('ID', 'post_parent', 'menu_order'); 
    …… 
    481719} 
    482720 
     721/** 
     722 * wp_delete_post() - Deletes a Post 
     723 * 
     724 * {@internal Missing Long Description}} 
     725 * 
     726 * @package WordPress 
     727 * @subpackage Post 
     728 * @since 1.0.1 
     729 * 
     730 * @param int $postid post ID 
     731 * @return mixed {@internal Missing Description}} 
     732 */ 
    483733function wp_delete_post($postid = 0) { 
    484734    global $wpdb, $wp_rewrite; 
    …… 
    492742    do_action('delete_post', $postid); 
    493743 
    494     // TODO delete for pluggable post taxonomies too 
     744    /** @todo delete for pluggable post taxonomies too */ 
    495745    wp_delete_object_term_relationships($postid, array('category', 'post_tag')); 
    496746 
    …… 
    534784} 
    535785 
     786/** 
     787 * wp_get_post_categories() - Retrieve the list of categories for a post 
     788 * 
     789 * Compatibility layer for themes and plugins. Also an easy layer of abstraction 
     790 * away from the complexity of the taxonomy layer. 
     791 * 
     792 * @package WordPress 
     793 * @subpackage Post 
     794 * @since 2.1 
     795 * 
     796 * @uses wp_get_object_terms() Retrieves the categories. Args details can be found here 
     797 * 
     798 * @param int $post_id Optional. The Post ID 
     799 * @param array $args Optional. Overwrite the defaults 
     800 * @return array {@internal Missing Description}} 
     801 */ 
    536802function wp_get_post_categories( $post_id = 0, $args = array() ) { 
    537803    $post_id = (int) $post_id; 
    …… 
    544810} 
    545811 
     812/** 
     813 * wp_get_post_tags() - Retrieve the post tags 
     814 * 
     815 * @package WordPress 
     816 * @subpackage Post 
     817 * @since 2.3 
     818 * 
     819 * @uses wp_get_object_terms() Gets the tags for returning. Args can be found here 
     820 * 
     821 * @param int $post_id Optional. The Post ID 
     822 * @param array $args Optional. Overwrite the defaults 
     823 * @return mixed The tags the post has currently 
     824 */ 
    546825function wp_get_post_tags( $post_id = 0, $args = array() ) { 
    547826    $post_id = (int) $post_id; 
    …… 
    555834} 
    556835 
     836/** 
     837 * wp_get_recent_posts() - Get the $num most recent posts 
     838 * 
     839 * {@internal Missing Long Description}} 
     840 * 
     841 * @package WordPress 
     842 * @subpackage Post 
     843 * @since 1.0.1 
     844 * 
     845 * @param int $num number of posts to get 
     846 * @return array {@internal Missing Description}} 
     847 */ 
    557848function wp_get_recent_posts($num = 10) { 
    558849    global $wpdb; 
    …… 
    570861} 
    571862 
     863/** 
     864 * wp_get_single_post() - Get one post 
     865 * 
     866 * {@internal Missing Long Description}} 
     867 * 
     868 * @package WordPress 
     869 * @subpackage Post 
     870 * @since 1.0.1 
     871 * @uses $wpdb 
     872 * 
     873 * @param int $postid post ID 
     874 * @param string $mode How to return result, either OBJECT, ARRAY_N, or ARRAY_A 
     875 * @return object|array Post object or array holding post contents and information 
     876 */ 
    572877function wp_get_single_post($postid = 0, $mode = OBJECT) { 
    573878    $postid = (int) $postid; 
    …… 
    588893} 
    589894 
     895/** 
     896 * wp_insert_post() - Insert a post 
     897 * 
     898 * {@internal Missing Long Description}} 
     899 * 
     900 * @package WordPress 
     901 * @subpackage Post 
     902 * @since 1.0.1 
     903 * 
     904 * @uses $wpdb 
     905 * @uses $wp_rewrite 
     906 * @uses $user_ID 
     907 * @uses $allowedtags 
     908 * 
     909 * @param array $postarr post contents 
     910 * @return int post ID or 0 on error 
     911 */ 
    590912function wp_insert_post($postarr = array()) { 
    591913    global $wpdb, $wp_rewrite, $user_ID; 
    …… 
    7591081} 
    7601082 
     1083/** 
     1084 * wp_update_post() - Update a post 
     1085 * 
     1086 * {@internal Missing Long Description}} 
     1087 * 
     1088 * @package WordPress 
     1089 * @subpackage Post 
     1090 * @since 1.0.1 
     1091 * @uses $wpdb 
     1092 * 
     1093 * @param array $postarr post data 
     1094 * @return int {@internal Missing Description}} 
     1095 */ 
    7611096function wp_update_post($postarr = array()) { 
    7621097    if ( is_object($postarr) ) 
    …… 
    7971132} 
    7981133 
     1134/** 
     1135 * wp_publish_post() - Mark a post as "published" 
     1136 * 
     1137 * {@internal Missing Long Description}} 
     1138 * 
     1139 * @package WordPress 
     1140 * @subpackage Post 
     1141 * @since 2.1 
     1142 * @uses $wpdb 
     1143 * 
     1144 * @param int $post_id Post ID 
     1145 * @return int|null {@internal Missing Description}} 
     1146 */ 
    7991147function wp_publish_post($post_id) { 
    8001148    global $wpdb; 
    …… 
    8371185} 
    8381186 
     1187/** 
     1188 * wp_set_post_categories() - Set categories for a post 
     1189 * 
     1190 * {@internal Missing Long Description}} 
     1191 * 
     1192 * @package WordPress 
     1193 * @subpackage Post 
     1194 * @since 2.1 
     1195 * @uses $wpdb 
     1196 * 
     1197 * @param int $post_ID post ID 
     1198 * @param array $post_categories 
     1199 * @return bool|mixed {@internal Missing Description}} 
     1200 */ 
    8391201function wp_set_post_categories($post_ID = 0, $post_categories = array()) { 
    8401202    $post_ID = (int) $post_ID; 
    …… 
    8511213}   // wp_set_post_categories() 
    8521214 
     1215/** 
     1216 * wp_transition_post_status() - Change the post transition status 
     1217 * 
     1218 * {@internal Missing Long Description}} 
     1219 * 
     1220 * @package WordPress 
     1221 * @subpackage Post 
     1222 * @since 2.3 
     1223 * 
     1224 * @param string $new_status {@internal Missing Description}} 
     1225 * @param string $old_status {@internal Missing Description}} 
     1226 * @param int $post {@internal Missing Description}} 
     1227 */ 
    8531228function wp_transition_post_status($new_status, $old_status, $post) { 
    8541229    if ( $new_status != $old_status ) { 
    …… 
    8631238// 
    8641239 
    865 function add_ping($post_id, $uri) { // Add a URL to those already pung 
     1240/** 
     1241 * add_ping() - Add a URL to those already pung 
     1242 * 
     1243 * {@internal Missing Long Description}} 
     1244 * 
     1245 * @package WordPress 
     1246 * @subpackage Post 
     1247 * @since 1.5 
     1248 * @uses $wpdb 
     1249 * 
     1250 * @param int $post_id post ID 
     1251 * @param string $uri {@internal Missing Description}} 
     1252 * @return mixed {@internal Missing Description}} 
     1253 */ 
     1254function add_ping($post_id, $uri) { 
    8661255    global $wpdb; 
    8671256    $pung = $wpdb->get_var( $wpdb->prepare( "SELECT pinged FROM $wpdb->posts WHERE ID = %d", $post_id )); 
    …… 
    8941283} 
    8951284 
    896 function get_pung($post_id) { // Get URLs already pung for a post 
     1285/** 
     1286 * get_pung() - Get URLs already pinged for a post 
     1287 * 
     1288 * {@internal Missing Long Description}} 
     1289 * 
     1290 * @package WordPress 
     1291 * @subpackage Post 
     1292 * @since 1.5 
     1293 * @uses $wpdb 
     1294 * 
     1295 * @param int $post_id post ID 
     1296 * @return array {@internal Missing Description}} 
     1297 */ 
     1298function get_pung($post_id) { 
    8971299    global $wpdb; 
    8981300    $pung = $wpdb->get_var( $wpdb->prepare( "SELECT pinged FROM $wpdb->posts WHERE ID = %d", $post_id )); 
    …… 
    9031305} 
    9041306 
    905 function get_to_ping($post_id) { // Get any URLs in the todo list 
     1307/** 
     1308 * get_to_ping() - Get any URLs in the todo list 
     1309 * 
     1310 * {@internal Missing Long Description}} 
     1311 * 
     1312 * @package WordPress 
     1313 * @subpackage Post 
     1314 * @since 1.5 
     1315 * @uses $wpdb 
     1316 * 
     1317 * @param int $post_id post ID 
     1318 * @return array {@internal Missing Description}} 
     1319 */ 
     1320function get_to_ping($post_id) { 
    9061321    global $wpdb; 
    9071322    $to_ping = $wpdb->get_var( $wpdb->prepare( "SELECT to_ping FROM $wpdb->posts WHERE ID = %d", $post_id )); 
    …… 
    9121327} 
    9131328 
    914 // do trackbacks for a list of urls 
    915 // accepts a comma-separated list of trackback urls and a post id 
     1329/** 
     1330 * trackback_url_list() - Do trackbacks for a list of urls 
     1331 * 
     1332 * {@internal Missing Long Description}} 
     1333 * 
     1334 * @package WordPress 
     1335 * @subpackage Post 
     1336 * @since 1.0.1 
     1337 * 
     1338 * @param string $tb_list comma separated list of URLs 
     1339 * @param int $post_id post ID 
     1340 */ 
    9161341function trackback_url_list($tb_list, $post_id) { 
    9171342    if (!empty($tb_list)) { 
    …… 
    9411366// 
    9421367 
     1368/** 
     1369 * get_all_page_ids() - Get a list of page IDs 
     1370 * 
     1371 * {@internal Missing Long Description}} 
     1372 * 
     1373 * @package WordPress 
     1374 * @subpackage Post 
     1375 * @since 2.0 
     1376 * @uses $wpdb 
     1377 * 
     1378 * @return array {@internal Missing Description}} 
     1379 */ 
    9431380function get_all_page_ids() { 
    9441381    global $wpdb; 
    …… 
    9521389} 
    9531390 
    954  
    955 // Retrieves page data given a page ID or page object. 
    956 // Handles page caching. 
     1391/** 
     1392 * get_page() - Retrieves page data given a page ID or page object 
     1393 * 
     1394 * {@internal Missing Long Description}} 
     1395 * 
     1396 * @package WordPress 
     1397 * @subpackage Post 
     1398 * @since 1.5.1 
     1399 * 
     1400 * @param mixed &$page page object or page ID 
     1401 * @param string $output what to output 
     1402 * @param string $filter How the return value should be filtered. 
     1403 * @return mixed {@internal Missing Description}} 
     1404 */ 
    9571405function &get_page(&$page, $output = OBJECT, $filter = 'raw') { 
    9581406    if ( empty($page) ) { 
    …… 
    9661414} 
    9671415 
     1416/** 
     1417 * get_page_by_path() - Retrieves a page given its path 
     1418 * 
     1419 * {@internal Missing Long Description}} 
     1420 * 
     1421 * @package WordPress 
     1422 * @subpackage Post 
     1423 * @since 2.1 
     1424 * @uses $wpdb 
     1425 * 
     1426 * @param string $page_path page path 
     1427 * @param string $output output type 
     1428 * @return mixed {@internal Missing Description}} 
     1429 */ 
    9681430function get_page_by_path($page_path, $output = OBJECT) { 
    9691431    global $wpdb; 
    …… 
    9971459} 
    9981460 
     1461/** 
     1462 * get_page_by_title() - Retrieve a page given its title 
     1463 * 
     1464 * {@internal Missing Long Description}} 
     1465 * 
     1466 * @package WordPress 
     1467 * @subpackage Post 
     1468 * @since 2.1 
     1469 * @uses $wpdb 
     1470 * 
     1471 * @param string $page_title page title 
     1472 * @param string $output output type 
     1473 * @return mixed {@internal Missing Description}} 
     1474 */ 
    9991475function get_page_by_title($page_title, $output = OBJECT) { 
    10001476    global $wpdb; 
    …… 
    10061482} 
    10071483 
     1484/** 
     1485 * get_page_children() - Retrieve child pages 
     1486 * 
     1487 * {@internal Missing Long Description}} 
     1488 * 
     1489 * @package WordPress 
     1490 * @subpackage Post 
     1491 * @since 1.5.1 
     1492 * 
     1493 * @param int $page_id page ID 
     1494 * @param array $pages list of pages 
     1495 * @return array {@internal Missing Description}} 
     1496 */ 
    10081497function &get_page_children($page_id, $pages) { 
    10091498    $page_list = array(); 
    …… 
    10181507} 
    10191508 
    1020 //fetches the pages returned as a FLAT list, but arranged in order of their hierarchy, i.e., child parents 
    1021 //immediately follow their parents 
     1509/** 
     1510 * get_page_hierarchy() - {@internal Missing Short Description}} 
     1511 * 
     1512 * Fetches the pages returned as a FLAT list, but arranged in order of their hierarchy, 
     1513 * i.e., child parents immediately follow their parents. 
     1514 * 
     1515 * @package WordPress 
     1516 * @subpackage Post 
     1517 * @since 2.0 
     1518 * 
     1519 * @param array $posts posts array 
     1520 * @param int $parent parent page ID 
     1521 * @return array {@internal Missing Description}} 
     1522 */ 
    10221523function get_page_hierarchy($posts, $parent = 0) { 
    10231524    $result = array ( ); 
    …… 
    10321533} 
    10331534 
     1535/** 
     1536 * get_page_uri() - Builds a page URI 
     1537 * 
     1538 * {@internal Missing Long Description}} 
     1539 * 
     1540 * @package WordPress 
     1541 * @subpackage Post 
     1542 * @since 1.5 
     1543 * 
     1544 * @param int $page_id page ID 
     1545 * @return string {@internal Missing Description}} 
     1546 */ 
    10341547function get_page_uri($page_id) { 
    10351548    $page = get_page($page_id); 
    …… 
    10481561} 
    10491562 
     1563/** 
     1564 * get_pages() - Retrieve a list of pages 
     1565 * 
     1566 * {@internal Missing Long Description}} 
     1567 * 
     1568 * @package WordPress 
     1569 * @subpackage Post 
     1570 * @since 1.5 
     1571 * @uses $wpdb 
     1572 * 
     1573 * @param mixed $args Optional. Array or string of options 
     1574 * @return array List of pages matching defaults or $args 
     1575 */ 
    10501576function &get_pages($args = '') { 
    10511577    global $wpdb; 
    …… 
    11581684// 
    11591685 
     1686/** 
     1687 * is_local_attachment() - Check if the attachment URI is local one and is really an attachment. 
     1688 * 
     1689 * {@internal Missing Long Description}} 
     1690 * 
     1691 * @package WordPress 
     1692 * @subpackage Post 
     1693 * @since 2.0 
     1694 * 
     1695 * @param string $url URL to check 
     1696 * @return bool {@internal Missing Description}} 
     1697 */ 
    11601698function is_local_attachment($url) { 
    11611699    if (strpos($url, get_bloginfo('url')) === false) 
    …… 
    11711709} 
    11721710 
     1711/** 
     1712 * wp_insert_attachment() - Insert an attachment 
     1713 * 
     1714 * {@internal Missing Long Description}} 
     1715 * 
     1716 * @package WordPress 
     1717 * @subpackage Post 
     1718 * @since 2.0 
     1719 * 
     1720 * @uses $wpdb 
     1721 * @uses $user_ID 
     1722 * 
     1723 * @param object $object attachment object 
     1724 * @param string $file filename 
     1725 * @param int $post_parent parent post ID 
     1726 * @return int {@internal Missing Description}} 
     1727 */ 
    11731728function wp_insert_attachment($object, $file = false, $parent = 0) { 
    11741729    global $wpdb, $user_ID; 
    …… 
    12921847} 
    12931848 
     1849/** 
     1850 * wp_delete_attachment() - Delete an attachment 
     1851 * 
     1852 * {@internal Missing Long Description}} 
     1853 * 
     1854 * @package WordPress 
     1855 * @subpackage Post 
     1856 * @since 2.0 
     1857 * @uses $wpdb 
     1858 * 
     1859 * @param int $postid attachment Id 
     1860 * @return mixed {@internal Missing Description}} 
     1861 */ 
    12941862function wp_delete_attachment($postid) { 
    12951863    global $wpdb; 
    …… 
    13041872    $file = get_attached_file( $postid ); 
    13051873 
    1306     // TODO delete for pluggable post taxonomies too 
     1874    /** @todo Delete for pluggable post taxonomies too */ 
    13071875    wp_delete_object_term_relationships($postid, array('category', 'post_tag')); 
    13081876 
    …… 
    13341902} 
    13351903 
     1904/** 
     1905 * wp_get_attachment_metadata() - Retrieve metadata for an attachment 
     1906 * 
     1907 * {@internal Missing Long Description}} 
     1908 * 
     1909 * @package WordPress 
     1910 * @subpackage Post 
     1911 * @since 2.1 
     1912 * 
     1913 * @param int $post_id attachment ID 
     1914 * @param bool $unfiltered Optional, default is false. If true, filters are not run 
     1915 * @return array {@internal Missing Description}} 
     1916 */ 
    13361917function wp_get_attachment_metadata( $post_id, $unfiltered = false ) { 
    13371918    $post_id = (int) $post_id; 
    …… 
    13451926} 
    13461927 
     1928/** 
     1929 * wp_update_attachment_metadata() - Update metadata for an attachment 
     1930 * 
     1931 * {@internal Missing Long Description}} 
     1932 * 
     1933 * @package WordPress 
     1934 * @subpackage Post 
     1935 * @since 2.1 
     1936 * 
     1937 * @param int $post_id attachment ID 
     1938 * @param array $data attachment data 
     1939 * @return int {@internal Missing Description}} 
     1940 */ 
    13471941function wp_update_attachment_metadata( $post_id, $data ) { 
    13481942    $post_id = (int) $post_id; 
    …… 
    13601954} 
    13611955 
     1956/** 
     1957 * wp_get_attachment_url() - Retrieve the URL for an attachment 
     1958 * 
     1959 * {@internal Missing Long Description}} 
     1960 * 
     1961 * @package WordPress 
     1962 * @subpackage Post 
     1963 * @since 2.1 
     1964 * 
     1965 * @param int $post_id attachment ID 
     1966 * @return string {@internal Missing Description}} 
     1967 */ 
    13621968function wp_get_attachment_url( $post_id = 0 ) { 
    13631969    $post_id = (int) $post_id; 
    …… 
    13731979} 
    13741980 
     1981/** 
     1982 * wp_get_attachment_thumb_file() - Retrieve thumbnail for an attachment 
     1983 * 
     1984 * {@internal Missing Long Description}} 
     1985 * 
     1986 * @package WordPress 
     1987 * @subpackage Post 
     1988 * @since 2.1 
     1989 * 
     1990 * @param int $post_id attachment ID 
     1991 * @return mixed {@internal Missing Description}} 
     1992 */ 
    13751993function wp_get_attachment_thumb_file( $post_id = 0 ) { 
    13761994    $post_id = (int) $post_id; 
    …… 
    13872005} 
    13882006 
     2007/** 
     2008 * wp_get_attachment_thumb_url() - Retrieve URL for an attachment thumbnail 
     2009 * 
     2010 * {@internal Missing Long Description}} 
     2011 * 
     2012 * @package WordPress 
     2013 * @subpackage Post 
     2014 * @since 2.1 
     2015 * 
     2016 * @param int $post_id attachment ID 
     2017 * @return string {@internal Missing Description}} 
     2018 */ 
    13892019function wp_get_attachment_thumb_url( $post_id = 0 ) { 
    13902020    $post_id = (int) $post_id; 
    …… 
    14022032} 
    14032033 
     2034/** 
     2035 * wp_attachment_is_image() - Check if the attachment is an image 
     2036 * 
     2037 * {@internal Missing Long Description}} 
     2038 * 
     2039 * @package WordPress 
     2040 * @subpackage Post 
     2041 * @since 2.1 
     2042 * 
     2043 * @param int $post_id attachment ID 
     2044 * @return bool {@internal Missing Description}} 
     2045 */ 
    14042046function wp_attachment_is_image( $post_id = 0 ) { 
    14052047    $post_id = (int) $post_id; 
    …… 
    14192061} 
    14202062 
     2063/** 
     2064 * wp_mime_type_icon() - Retrieve the icon for a MIME type 
     2065 * 
     2066 * {@internal Missing Long Description}} 
     2067 * 
     2068 * @package WordPress 
     2069 * @subpackage Post 
     2070 * @since 2.1 
     2071 * 
     2072 * @param string $mime MIME type 
     2073 * @return string|bool {@internal Missing Description}} 
     2074 */ 
    14212075function wp_mime_type_icon( $mime = 0 ) { 
    14222076    $post_id = 0; 
    …… 
    14582112} 
    14592113 
     2114/** 
     2115 * wp_check_for_changed_slugs() - {@internal Missing Short Description}} 
     2116 * 
     2117 * {@internal Missing Long Description}} 
     2118 * 
     2119 * @package WordPress 
     2120 * @subpackage Post 
     2121 * @since 2.1 
     2122 * 
     2123 * @param int $post_id The Post ID 
     2124 * @return int Same as $post_id 
     2125 */ 
    14602126function wp_check_for_changed_slugs($post_id) { 
    14612127    if ( !strlen($_POST['wp-old-slug']) ) 
    …… 
    14862152 
    14872153/** 
     2154 * get_private_posts_cap_sql() - {@internal Missing Short Description}} 
     2155 * 
    14882156 * This function provides a standardized way to appropriately select on 
    14892157 * the post_status of posts/pages. The function will return a piece of 
    …… 
    14912159 * to allow all published posts, and all private posts to which the user 
    14922160 * has access. 
     2161 * 
     2162 * @package WordPress 
     2163 * @subpackage Post 
     2164 * @since 2.2 
     2165 * 
     2166 * @uses $user_ID 
     2167 * @uses apply_filters() Call 'pub_priv_sql_capability' filter for plugins with different post types 
    14932168 * 
    14942169 * @param string $post_type currently only supports 'post' or 'page'. 
    …… 
    15312206} 
    15322207 
     2208/** 
     2209 * get_lastpostdate() - {@internal Missing Short Description}} 
     2210 * 
     2211 * {@internal Missing Long Description}} 
     2212 * 
     2213 * @package WordPress 
     2214 * @subpackage Post 
     2215 * @since 0.71 
     2216 * 
     2217 * @uses $wpdb 
     2218 * @uses $blog_id 
     2219 * @uses apply_filters() Calls 'get_lastpostdate' filter 
     2220 * 
     2221 * @global mixed $cache_lastpostdate Stores the last post date 
     2222 * @global mixed $pagenow The current page being viewed 
     2223 * 
     2224 * @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'. 
     2225 * @return string The date of the last post. 
     2226 */ 
    15332227function get_lastpostdate($timezone = 'server') { 
    15342228    global $cache_lastpostdate, $wpdb, $blog_id; 
    …… 
    15532247} 
    15542248 
     2249/** 
     2250 * get_lastpostmodified() - {@internal Missing Short Description}} 
     2251 * 
     2252 * {@internal Missing Long Description}} 
     2253 * 
     2254 * @package WordPress 
     2255 * @subpackage Post 
     2256 * @since 1.2 
     2257 * 
     2258 * @uses $wpdb 
     2259 * @uses $blog_id 
     2260 * @uses apply_filters() Calls 'get_lastpostmodified' filter 
     2261 * 
     2262 * @global mixed $cache_lastpostmodified Stores the date the last post was modified 
     2263 * @global mixed $pagenow The current page being viewed 
     2264 * 
     2265 * @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'. 
     2266 * @return string The date the post was last modified. 
     2267 */ 
    15552268function get_lastpostmodified($timezone = 'server') { 
    15562269    global $cache_lastpostmodified, $wpdb, $blog_id; 
    …… 
    15792292} 
    15802293 
    1581 // 
    1582 // Cache 
    1583 // 
    1584  
     2294/** 
     2295 * update_post_cache() - Updates posts in cache 
     2296 * 
     2297 * @usedby update_page_cache() update_page_cache() aliased by this function. 
     2298 * 
     2299 * @package WordPress 
     2300 * @subpackage Cache 
     2301 * @since 1.5.1 
     2302 * 
     2303 * @param array $posts Array of post objects 
     2304 */ 
    15852305function update_post_cache(&$posts) { 
    15862306    if ( !$posts ) 
    …… 
    15912311} 
    15922312 
     2313/** 
     2314 * clean_post_cache() - Will clean the post in the cache 
     2315 * 
     2316 * Cleaning means delete from the cache of the post. Will call to clean 
     2317 * the term object cache associated with the post ID. 
     2318 * 
     2319 * @package WordPress 
     2320 * @subpackage Cache 
     2321 * @since 2.0 
     2322 * 
     2323 * @uses do_action() Will call the 'clean_post_cache' hook action. 
     2324 * 
     2325 * @param int $id The Post ID in the cache to clean 
     2326 */ 
    15932327function clean_post_cache($id) { 
    15942328    wp_cache_delete($id, 'posts'); 
    …… 
    16022336} 
    16032337 
     2338/** 
     2339 * update_page_cache() - Alias of update_post_cache() 
     2340 * 
     2341 * @see update_post_cache() Posts and pages are the same, alias is intentional 
     2342 * 
     2343 * @package WordPress 
     2344 * @subpackage Cache 
     2345 * @since 1.5.1 
     2346 * 
     2347 * @param array $pages list of page objects 
     2348 */ 
    16042349function update_page_cache(&$pages) { 
    16052350    update_post_cache($pages); 
    16062351} 
    16072352 
     2353/** 
     2354 * clean_page_cache() - Will clean the page in the cache 
     2355 * 
     2356 * Clean (read: delete) page from cache that matches $id. Will also clean 
     2357 * cache associated with 'all_page_ids' and 'get_pages'. 
     2358 * 
     2359 * @package WordPress 
     2360 * @subpackage Cache 
     2361 * @since 2.0 
     2362 * 
     2363 * @uses do_action() Will call the 'clean_page_cache' hook action. 
     2364 * 
     2365 * @param int $id Page ID to clean 
     2366 */ 
    16082367function clean_page_cache($id) { 
    16092368    clean_post_cache($id); 
    …… 
    16152374} 
    16162375 
     2376/** 
     2377 * update_post_caches() - Call major cache updating functions for list of Post objects. 
     2378 * 
     2379 * @package WordPress 
     2380 * @subpackage Cache 
     2381 * @since 1.5 
     2382 * 
     2383 * @uses $wpdb 
     2384 * @uses update_post_cache() 
     2385 * @uses update_object_term_cache() 
     2386 * @uses update_postmeta_cache() 
     2387 * 
     2388 * @param array $posts Array of Post objects 
     2389 */ 
    16172390function update_post_caches(&$posts) { 
    16182391    // No point in doing all this work if we didn't match any posts. 
    …… 
    16322405} 
    16332406 
     2407/** 
     2408 * update_postmeta_cache() - {@internal Missing Short Description}} 
     2409 * 
     2410 * {@internal Missing Long Description}} 
     2411 * 
     2412 * @package WordPress 
     2413 * @subpackage Cache 
     2414 * @since 2.1 
     2415 * 
     2416 * @uses $wpdb 
     2417 * 
     2418 * @param array $post_ids {@internal Missing Description}} 
     2419 * @return bool|array Returns false if there is nothing to update or an array of metadata 
     2420 */ 
    16342421function update_postmeta_cache($post_ids) { 
    16352422    global $wpdb; 
    …… 
    16892476// 
    16902477 
     2478/** 
     2479 * _transition_post_status() - Hook {@internal Missing Short Description}} 
     2480 * 
     2481 * {@internal Missing Long Description}} 
     2482 * 
     2483 * @package WordPress 
     2484 * @subpackage Post 
     2485 * @since 2.3 
     2486 * 
     2487 * @uses $wpdb 
     2488 * 
     2489 * @param string $new_status {@internal Missing Description}} 
     2490 * @param string $old_status {@internal Missing Description}} 
     2491 * @param object $post Object type containing the post information 
     2492 */ 
    16912493function _transition_post_status($new_status, $old_status, $post) { 
    16922494    global $wpdb; 
    …… 
    17022504} 
    17032505 
     2506/** 
     2507 * _future_post_hook() - Hook used to schedule publication for a post marked for the future. 
     2508 * 
     2509 * The $post properties used and must exist are 'ID' and 'post_date_gmt'. 
     2510 * 
     2511 * @package WordPress 
     2512 * @subpackage Post 
     2513 * @since 2.3 
     2514 * 
     2515 * @param int $post_id Not Used. Can be set to null. 
     2516 * @param object $post Object type containing the post information 
     2517 */ 
    17042518function _future_post_hook($post_id, $post) { 
    1705     // Schedule publication. 
    17062519    wp_clear_scheduled_hook( 'publish_future_post', $post->ID ); 
    17072520    wp_schedule_single_event(strtotime($post->post_date_gmt. ' GMT'), 'publish_future_post', array($post->ID)); 
    17082521} 
    17092522 
     2523/** 
     2524 * _publish_post_hook() - Hook {@internal Missing Short Description}} 
     2525 * 
     2526 * {@internal Missing Long Description}} 
     2527 * 
     2528 * @package WordPress 
     2529 * @subpackage Post 
     2530 * @since 2.3 
     2531 * 
     2532 * @uses $wpdb 
     2533 * @uses XMLRPC_REQUEST 
     2534