From e6da4eebe9d2da77a46a2871ac89ada1abf43a1f Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 7 Jan 2014 16:07:12 +0000 Subject: [PATCH] Inline documentation for core shortcode attributes. Props DrewAPicture, johnbillion. Fixes #25661. Built from https://develop.svn.wordpress.org/trunk@26915 git-svn-id: http://core.svn.wordpress.org/trunk@26796 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-wp-embed.php | 11 ++- wp-includes/media.php | 139 ++++++++++++++++++++++++++------- 2 files changed, 119 insertions(+), 31 deletions(-) diff --git a/wp-includes/class-wp-embed.php b/wp-includes/class-wp-embed.php index 575066ccc0..2670ebe315 100644 --- a/wp-includes/class-wp-embed.php +++ b/wp-includes/class-wp-embed.php @@ -130,7 +130,12 @@ class WP_Embed { * @uses get_post_meta() * @uses update_post_meta() * - * @param array $attr Shortcode attributes. + * @param array $attr { + * Shortcode attributes. Optional. + * + * @type int $width Width of the embed in pixels. + * @type int $height Height of the embed in pixels. + * } * @param string $url The URL attempting to be embedded. * @return string The embed HTML on success, otherwise the original URL. */ @@ -158,6 +163,8 @@ class WP_Embed { * * @since 2.9.0 * + * @see WP_Embed::shortcode() + * * @param mixed $return The shortcode callback function to call. * @param string $url The attempted embed URL. * @param array $attr An array of shortcode attributes. @@ -189,6 +196,8 @@ class WP_Embed { * * @since 2.9.0 * + * @see WP_Embed::shortcode() + * * @param mixed $cache The cached HTML result, stored in post meta. * @param string $url The attempted embed URL. * @param array $attr An array of shortcode attributes. diff --git a/wp-includes/media.php b/wp-includes/media.php index f063e8e8e1..4ce006e362 100644 --- a/wp-includes/media.php +++ b/wp-includes/media.php @@ -623,11 +623,19 @@ add_shortcode('caption', 'img_caption_shortcode'); * * @since 2.6.0 * - * @param array $attr Attributes attributed to the shortcode. + * @param array $attr { + * Attributes of the caption shortcode. + * + * @type string $id ID of the div element for the caption. + * @type string $align Class name that aligns the caption. Default 'alignnone'. Accepts 'alignleft', + * 'aligncenter', alignright', 'alignnone'. + * @type int $width The width of the caption, in pixels. + * @type string $caption The caption text. + * } * @param string $content Optional. Shortcode content. - * @return string + * @return string HTML content to display the caption. */ -function img_caption_shortcode($attr, $content = null) { +function img_caption_shortcode( $attr, $content = null ) { // New-style shortcode with the caption inside the shortcode with the link and image tags. if ( ! isset( $attr['caption'] ) ) { if ( preg_match( '#((?:]+>\s*)?]+>(?:\s*)?)(.*)#is', $content, $matches ) ) { @@ -636,8 +644,21 @@ function img_caption_shortcode($attr, $content = null) { } } - // Allow plugins/themes to override the default caption template. - $output = apply_filters('img_caption_shortcode', '', $attr, $content); + /** + * Filter the default caption shortcode output. + * + * If the filtered output isn't empty, it will be used instead of generating + * the default caption template. + * + * @since 2.6.0 + * + * @see img_caption_shortcode() + * + * @param string $output The caption output. Default empty. + * @param array $attr Attributes of the caption shortcode. + * @param string $content The image element, possibly wrapped in a hyperlink. + */ + $output = apply_filters( 'img_caption_shortcode', '', $attr, $content ); if ( $output != '' ) return $output; @@ -665,16 +686,12 @@ function img_caption_shortcode($attr, $content = null) { * * @since 3.7.0 * - * @param int $caption_width Width in pixels. To remove this inline style, return zero. - * @param array $atts { - * The attributes of the caption shortcode. + * @see img_caption_shortcode() * - * @type string 'id' The ID of the div element for the caption. - * @type string 'align' The class name that aligns the caption. Default 'alignnone'. - * @type int 'width' The width of the image being captioned. - * @type string 'caption' The image's caption. - * } - * @param string $content The image element, possibly wrapped in a hyperlink. + * @param int $caption_width Width of the caption in pixels. To remove this inline style, + * return zero. + * @param array $atts Attributes of the caption shortcode. + * @param string $content The image element, possibly wrapped in a hyperlink. */ $caption_width = apply_filters( 'img_caption_shortcode_width', $caption_width, $atts, $content ); @@ -696,10 +713,27 @@ add_shortcode('gallery', 'gallery_shortcode'); * * @since 2.5.0 * - * @param array $attr Attributes of the shortcode. + * @param array $attr { + * Attributes of the gallery shortcode. + * + * @type string $order Order of the images in the gallery. Default 'ASC'. Accepts 'ASC', 'DESC'. + * @type string $orderby The field to use when ordering the images. Default 'menu_order ID'. + * Accepts any valid SQL ORDERBY statement. + * @type int $id Post ID. + * @type string $itemtag HTML tag to use for each image in the gallery. Default 'dl'. + * @type string $icontag HTML tag to use for each image's icon. Default 'dt'. + * @type string $captiontag HTML tag to use for each image's caption. Default 'dd'. + * @type int $columns Number of columns of images to display. Default 3. + * @type string $size Size of the images to display. Default 'thumbnail'. + * @type string $ids A comma-separated list of IDs of attachments to display. Default empty. + * @type string $include A comma-separated list of IDs of attachments to include. Default empty. + * @type string $exclude A comma-separated list of IDs of attachments to exclude. Default empty. + * @type string $link What to link each image to. Default empty (links to the attachment page). + * Accepts 'file', 'none'. + * } * @return string HTML content to display gallery. */ -function gallery_shortcode($attr) { +function gallery_shortcode( $attr ) { $post = get_post(); static $instance = 0; @@ -712,8 +746,20 @@ function gallery_shortcode($attr) { $attr['include'] = $attr['ids']; } - // Allow plugins/themes to override the default gallery template. - $output = apply_filters('post_gallery', '', $attr); + /** + * Filter the default gallery shortcode output. + * + * If the filtered output isn't empty, it will be used instead of generating + * the default gallery template. + * + * @since 2.5.0 + * + * @see gallery_shortcode() + * + * @param string $output The gallery output. Default empty. + * @param array $attr Attributes of the gallery shortcode. + */ + $output = apply_filters( 'post_gallery', '', $attr ); if ( $output != '' ) return $output; @@ -875,7 +921,17 @@ function wp_get_audio_extensions() { * * @since 3.6.0 * - * @param array $attr Attributes of the shortcode. + * @param array $attr { + * Attributes of the audio shortcode. + * + * @type string $src URL to the source of the audio file. Default empty. + * @type string $loop The 'loop' attribute for the `