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.

Built from https://develop.svn.wordpress.org/trunk@41281


git-svn-id: http://core.svn.wordpress.org/trunk@41121 1a063a9b-81f0-0310-95a4-ce76da25c4cd

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;

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.9-alpha-41280';
+$wp_version = '4.9-alpha-41281';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.