From b90eb2217657e90ee60ad4d0f566ffbd6c604fba Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Sun, 20 Aug 2017 19:43:58 +0000
Subject: [PATCH] Docs: Improve documentation for `add_shortcode()` by:

* Removing inline examples already listed in the Code Reference
* Improving the summary and description to explain how tag conflicts are handled
* Supplement the docs for the `$func` parameter by describing the three arguments passed to a shortcode callback.

Props grapplerulrich for the initial patch.
Fixes #37222.


git-svn-id: https://develop.svn.wordpress.org/trunk@41281 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/shortcodes.php | 46 ++++++++--------------------------
 1 file changed, 10 insertions(+), 36 deletions(-)

diff --git a/src/wp-includes/shortcodes.php b/src/wp-includes/shortcodes.php
index 8cd37d0ae4..23305bda3d 100644
--- a/src/wp-includes/shortcodes.php
+++ b/src/wp-includes/shortcodes.php
@@ -42,49 +42,23 @@
 $shortcode_tags = array();
 
 /**
- * Add hook for shortcode tag.
+ * Adds a new shortcode.
  *
- * There can only be one hook for each shortcode. Which means that if another
- * plugin has a similar shortcode, it will override yours or yours will override
- * theirs depending on which order the plugins are included and/or ran.
- *
- * Simplest example of a shortcode tag using the API:
- *
- *     // [footag foo="bar"]
- *     function footag_func( $atts ) {
- *         return "foo = {
- *             $atts[foo]
- *         }";
- *     }
- *     add_shortcode( 'footag', 'footag_func' );
- *
- * Example with nice attribute defaults:
- *
- *     // [bartag foo="bar"]
- *     function bartag_func( $atts ) {
- *         $args = shortcode_atts( array(
- *             'foo' => 'no foo',
- *             'baz' => 'default baz',
- *         ), $atts );
- *
- *         return "foo = {$args['foo']}";
- *     }
- *     add_shortcode( 'bartag', 'bartag_func' );
- *
- * Example with enclosed content:
- *
- *     // [baztag]content[/baztag]
- *     function baztag_func( $atts, $content = '' ) {
- *         return "content = $content";
- *     }
- *     add_shortcode( 'baztag', 'baztag_func' );
+ * Care should be taken, either through prefixing or other means,to ensure
+ * that the shortcode tag being added is unique and will not conflict with
+ * other, already-added shortcode tags. In the event of a duplicated tag, the
+ * tag loaded last will take precedence.
  *
  * @since 2.5.0
  *
  * @global array $shortcode_tags
  *
  * @param string   $tag  Shortcode tag to be searched in post content.
- * @param callable $func Hook to run when shortcode is found.
+ * @param callable $func The callback function to run when the shortcode is found.
+ *                       Every shortcode callback is passed three parameters by default,
+ *                       including an array of attributes (`$atts`), the content
+ *                       the shortcode was found in (`$content`), and finally
+ *                       the shortcode tag itself (`$shortcode_tag`), in that order.
  */
 function add_shortcode($tag, $func) {
 	global $shortcode_tags;