Make WordPress Core

Ticket #5640: 5640.r8855.diff

File 5640.r8855.diff, 10.7 KB (added by jacobsantos, 15 years ago)

Two functions left to document, based off of r8855.

  • general-template.php

     
    282282}
    283283
    284284/**
    285  * {@internal Missing Short Description}}
     285 * Display or retrieve page title for all areas of blog.
    286286 *
    287  * {@internal Missing Long Description}}
     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.
    288291 *
     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.
     298 *
    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 = '') {
    296307        global $wpdb, $wp_locale, $wp_query;
     
    398409}
    399410
    400411/**
    401  * {@internal Missing Short Description}}
     412 * Display or retrieve page title for post.
    402413 *
    403  * {@internal Missing Long Description}}
     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.
    404416 *
     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.
     421 *
    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) {
    413430        global $wpdb;
     
    428445}
    429446
    430447/**
    431  * {@internal Missing Short Description}}
     448 * Display or retrieve page title for category archive.
    432449 *
    433  * {@internal Missing Long Description}}
     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()}.
    434452 *
     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.
     457 *
    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 ) {
    442465        $cat = intval( get_query_var('cat') );
     
    454477}
    455478
    456479/**
    457  * {@internal Missing Short Description}}
     480 * Display or retrieve page title for tag post archive.
    458481 *
    459  * {@internal Missing Long Description}}
     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.
    460484 *
     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.
     489 *
    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 ) {
    468497        if ( !is_tag() )
     
    485514}
    486515
    487516/**
    488  * {@internal Missing Short Description}}
     517 * Display or retrieve page title for post archive based on date.
    489518 *
    490  * {@internal Missing Long Description}}
     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()}.
    491522 *
     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.
     527 *
    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 ) {
    499535        global $wp_locale;
     
    521557}
    522558
    523559/**
    524  * {@internal Missing Short Description}}
     560 * Retrieve archive link content based on predefined or custom code.
    525561 *
    526  * {@internal Missing Long Description}}
     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.
    527566 *
     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.
     582 *
    528583 * @since 1.0.0
    529584 * @author Orien
    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 = '') {
    540595        $text = wptexturize($text);
     
    730785}
    731786
    732787/**
    733  * {@internal Missing Short Description}}
     788 * Get number of days since the start of the week.
    734789 *
    735  * {@internal Missing Long Description}}
    736  *
    737790 * @since 1.5.0
    738791 * @usedby get_calendar()
    739792 *
    740793 * @param int $num Number of day.
    741  * @return int
     794 * @return int Days since the start of the week.
    742795 */
    743796function calendar_week_mod($num) {
    744797        $base = 7;
     
    746799}
    747800
    748801/**
    749  * {@internal Missing Short Description}}
     802 * Display calendar with days that have posts as links.
    750803 *
    751  * {@internal Missing Long Description}}
     804 * The calendar is cached, which will be retrieved, if it exists. If there are
     805 * no posts for the month, then it will not be displayed.
    752806 *
    753807 * @since 1.0.0
    754808 *
    755  * @param unknown_type $initial
     809 * @param bool $initial Optional, default is true. Use initial calendar names.
    756810 */
    757811function get_calendar($initial = true) {
    758812        global $wpdb, $m, $monthnum, $year, $wp_locale, $posts;
     
    9621016add_action( 'update_option_start_of_week', 'delete_get_calendar_cache' );
    9631017
    9641018/**
    965  * {@internal Missing Short Description}}
     1019 * Display all of the allowed tags in HTML format with attributes.
    9661020 *
    967  * {@internal Missing Long Description}}
     1021 * This is useful for displaying in the comment area, which elements and
     1022 * attributes are supported. As well as any plugins which want to display it.
    9681023 *
    9691024 * @since 1.0.1
    9701025 * @uses $allowedtags
    9711026 *
    972  * @return unknown
     1027 * @return string HTML allowed tags entity encoded.
    9731028 */
    9741029function allowed_tags() {
    9751030        global $allowedtags;
     
    13101365}
    13111366
    13121367/**
    1313  * {@internal Missing Short Description}}
     1368 * Display visual editor forms: TinyMCE, or HTML, or both.
    13141369 *
    1315  * {@internal Missing Long Description}}
     1370 * The amount of rows the text area will have for the content has to be between
     1371 * 3 and 100 or will default at 12. There is only one option used for all users,
     1372 * named 'default_post_edit_rows'.
    13161373 *
     1374 * If the user can not use the rich editor (TinyMCE), then the switch button
     1375 * will not be displayed.
     1376 *
    13171377 * @since 2.1.0
    13181378 *
    1319  * @param unknown_type $content
    1320  * @param unknown_type $id
    1321  * @param unknown_type $prev_id
     1379 * @param string $content Textarea content.
     1380 * @param string $id HTML ID attribute value.
     1381 * @param string $prev_id HTML ID name for switching back and forth between visual editors.
     1382 * @param bool $media_buttons Optional, default is true. Whether to display media buttons.
     1383 * @param int $tab_index Optional, default is 2. Tabindex for textarea element.
    13221384 */
    13231385function the_editor($content, $id = 'content', $prev_id = 'title', $media_buttons = true, $tab_index = 2) {
    13241386        $rows = get_option('default_post_edit_rows');
     
    14471509 *
    14481510 * @since 2.1.0
    14491511 *
    1450  * @param unknown_type $args
     1512 * @param string|array $args Optional. Override defaults.
    14511513 * @return unknown
    14521514 */
    14531515function paginate_links( $args = '' ) {