WordPress.org
Get WordPress

Make WordPress Core

Ticket #7659: 7659.r8976.diff

File 7659.r8976.diff, 16.5 KB (added by jacobsantos, 16 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