Make WordPress Core

Changeset 8874


Ignore:
Timestamp:
09/12/2008 04:31:41 AM (16 years ago)
Author:
azaozz
Message:

Inline Documentation for general-template.php, props jacobsantos, fixes #5640

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/general-template.php

    r8835 r8874  
    283283
    284284/**
    285  * {@internal Missing Short Description}}
    286  *
    287  * {@internal Missing Long Description}}
     285 * Display or retrieve page title for all areas of blog.
     286 *
     287 * By default, the page title will display the separator before the page title,
     288 * so that the blog title will be before the page title. This is not good for
     289 * title display, since the blog title shows up on most tabs and not what is
     290 * important, which is the page that the user is looking at.
     291 *
     292 * There are also SEO benefits to having the blog title after or to the 'right'
     293 * or the page title. However, it is mostly common sense to have the blog title
     294 * to the right with most browsers supporting tabs. You can achieve this by
     295 * using the seplocation parameter and setting the value to 'right'. This change
     296 * was introduced around 2.5.0, in case backwards compatibility of themes is
     297 * important.
    288298 *
    289299 * @since 1.0.0
    290300 *
    291  * @param unknown_type $sep
    292  * @param unknown_type $display
    293  * @return unknown
     301 * @param string $sep Optional, default is '»'. How to separate the various items within the page title.
     302 * @param bool $display Optional, default is true. Whether to display or retrieve title.
     303 * @param string $seplocation Optional. Direction to display title, 'right'.
     304 * @return string|null String on retrieve, null when displaying.
    294305 */
    295306function wp_title($sep = '»', $display = true, $seplocation = '') {
     
    399410
    400411/**
    401  * {@internal Missing Short Description}}
    402  *
    403  * {@internal Missing Long Description}}
     412 * Display or retrieve page title for post.
     413 *
     414 * This is optimized for single.php template file for displaying the post title.
     415 * Only useful for posts, does not support pages for example.
     416 *
     417 * It does not support placing the separator after the title, but by leaving the
     418 * prefix parameter empty, you can set the title separator manually. The prefix
     419 * does not automatically place a space between the prefix, so if there should
     420 * be a space, the parameter value will need to have it at the end.
    404421 *
    405422 * @since 0.71
    406423 * @uses $wpdb
    407424 *
    408  * @param unknown_type $prefix
    409  * @param unknown_type $display
    410  * @return unknown
     425 * @param string $prefix Optional. What to display before the title.
     426 * @param bool $display Optional, default is true. Whether to display or retrieve title.
     427 * @return string|null Title when retrieving, null when displaying or failure.
    411428 */
    412429function single_post_title($prefix = '', $display = true) {
     
    429446
    430447/**
    431  * {@internal Missing Short Description}}
    432  *
    433  * {@internal Missing Long Description}}
     448 * Display or retrieve page title for category archive.
     449 *
     450 * This is useful for category template file or files, because it is optimized
     451 * for category page title and with less overhead than {@link wp_title()}.
     452 *
     453 * It does not support placing the separator after the title, but by leaving the
     454 * prefix parameter empty, you can set the title separator manually. The prefix
     455 * does not automatically place a space between the prefix, so if there should
     456 * be a space, the parameter value will need to have it at the end.
    434457 *
    435458 * @since 0.71
    436459 *
    437  * @param unknown_type $prefix
    438  * @param unknown_type $display
    439  * @return unknown
     460 * @param string $prefix Optional. What to display before the title.
     461 * @param bool $display Optional, default is true. Whether to display or retrieve title.
     462 * @return string|null Title when retrieving, null when displaying or failure.
    440463 */
    441464function single_cat_title($prefix = '', $display = true ) {
     
    455478
    456479/**
    457  * {@internal Missing Short Description}}
    458  *
    459  * {@internal Missing Long Description}}
     480 * Display or retrieve page title for tag post archive.
     481 *
     482 * Useful for tag template files for displaying the tag page title. It has less
     483 * overhead than {@link wp_title()}, because of its limited implementation.
     484 *
     485 * It does not support placing the separator after the title, but by leaving the
     486 * prefix parameter empty, you can set the title separator manually. The prefix
     487 * does not automatically place a space between the prefix, so if there should
     488 * be a space, the parameter value will need to have it at the end.
    460489 *
    461490 * @since 2.3.0
    462491 *
    463  * @param unknown_type $prefix
    464  * @param unknown_type $display
    465  * @return unknown
     492 * @param string $prefix Optional. What to display before the title.
     493 * @param bool $display Optional, default is true. Whether to display or retrieve title.
     494 * @return string|null Title when retrieving, null when displaying or failure.
    466495 */
    467496function single_tag_title($prefix = '', $display = true ) {
     
    486515
    487516/**
    488  * {@internal Missing Short Description}}
    489  *
    490  * {@internal Missing Long Description}}
     517 * Display or retrieve page title for post archive based on date.
     518 *
     519 * Useful for when the template only needs to display the month and year, if
     520 * either are available. Optimized for just this purpose, so if it is all that
     521 * is needed, should be better than {@link wp_title()}.
     522 *
     523 * It does not support placing the separator after the title, but by leaving the
     524 * prefix parameter empty, you can set the title separator manually. The prefix
     525 * does not automatically place a space between the prefix, so if there should
     526 * be a space, the parameter value will need to have it at the end.
    491527 *
    492528 * @since 0.71
    493529 *
    494  * @param unknown_type $prefix
    495  * @param unknown_type $display
    496  * @return unknown
     530 * @param string $prefix Optional. What to display before the title.
     531 * @param bool $display Optional, default is true. Whether to display or retrieve title.
     532 * @return string|null Title when retrieving, null when displaying or failure.
    497533 */
    498534function single_month_title($prefix = '', $display = true ) {
     
    522558
    523559/**
    524  * {@internal Missing Short Description}}
    525  *
    526  * {@internal Missing Long Description}}
     560 * Retrieve archive link content based on predefined or custom code.
     561 *
     562 * The format can be one of four styles. The 'link' for head element, 'option'
     563 * for use in the select element, 'html' for use in list (either ol or ul HTML
     564 * elements). Custom content is also supported using the before and after
     565 * parameters.
     566 *
     567 * The 'link' format uses the link HTML element with the <em>archives</em>
     568 * relationship. The before and after parameters are not used. The text
     569 * parameter is used to describe the link.
     570 *
     571 * The 'option' format uses the option HTML element for use in select element.
     572 * The value is the url parameter and the before and after parameters are used
     573 * between the text description.
     574 *
     575 * The 'html' format, which is the default, uses the li HTML element for use in
     576 * the list HTML elements. The before parameter is before the link and the after
     577 * parameter is after the closing link.
     578 *
     579 * The custom format uses the before parameter before the link ('a' HTML
     580 * element) and the after parameter after the closing link tag. If the above
     581 * three values for the format are not used, then custom format is assumed.
    527582 *
    528583 * @since 1.0.0
     
    530585 * @link http://icecode.com/ link navigation hack by Orien
    531586 *
    532  * @param unknown_type $url
    533  * @param unknown_type $text
    534  * @param unknown_type $format
    535  * @param unknown_type $before
    536  * @param unknown_type $after
    537  * @return unknown
     587 * @param string $url URL to archive.
     588 * @param string $text Archive text description.
     589 * @param string $format Optional, default is 'html'. Can be 'link', 'option', 'html', or custom.
     590 * @param string $before Optional.
     591 * @param string $after Optional.
     592 * @return string HTML link content for archive.
    538593 */
    539594function get_archives_link($url, $text, $format = 'html', $before = '', $after = '') {
     
    557612
    558613/**
    559  * {@internal Missing Short Description}}
    560  *
    561  * {@internal Missing Long Description}}
     614 * Display archive links based on type and format.
     615 *
     616 * The 'type' argument offers a few choices and by default will display monthly
     617 * archive links. The other options for values are 'daily', 'weekly', 'monthly',
     618 * 'yearly', 'postbypost' or 'alpha'. Both 'postbypost' and 'alpha' display the
     619 * same archive link list, the difference between the two is that 'alpha'
     620 * will order by post title and 'postbypost' will order by post date.
     621 *
     622 * The date archives will logically display dates with links to the archive post
     623 * page. The 'postbypost' and 'alpha' values for 'type' argument will display
     624 * the post titles.
     625 *
     626 * The 'limit' argument will only display a limited amount of links, specified
     627 * by the 'limit' integer value. By default, there is no limit. The
     628 * 'show_post_count' argument will show how many posts are within the archive.
     629 * By default, the 'show_post_count' argument is set to false.
     630 *
     631 * For the 'format', 'before', and 'after' arguments, see {@link
     632 * get_archives_link()}. The values of these arguments have to do with that
     633 * function.
    562634 *
    563635 * @since 1.2.0
    564636 *
    565  * @param unknown_type $args
     637 * @param string|array $args Optional. Override defaults.
    566638 */
    567639function wp_get_archives($args = '') {
     
    622694            $afterafter = $after;
    623695            foreach ( (array) $arcresults as $arcresult ) {
    624                 $url    = get_month_link($arcresult->year,  $arcresult->month);
     696                $url = get_month_link( $arcresult->year, $arcresult->month );
    625697                $text = sprintf(__('%1$s %2$d'), $wp_locale->get_month($arcresult->month), $arcresult->year);
    626698                if ( $show_post_count )
     
    731803
    732804/**
    733  * {@internal Missing Short Description}}
    734  *
    735  * {@internal Missing Long Description}}
     805 * Get number of days since the start of the week.
    736806 *
    737807 * @since 1.5.0
     
    739809 *
    740810 * @param int $num Number of day.
    741  * @return int
     811 * @return int Days since the start of the week.
    742812 */
    743813function calendar_week_mod($num) {
     
    747817
    748818/**
    749  * {@internal Missing Short Description}}
    750  *
    751  * {@internal Missing Long Description}}
     819 * Display calendar with days that have posts as links.
     820 *
     821 * The calendar is cached, which will be retrieved, if it exists. If there are
     822 * no posts for the month, then it will not be displayed.
    752823 *
    753824 * @since 1.0.0
    754825 *
    755  * @param unknown_type $initial
     826 * @param bool $initial Optional, default is true. Use initial calendar names.
    756827 */
    757828function get_calendar($initial = true) {
     
    9631034
    9641035/**
    965  * {@internal Missing Short Description}}
    966  *
    967  * {@internal Missing Long Description}}
     1036 * Display all of the allowed tags in HTML format with attributes.
     1037 *
     1038 * This is useful for displaying in the comment area, which elements and
     1039 * attributes are supported. As well as any plugins which want to display it.
    9681040 *
    9691041 * @since 1.0.1
    9701042 * @uses $allowedtags
    9711043 *
    972  * @return unknown
     1044 * @return string HTML allowed tags entity encoded.
    9731045 */
    9741046function allowed_tags() {
     
    13111383
    13121384/**
    1313  * {@internal Missing Short Description}}
    1314  *
    1315  * {@internal Missing Long Description}}
     1385 * Display visual editor forms: TinyMCE, or HTML, or both.
     1386 *
     1387 * The amount of rows the text area will have for the content has to be between
     1388 * 3 and 100 or will default at 12. There is only one option used for all users,
     1389 * named 'default_post_edit_rows'.
     1390 *
     1391 * If the user can not use the rich editor (TinyMCE), then the switch button
     1392 * will not be displayed.
    13161393 *
    13171394 * @since 2.1.0
    13181395 *
    1319  * @param unknown_type $content
    1320  * @param unknown_type $id
    1321  * @param unknown_type $prev_id
     1396 * @param string $content Textarea content.
     1397 * @param string $id HTML ID attribute value.
     1398 * @param string $prev_id HTML ID name for switching back and forth between visual editors.
     1399 * @param bool $media_buttons Optional, default is true. Whether to display media buttons.
     1400 * @param int $tab_index Optional, default is 2. Tabindex for textarea element.
    13221401 */
    13231402function the_editor($content, $id = 'content', $prev_id = 'title', $media_buttons = true, $tab_index = 2) {
     
    14421521
    14431522/**
    1444  * {@internal Missing Short Description}}
    1445  *
    1446  * {@internal Missing Long Description}}
     1523 * Retrieve paginated link for archive post pages.
     1524 *
     1525 * Technically, the function can be used to create paginated link list for any
     1526 * area. The 'base' argument is used to reference the url, which will be used to
     1527 * create the paginated links. The 'format' argument is then used for replacing
     1528 * the page number. It is however, most likely and by default, to be used on the
     1529 * archive post pages.
     1530 *
     1531 * The 'type' argument controls format of the returned value. The default is
     1532 * 'plain', which is just a string with the links separated by a newline
     1533 * character. The other possible values are either 'array' or 'list'. The
     1534 * 'array' value will return an array of the paginated link list to offer full
     1535 * control of display. The 'list' value will place all of the paginated links in
     1536 * an unordered HTML list.
     1537 *
     1538 * The 'total' argument is the total amount of pages and is an integer. The
     1539 * 'current' argument is the current page number and is also an integer.
     1540 *
     1541 * An example of the 'base' argument is "http://example.com/all_posts.php%_%"
     1542 * and the '%_%' is required. The '%_%' will be replaced by the contents of in
     1543 * the 'format' argument. An example for the 'format' argument is "?page=%#%"
     1544 * and the '%#%' is also required. The '%#%' will be replaced with the page
     1545 * number.
     1546 *
     1547 * You can include the previous and next links in the list by setting the
     1548 * 'prev_next' argument to true, which it is by default. You can set the
     1549 * previous text, by using the 'prev_text' argument. You can set the next text
     1550 * by setting the 'next_text' argument.
     1551 *
     1552 * If the 'show_all' argument is set to true, then it will show all of the pages
     1553 * instead of a short list of the pages near the current page. By default, the
     1554 * 'show_all' is set to false and controlled by the 'end_size' and 'mid_size'
     1555 * arguments. The 'end_size' argument is how many numbers on either the start
     1556 * and the end list edges, by default is 1. The 'mid_size' argument is how many
     1557 * numbers to either side of current page, but not including current page.
     1558 *
     1559 * It is possible to add query vars to the link by using the 'add_args' argument
     1560 * and see {@link add_query_arg()} for more information.
    14471561 *
    14481562 * @since 2.1.0
    14491563 *
    1450  * @param unknown_type $args
    1451  * @return unknown
     1564 * @param string|array $args Optional. Override defaults.
     1565 * @return array|string String of page links or array of page links.
    14521566 */
    14531567function paginate_links( $args = '' ) {
     
    14611575        'prev_text' => __('&laquo; Previous'),
    14621576        'next_text' => __('Next &raquo;'),
    1463         'end_size' => 1, // How many numbers on either end including the end
    1464         'mid_size' => 2, // How many numbers to either side of current not including current
     1577        'end_size' => 1,
     1578        'mid_size' => 2,
    14651579        'type' => 'plain',
    1466         'add_args' => false // array of query args to aadd
     1580        'add_args' => false // array of query args to add
    14671581    );
    14681582
     
    14711585
    14721586    // Who knows what else people pass in $args
    1473     $total  = (int) $total;
     1587    $total = (int) $total;
    14741588    if ( $total < 2 )
    14751589        return;
Note: See TracChangeset for help on using the changeset viewer.