WordPress.org

Make WordPress Core

Ticket #7659: 7659.r8947.diff

File 7659.r8947.diff, 14.8 KB (added by jacobsantos, 10 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