Add better add_shortcode documentation

[grapplerulrich]

When looking at the ​add_shortcode() documentation is it is not clear what $parameters the the function $func has.

Only by looking at ​do_shortcode_tag() can you see that there are three parameters $args, $inline_content and $shortcode_tag

[grapplerulrich]

Small improvement by updating the code example

[grapplerulrich]

A partial fix for this would be to improve the code example which uses all of the parameters.

[morganestes]

It would also help to include some examples in the Code Reference page ​https://developer.wordpress.org/reference/functions/add_shortcode/. The inline docs will get parsed for the inline/canonical example, but can be expanded on in the examples on that page.

[DrewAPicture]

In 41281:

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.

[DrewAPicture]

In 41282:

Shortcodes: Rename the $func parameter for add_shortcode() to $callback to improve clarity.

See #37222. See #41017.

[DrewAPicture]

In 41283:

Docs: Clarify that the second parameter passed to a shortcode callback is the shortcode content or null, rather than the content the shortcode was found in.

See #37222.

[grapplerulrich]

@DrewAPicture Thank you for fixing this.

I think you meant to add a space instead of a comma between "means" and "to" in [41281]

Care should be taken, either through prefixing or other means,to ensure

[DrewAPicture]

In 41286:

Docs: Fix a typo in the DocBlock description for add_shortcode() introduced in [41281].

Props grapplerulrich.
See #37222.