WordPress.org

Make WordPress Core

Ticket #7659: 7659.r8976.diff

File 7659.r8976.diff, 16.5 KB (added by jacobsantos, 6 years ago)

14 functions completed based off of r8976

  • post-template.php

     
    11<?php 
    22/** 
    3  * WordPress Post Template Functions 
     3 * WordPress Post Template Functions. 
    44 * 
    55 * Gets content for the current post in the loop. 
    66 * 
     
    99 */ 
    1010 
    1111/** 
    12  * the_ID() - {@internal Missing Short Description}} 
     12 * Display the ID of the current item in the WordPress Loop. 
    1313 * 
    14  * {@internal Missing Long Description}} 
    15  * 
    1614 * @since 0.71 
    1715 * @uses $id 
    1816 */ 
     
    2220} 
    2321 
    2422/** 
    25  * get_the_ID() - {@internal Missing Short Description}} 
     23 * Retrieve the ID of the current item in the WordPress Loop. 
    2624 * 
    27  * {@internal Missing Long Description}} 
    28  * 
    2925 * @since 2.1.0 
    3026 * @uses $id 
    3127 * 
     
    3733} 
    3834 
    3935/** 
    40  * the_title() - {@internal Missing Short Description}} 
     36 * Display or retrieve the current post title with optional content. 
    4137 * 
    42  * {@internal Missing Long Description}} 
    43  * 
    4438 * @since 0.71 
    4539 * 
    46  * @param unknown_type $before 
    47  * @param unknown_type $after 
    48  * @param unknown_type $echo 
    49  * @return unknown 
     40 * @param string $before Optional. Content to prepend to the title. 
     41 * @param string $after Optional. Content to append to the title. 
     42 * @param bool $echo Optional, default to true.Whether to display or return. 
     43 * @return null|string Null on no title. String if $echo parameter is false. 
    5044 */ 
    5145function the_title($before = '', $after = '', $echo = true) { 
    5246        $title = get_the_title(); 
     
    6357} 
    6458 
    6559/** 
    66  * the_title_attribute() - {@internal Missing Short Description}} 
     60 * Sanitize the current title when retrieving or displaying. 
    6761 * 
    68  * {@internal Missing Long Description}} 
     62 * Works like {@link the_title()}, except the parameters can be in a string or 
     63 * an array. See the function for what can be override in the $args parameter. 
    6964 * 
     65 * The title before it is displayed will have the tags stripped and {@link 
     66 * attribute_escape()} before it is passed to the user or displayed. The default 
     67 * as with {@link the_title()}, is to display the title. 
     68 * 
    7069 * @since 2.3.0 
    7170 * 
    72  * @param unknown_type $args 
    73  * @return unknown 
     71 * @param string|array $args Optional. Override the defaults. 
     72 * @return string|null Null on failure or display. String when echo is false. 
    7473 */ 
    7574function the_title_attribute( $args = '' ) { 
    7675        $title = get_the_title(); 
     
    9392} 
    9493 
    9594/** 
    96  * get_the_title() - {@internal Missing Short Description}} 
     95 * {@internal Missing Short Description}} 
    9796 * 
    9897 * {@internal Missing Long Description}} 
    9998 * 
    10099 * @since 0.71 
    101100 * 
    102  * @param unknown_type $id 
     101 * @param int $id 
    103102 * @return unknown 
    104103 */ 
    105104function get_the_title( $id = 0 ) { 
     
    117116} 
    118117 
    119118/** 
    120  * the_guid() - {@internal Missing Short Description}} 
     119 * {@internal Missing Short Description}} 
    121120 * 
    122121 * {@internal Missing Long Description}} 
    123122 * 
     
    130129} 
    131130 
    132131/** 
    133  * get_the_guid() - {@internal Missing Short Description}} 
     132 * {@internal Missing Short Description}} 
    134133 * 
    135134 * {@internal Missing Long Description}} 
    136135 * 
     
    146145} 
    147146 
    148147/** 
    149  * the_content() - {@internal Missing Short Description}} 
     148 * {@internal Missing Short Description}} 
    150149 * 
    151150 * {@internal Missing Long Description}} 
    152151 * 
     
    156155 * @param unknown_type $stripteaser 
    157156 * @param unknown_type $more_file 
    158157 */ 
    159 function the_content($more_link_text = NULL, $stripteaser = 0, $more_file = '') { 
     158function the_content($more_link_text = null, $stripteaser = 0, $more_file = '') { 
    160159        $content = get_the_content($more_link_text, $stripteaser, $more_file); 
    161160        $content = apply_filters('the_content', $content); 
    162161        $content = str_replace(']]>', ']]&gt;', $content); 
     
    164163} 
    165164 
    166165/** 
    167  * get_the_content() - {@internal Missing Short Description}} 
     166 * {@internal Missing Short Description}} 
    168167 * 
    169168 * {@internal Missing Long Description}} 
    170169 * 
     
    175174 * @param unknown_type $more_file 
    176175 * @return unknown 
    177176 */ 
    178 function get_the_content($more_link_text = NULL, $stripteaser = 0, $more_file = '') { 
     177function get_the_content($more_link_text = null, $stripteaser = 0, $more_file = '') { 
    179178        global $id, $post, $more, $page, $pages, $multipage, $preview, $pagenow; 
    180179 
    181         if ( NULL == $more_link_text ) 
     180        if ( null == $more_link_text ) 
    182181                $more_link_text = __( '(more...)' ); 
    183182 
    184183        $output = ''; 
     
    227226} 
    228227 
    229228/** 
    230  * the_excerpt() - {@internal Missing Short Description}} 
     229 * {@internal Missing Short Description}} 
    231230 * 
    232231 * {@internal Missing Long Description}} 
    233232 * 
     
    239238} 
    240239 
    241240/** 
    242  * get_the_excerpt() - {@internal Missing Short Description}} 
     241 * {@internal Missing Short Description}} 
    243242 * 
    244243 * {@internal Missing Long Description}} 
    245244 * 
     
    261260} 
    262261 
    263262/** 
    264  * has_excerpt() - {@internal Missing Short Description}} 
     263 * {@internal Missing Short Description}} 
    265264 * 
    266265 * {@internal Missing Long Description}} 
    267266 * 
     
    276275} 
    277276 
    278277/** 
    279  * Echo the classes for the post div 
     278 * Display the classes for the post div. 
    280279 * 
    281280 * {@internal Missing Long Description}} 
    282281 * 
    283  * @package WordPress 
    284  * @subpackage Post 
    285  * @since 2.7 
     282 * @since 2.7.0 
    286283 * 
    287284 * @param string|array $class One or more classes to add to the class list 
    288  * @param int $post_id An optional post ID 
     285 * @param int $post_id An optional post ID. 
    289286 */ 
    290287function post_class( $class = '', $post_id = null ) { 
    291288        // Separates classes with a single space, collates classes for post DIV 
     
    293290} 
    294291 
    295292/** 
    296  * Returns the classes for the post div as an array 
     293 * Retrieve the classes for the post div as an array. 
    297294 * 
    298295 * {@internal Missing Long Description}} 
    299296 * 
    300  * @package WordPress 
    301  * @subpackage Post 
    302  * @since 2.7 
     297 * @since 2.7.0 
    303298 * 
    304299 * @param string|array $class One or more classes to add to the class list 
    305300 * @param int $post_id An optional post ID 
     
    343338} 
    344339 
    345340/** 
    346  * Determines if post requires a password and if the correct password has been provided 
     341 * Determines if post requires a password and if the correct password has been provided. 
    347342 * 
    348343 * {@internal Missing Long Description}} 
    349344 * 
    350  * @package WordPress 
    351  * @subpackage Post 
    352  * @since 2.7 
     345 * @since 2.7.0 
    353346 * 
    354347 * @param int|object $post An optional post.  Global $post used if not provided. 
    355348 * @return bool false if a password is not required or the correct password cookie is present, true otherwise 
     
    370363} 
    371364 
    372365/** 
    373  * Echo "sticky" CSS class if a post is sticky 
     366 * Display "sticky" CSS class, if a post is sticky. 
    374367 * 
    375  * {@internal Missing Long Description}} 
     368 * @since 2.7.0 
    376369 * 
    377  * @package WordPress 
    378  * @subpackage Post 
    379  * @since 2.7 
    380  * 
    381370 * @param int $post_id An optional post ID 
    382371 */ 
    383372function sticky_class( $post_id = null ) { 
     
    388377} 
    389378 
    390379/** 
    391  * wp_link_pages() - {@internal Missing Short Description}} 
     380 * {@internal Missing Short Description}} 
    392381 * 
    393382 * {@internal Missing Long Description}} 
    394383 * 
     
    478467// 
    479468 
    480469/** 
    481  * post_custom() - {@internal Missing Short Description}} 
     470 * Retrieve post custom meta data field. 
    482471 * 
    483  * {@internal Missing Long Description}} 
    484  * 
    485472 * @since 1.5.0 
    486473 * 
    487  * @param unknown_type $key 
    488  * @return unknown 
     474 * @param string $key Meta data key name. 
     475 * @return string|array Array of values or single value, if only one element exists. 
    489476 */ 
    490477function post_custom( $key = '' ) { 
    491478        $custom = get_post_custom(); 
     
    496483                return $custom[$key]; 
    497484} 
    498485 
    499  
    500 // this will probably change at some point... 
    501486/** 
    502  * the_meta() - {@internal Missing Short Description}} 
     487 * Display list of post custom fields. 
    503488 * 
    504  * {@internal Missing Long Description}} 
    505  * 
     489 * @internal This will probably change at some point... 
    506490 * @since 1.2.0 
    507  * @uses apply_filters()  
     491 * @uses apply_filters() Calls 'the_meta_key' on list item HTML content, with key and value as separate parameters. 
    508492 */ 
    509493function the_meta() { 
    510494        if ( $keys = get_post_custom_keys() ) { 
     
    527511// 
    528512 
    529513/** 
    530  * wp_dropdown_pages() - {@internal Missing Short Description}} 
     514 * {@internal Missing Short Description}} 
    531515 * 
    532516 * {@internal Missing Long Description}} 
    533517 * 
     
    566550} 
    567551 
    568552/** 
    569  * wp_list_pages() - {@internal Missing Short Description}} 
     553 * {@internal Missing Short Description}} 
    570554 * 
    571555 * {@internal Missing Long Description}} 
    572556 * 
    573557 * @since 1.5.0 
    574558 * 
    575  * @param unknown_type $args 
     559 * @param array|string $args Optional. Override default arguments. 
    576560 * @return unknown 
    577561 */ 
    578562function wp_list_pages($args = '') { 
     
    622606} 
    623607 
    624608/** 
    625  * Create menu of pages 
     609 * Display menu of pages. 
    626610 * 
    627611 * @since 2.7.0 
    628612 * 
     
    661645// 
    662646 
    663647/** 
    664  * walk_page_tree() - {@internal Missing Short Description}} 
     648 * Retrieve HTML list content for page list. 
    665649 * 
    666  * {@internal Missing Long Description}} 
    667  * 
     650 * @uses Walker_Page to create HTML list content. 
    668651 * @since 2.1.0 
    669  * 
    670  * @return unknown 
     652 * @see Walker_Page::walk() for parameters and return description. 
    671653 */ 
    672654function walk_page_tree() { 
    673655        $walker = new Walker_Page; 
     
    676658} 
    677659 
    678660/** 
    679  * walk_page_dropdown_tree() - {@internal Missing Short Description}} 
     661 * Retrieve HTML dropdown (select) content for page list. 
    680662 * 
    681  * {@internal Missing Long Description}} 
    682  * 
     663 * @uses Walker_PageDropdown to create HTML dropdown content. 
    683664 * @since 2.1.0 
    684  * 
    685  * @return unknown 
     665 * @see Walker_PageDropdown::walk() for parameters and return description. 
    686666 */ 
    687667function walk_page_dropdown_tree() { 
    688668        $walker = new Walker_PageDropdown; 
     
    695675// 
    696676 
    697677/** 
    698  * the_attachment_link() - {@internal Missing Short Description}} 
     678 * {@internal Missing Short Description}} 
    699679 * 
    700680 * {@internal Missing Long Description}} 
    701681 * 
     
    712692                echo wp_get_attachment_link($id, 'thumbnail', $permalink); 
    713693} 
    714694 
    715 // get an attachment page link using an image or icon if possible 
     695/** 
     696 * Retrieve an attachment page link using an image or icon, if possible. 
     697 * 
     698 * {@internal Missing Long Description}} 
     699 * 
     700 * @since unknown 
     701 * 
     702 * @param unknown_type $id 
     703 * @param unknown_type $size 
     704 * @param unknown_type $permalink 
     705 * @param unknown_type $icon 
     706 * @return unknown 
     707 */ 
    716708function wp_get_attachment_link($id = 0, $size = 'thumbnail', $permalink = false, $icon = false) { 
    717709        $id = intval($id); 
    718710        $_post = & get_post( $id ); 
     
    733725 
    734726} 
    735727 
    736 // deprecated - use wp_get_attachment_link() 
     728/** 
     729 * {@internal Missing Short Description}} 
     730 * 
     731 * {@internal Missing Long Description}} 
     732 * 
     733 * @since unknown 
     734 * @deprecated Use {@link wp_get_attachment_link()} 
     735 * @see wp_get_attachment_link() Use instead. 
     736 * 
     737 * @param unknown_type $id 
     738 * @param unknown_type $fullsize 
     739 * @param unknown_type $max_dims 
     740 * @param unknown_type $permalink 
     741 * @return unknown 
     742 */ 
    737743function get_the_attachment_link($id = 0, $fullsize = false, $max_dims = false, $permalink = false) { 
    738744        $id = (int) $id; 
    739745        $_post = & get_post($id); 
     
    750756        return "<a href='$url' title='$post_title'>$innerHTML</a>"; 
    751757} 
    752758 
    753  
    754 // deprecated: use wp_get_attachment_image_src() 
    755759/** 
    756  * get_attachment_icon_src() - {@internal Missing Short Description}} 
     760 * {@internal Missing Short Description}} 
    757761 * 
    758762 * {@internal Missing Long Description}} 
    759763 * 
    760764 * @since 2.1.0 
     765 * @deprecated Use {@link wp_get_attachment_image_src()} 
     766 * @see wp_get_attachment_image_src() Use instead. 
    761767 * 
    762768 * @param unknown_type $id 
    763769 * @param unknown_type $fullsize 
     
    794800        return array($src, $src_file); 
    795801} 
    796802 
    797 // deprecated: use wp_get_attachment_image() 
    798803/** 
    799  * get_attachment_icon() - {@internal Missing Short Description}} 
     804 * {@internal Missing Short Description}} 
    800805 * 
    801806 * {@internal Missing Long Description}} 
    802807 * 
    803808 * @since 2.0.0 
     809 * @deprecated Use {@link wp_get_attachment_image()} 
     810 * @see wp_get_attachment_image() Use instead of. 
    804811 * 
    805812 * @param unknown_type $id 
    806813 * @param unknown_type $fullsize 
     
    850857        return apply_filters( 'attachment_icon', $icon, $post->ID ); 
    851858} 
    852859 
    853 // deprecated: use wp_get_attachment_image() 
    854860/** 
    855  * get_attachment_innerHTML() - {@internal Missing Short Description}} 
     861 * {@internal Missing Short Description}} 
    856862 * 
    857863 * {@internal Missing Long Description}} 
    858864 * 
    859865 * @since 2.0.0 
     866 * @deprecated Use {@link wp_get_attachment_image()} 
     867 * @see wp_get_attachment_image() Use instead. 
    860868 * 
    861869 * @param unknown_type $id 
    862870 * @param unknown_type $fullsize 
     
    878886} 
    879887 
    880888/** 
    881  * prepend_attachment() - {@internal Missing Short Description}} 
     889 * {@internal Missing Short Description}} 
    882890 * 
    883891 * {@internal Missing Long Description}} 
    884892 * 
     
    907915// 
    908916 
    909917/** 
    910  * get_the_password_form() - {@internal Missing Short Description}} 
     918 * Retrieve protected post password form content. 
    911919 * 
    912  * {@internal Missing Long Description}} 
    913  * 
    914920 * @since 1.0.0 
     921 * @uses apply_filters() Calls 'the_password_form' filter on output. 
    915922 * 
    916  * @return unknown 
     923 * @return string HTML content for password form for password protected post. 
    917924 */ 
    918925function get_the_password_form() { 
    919926        global $post; 
     
    927934} 
    928935 
    929936/** 
    930  * is_page_template() - Determine wether or not we are in a page template 
     937 * Whether currently in a page template. 
    931938 * 
    932  * This template tag allows you to determine wether or not you are in a page template. 
    933  * You can optional provide a template name and then the check will be specific to 
    934  * that template. 
     939 * This template tag allows you to determine whether or not you are in a page 
     940 * template. You can optional provide a template name and then the check will be 
     941 * specific to that template. 
    935942 * 
    936943 * @since 2.5.0 
    937944 * @uses $wp_query 
    938945 * 
    939  * @param string $template The specific template name if specific matching is required 
    940  * @return bool False on failure, true if success 
     946 * @param string $template The specific template name if specific matching is required. 
     947 * @return bool False on failure, true if success. 
    941948 */ 
    942949function is_page_template($template = '') { 
    943950        if (!is_page()) { 
     
    963970} 
    964971 
    965972/** 
    966  * wp_post_revision_title() - returns formatted datetimestamp of a revision (linked to that revisions's page) 
     973 * Retrieve formatted date timestamp of a revision (linked to that revisions's page). 
    967974 * 
    968975 * @package WordPress 
    969  * @subpackage Post Revisions 
    970  * @since 2.6 
     976 * @subpackage Post_Revisions 
     977 * @since 2.6.0 
    971978 * 
    972979 * @uses date_i18n() 
    973980 * 
    974  * @param int|object $revision revision ID or revision object 
    975  * @param bool $link optional Link to revisions's page? 
    976  * @return string i18n formatted datetimestamp or localized 'Corrent Revision' 
     981 * @param int|object $revision Revision ID or revision object. 
     982 * @param bool $link Optional, default is true. Link to revisions's page? 
     983 * @return string i18n formatted datetimestamp or localized 'Current Revision'. 
    977984 */ 
    978985function wp_post_revision_title( $revision, $link = true ) { 
    979986        if ( !$revision = get_post( $revision ) ) 
     
    9991006} 
    10001007 
    10011008/** 
    1002  * wp_list_post_revisions() - echoes list of a post's revisions 
     1009 * Display list of a post's revisions. 
    10031010 * 
    1004  * Can output either a UL with edit links or a TABLE with diff interface, and restore action links 
     1011 * Can output either a UL with edit links or a TABLE with diff interface, and 
     1012 * restore action links. 
    10051013 * 
    10061014 * Second argument controls parameters: 
    1007  *   (bool)   parent : include the parent (the "Current Revision") in the list 
    1008  *   (string) format : 'list' or 'form-table'.  'list' outputs UL, 'form-table' outputs TABLE with UI 
    1009  *   (int)    right  : what revision is currently being viewed - used in form-table format 
    1010  *   (int)    left   : what revision is currently being diffed against right - used in form-table format 
     1015 *   (bool)   parent : include the parent (the "Current Revision") in the list. 
     1016 *   (string) format : 'list' or 'form-table'.  'list' outputs UL, 'form-table' 
     1017 *                     outputs TABLE with UI. 
     1018 *   (int)    right  : what revision is currently being viewed - used in 
     1019 *                     form-table format. 
     1020 *   (int)    left   : what revision is currently being diffed against right - 
     1021 *                     used in form-table format. 
    10111022 * 
    10121023 * @package WordPress 
    1013  * @subpackage Post Revisions 
    1014  * @since 2.6 
     1024 * @subpackage Post_Revisions 
     1025 * @since 2.6.0 
    10151026 * 
    10161027 * @uses wp_get_post_revisions() 
    10171028 * @uses wp_post_revision_title() 
    10181029 * @uses get_edit_post_link() 
    10191030 * @uses get_author_name() 
    10201031 * 
    1021  * @param int|object $post_id post ID or post object 
    1022  * @param string|array $args see description @see wp_parse_args() 
     1032 * @todo split into two functions (list, form-table) ? 
     1033 * 
     1034 * @param int|object $post_id Post ID or post object. 
     1035 * @param string|array $args See description {@link wp_parse_args()}. 
     1036 * @return null 
    10231037 */ 
    1024 function wp_list_post_revisions( $post_id = 0, $args = null ) { // TODO? split into two functions (list, form-table) ? 
     1038function wp_list_post_revisions( $post_id = 0, $args = null ) { 
    10251039        if ( !$post = get_post( $post_id ) ) 
    10261040                return; 
    10271041