WordPress.org

Make WordPress Core

Ticket #7659: 7659.r8947.diff

File 7659.r8947.diff, 14.8 KB (added by jacobsantos, 6 years ago)

Skeleton inline documentation and fixes based off of r8947

  • 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 * 
    375368 * {@internal Missing Long Description}} 
    376369 * 
    377  * @package WordPress 
    378  * @subpackage Post 
    379  * @since 2.7 
     370 * @since 2.7.0 
    380371 * 
    381372 * @param int $post_id An optional post ID 
    382373 */ 
     
    388379} 
    389380 
    390381/** 
    391  * wp_link_pages() - {@internal Missing Short Description}} 
     382 * {@internal Missing Short Description}} 
    392383 * 
    393384 * {@internal Missing Long Description}} 
    394385 * 
     
    478469// 
    479470 
    480471/** 
    481  * post_custom() - {@internal Missing Short Description}} 
     472 * {@internal Missing Short Description}} 
    482473 * 
    483474 * {@internal Missing Long Description}} 
    484475 * 
     
    499490 
    500491// this will probably change at some point... 
    501492/** 
    502  * the_meta() - {@internal Missing Short Description}} 
     493 * {@internal Missing Short Description}} 
    503494 * 
    504495 * {@internal Missing Long Description}} 
    505496 * 
     
    527518// 
    528519 
    529520/** 
    530  * wp_dropdown_pages() - {@internal Missing Short Description}} 
     521 * {@internal Missing Short Description}} 
    531522 * 
    532523 * {@internal Missing Long Description}} 
    533524 * 
     
    566557} 
    567558 
    568559/** 
    569  * wp_list_pages() - {@internal Missing Short Description}} 
     560 * {@internal Missing Short Description}} 
    570561 * 
    571562 * {@internal Missing Long Description}} 
    572563 * 
     
    661652// 
    662653 
    663654/** 
    664  * walk_page_tree() - {@internal Missing Short Description}} 
     655 * {@internal Missing Short Description}} 
    665656 * 
    666657 * {@internal Missing Long Description}} 
    667658 * 
     
    676667} 
    677668 
    678669/** 
    679  * walk_page_dropdown_tree() - {@internal Missing Short Description}} 
     670 * {@internal Missing Short Description}} 
    680671 * 
    681672 * {@internal Missing Long Description}} 
    682673 * 
     
    695686// 
    696687 
    697688/** 
    698  * the_attachment_link() - {@internal Missing Short Description}} 
     689 * {@internal Missing Short Description}} 
    699690 * 
    700691 * {@internal Missing Long Description}} 
    701692 * 
     
    712703                echo wp_get_attachment_link($id, 'thumbnail', $permalink); 
    713704} 
    714705 
    715 // get an attachment page link using an image or icon if possible 
     706/** 
     707 * Retrieve an attachment page link using an image or icon, if possible. 
     708 * 
     709 * {@internal Missing Long Description}} 
     710 * 
     711 * @since unknown 
     712 * 
     713 * @param unknown_type $id 
     714 * @param unknown_type $size 
     715 * @param unknown_type $permalink 
     716 * @param unknown_type $icon 
     717 * @return unknown 
     718 */ 
    716719function wp_get_attachment_link($id = 0, $size = 'thumbnail', $permalink = false, $icon = false) { 
    717720        $id = intval($id); 
    718721        $_post = & get_post( $id ); 
     
    733736 
    734737} 
    735738 
    736 // deprecated - use wp_get_attachment_link() 
     739/** 
     740 * {@internal Missing Short Description}} 
     741 * 
     742 * {@internal Missing Long Description}} 
     743 * 
     744 * @since unknown 
     745 * @deprecated Use {@link wp_get_attachment_link()} 
     746 * @see wp_get_attachment_link() Use instead. 
     747 * 
     748 * @param unknown_type $id 
     749 * @param unknown_type $fullsize 
     750 * @param unknown_type $max_dims 
     751 * @param unknown_type $permalink 
     752 * @return unknown 
     753 */ 
    737754function get_the_attachment_link($id = 0, $fullsize = false, $max_dims = false, $permalink = false) { 
    738755        $id = (int) $id; 
    739756        $_post = & get_post($id); 
     
    750767        return "<a href='$url' title='$post_title'>$innerHTML</a>"; 
    751768} 
    752769 
    753  
    754 // deprecated: use wp_get_attachment_image_src() 
    755770/** 
    756  * get_attachment_icon_src() - {@internal Missing Short Description}} 
     771 * {@internal Missing Short Description}} 
    757772 * 
    758773 * {@internal Missing Long Description}} 
    759774 * 
    760775 * @since 2.1.0 
     776 * @deprecated Use {@link wp_get_attachment_image_src()} 
     777 * @see wp_get_attachment_image_src() Use instead. 
    761778 * 
    762779 * @param unknown_type $id 
    763780 * @param unknown_type $fullsize 
     
    794811        return array($src, $src_file); 
    795812} 
    796813 
    797 // deprecated: use wp_get_attachment_image() 
    798814/** 
    799  * get_attachment_icon() - {@internal Missing Short Description}} 
     815 * {@internal Missing Short Description}} 
    800816 * 
    801817 * {@internal Missing Long Description}} 
    802818 * 
    803819 * @since 2.0.0 
     820 * @deprecated Use {@link wp_get_attachment_image()} 
     821 * @see wp_get_attachment_image() Use instead of. 
    804822 * 
    805823 * @param unknown_type $id 
    806824 * @param unknown_type $fullsize 
     
    850868        return apply_filters( 'attachment_icon', $icon, $post->ID ); 
    851869} 
    852870 
    853 // deprecated: use wp_get_attachment_image() 
    854871/** 
    855  * get_attachment_innerHTML() - {@internal Missing Short Description}} 
     872 * {@internal Missing Short Description}} 
    856873 * 
    857874 * {@internal Missing Long Description}} 
    858875 * 
    859876 * @since 2.0.0 
     877 * @deprecated Use {@link wp_get_attachment_image()} 
     878 * @see wp_get_attachment_image() Use instead. 
    860879 * 
    861880 * @param unknown_type $id 
    862881 * @param unknown_type $fullsize 
     
    878897} 
    879898 
    880899/** 
    881  * prepend_attachment() - {@internal Missing Short Description}} 
     900 * {@internal Missing Short Description}} 
    882901 * 
    883902 * {@internal Missing Long Description}} 
    884903 * 
     
    907926// 
    908927 
    909928/** 
    910  * get_the_password_form() - {@internal Missing Short Description}} 
     929 * {@internal Missing Short Description}} 
    911930 * 
    912931 * {@internal Missing Long Description}} 
    913932 * 
     
    927946} 
    928947 
    929948/** 
    930  * is_page_template() - Determine wether or not we are in a page template 
     949 * Whether currently in a page template. 
    931950 * 
    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. 
     951 * This template tag allows you to determine whether or not you are in a page 
     952 * template. You can optional provide a template name and then the check will be 
     953 * specific to that template. 
    935954 * 
    936955 * @since 2.5.0 
    937956 * @uses $wp_query 
    938957 * 
    939  * @param string $template The specific template name if specific matching is required 
    940  * @return bool False on failure, true if success 
     958 * @param string $template The specific template name if specific matching is required. 
     959 * @return bool False on failure, true if success. 
    941960 */ 
    942961function is_page_template($template = '') { 
    943962        if (!is_page()) { 
     
    963982} 
    964983 
    965984/** 
    966  * wp_post_revision_title() - returns formatted datetimestamp of a revision (linked to that revisions's page) 
     985 * Retrieve formatted date timestamp of a revision (linked to that revisions's page). 
    967986 * 
    968987 * @package WordPress 
    969  * @subpackage Post Revisions 
    970  * @since 2.6 
     988 * @subpackage Post_Revisions 
     989 * @since 2.6.0 
    971990 * 
    972991 * @uses date_i18n() 
    973992 * 
    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' 
     993 * @param int|object $revision Revision ID or revision object. 
     994 * @param bool $link Optional, default is true. Link to revisions's page? 
     995 * @return string i18n formatted datetimestamp or localized 'Current Revision'. 
    977996 */ 
    978997function wp_post_revision_title( $revision, $link = true ) { 
    979998        if ( !$revision = get_post( $revision ) ) 
     
    9991018} 
    10001019 
    10011020/** 
    1002  * wp_list_post_revisions() - echoes list of a post's revisions 
     1021 * Display list of a post's revisions. 
    10031022 * 
    1004  * Can output either a UL with edit links or a TABLE with diff interface, and restore action links 
     1023 * Can output either a UL with edit links or a TABLE with diff interface, and 
     1024 * restore action links. 
    10051025 * 
    10061026 * 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 
     1027 *   (bool)   parent : include the parent (the "Current Revision") in the list. 
     1028 *   (string) format : 'list' or 'form-table'.  'list' outputs UL, 'form-table' 
     1029 *                     outputs TABLE with UI. 
     1030 *   (int)    right  : what revision is currently being viewed - used in 
     1031 *                     form-table format. 
     1032 *   (int)    left   : what revision is currently being diffed against right - 
     1033 *                     used in form-table format. 
    10111034 * 
    10121035 * @package WordPress 
    1013  * @subpackage Post Revisions 
    1014  * @since 2.6 
     1036 * @subpackage Post_Revisions 
     1037 * @since 2.6.0 
    10151038 * 
    10161039 * @uses wp_get_post_revisions() 
    10171040 * @uses wp_post_revision_title() 
    10181041 * @uses get_edit_post_link() 
    10191042 * @uses get_author_name() 
    10201043 * 
    1021  * @param int|object $post_id post ID or post object 
    1022  * @param string|array $args see description @see wp_parse_args() 
     1044 * @todo split into two functions (list, form-table) ? 
     1045 * 
     1046 * @param int|object $post_id Post ID or post object. 
     1047 * @param string|array $args See description {@link wp_parse_args()}. 
     1048 * @return null 
    10231049 */ 
    1024 function wp_list_post_revisions( $post_id = 0, $args = null ) { // TODO? split into two functions (list, form-table) ? 
     1050function wp_list_post_revisions( $post_id = 0, $args = null ) { 
    10251051        if ( !$post = get_post( $post_id ) ) 
    10261052                return; 
    10271053