From 268b6882471133c904e2249abe30edf0e7c62bc9 Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Mon, 24 Feb 2014 19:41:24 +0000
Subject: [PATCH] Inline documentation improvements for `wp_get_playlist()`.

* Adds a missing `@param` description in the PHPDoc.
* Adds hook documentation for the `post_playlist` filter.
* Other comment cleanup.


git-svn-id: https://develop.svn.wordpress.org/trunk@27240 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/media.php | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/src/wp-includes/media.php b/src/wp-includes/media.php
index ff1e1362cc..ed5d363f08 100644
--- a/src/wp-includes/media.php
+++ b/src/wp-includes/media.php
@@ -941,8 +941,9 @@ function gallery_shortcode( $attr ) {
  *
  * @since 3.9.0
  *
- * @param array $attr Attributes of the shortcode.
- * @return string $type Type of playlist. Defaults to audio, video is also supported
+ * @param array  $attr Attributes of the shortcode.
+ * @param string $type Type of playlist. Accepts 'audio' and 'video'.
+ * @return string Playlist output. Empty string if the passed type is unsupported.
  */
 function wp_get_playlist( $attr, $type ) {
 	global $content_width;
@@ -963,13 +964,27 @@ function wp_get_playlist( $attr, $type ) {
 		$attr['include'] = $attr['ids'];
 	}
 
-	// Allow plugins/themes to override the default gallery template.
+	/**
+	 * Filter the playlist output.
+	 *
+	 * Passing a non-empty value to the filter will short-circuit generation
+	 * of the default playlist output, returning the passed value instead.
+	 *
+	 * @since 3.9.0
+	 *
+	 * @param string $output Playlist output. Default empty.
+	 * @param array  $attr   Array of shortcode attributes.
+	 * @param string $type   Type of playlist to generate output for.
+	 */
 	$output = apply_filters( 'post_playlist', '', $attr, $type );
 	if ( $output != '' ) {
 		return $output;
 	}
 
-	// We're trusting author input, so let's at least make sure it looks like a valid orderby statement
+	/*
+	 * We're trusting author input, so let's at least make sure it looks
+	 * like a valid orderby statement.
+	 */
 	if ( isset( $attr['orderby'] ) ) {
 		$attr['orderby'] = sanitize_sql_orderby( $attr['orderby'] );
 		if ( ! $attr['orderby'] )