WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 2 years ago

Last modified 2 years ago

#37222 closed enhancement (fixed)

Add better add_shortcode documentation

Reported by: grapplerulrich Owned by: DrewAPicture
Milestone: 4.9 Priority: normal
Severity: normal Version: 2.5
Component: Shortcodes Keywords: has-patch
Focuses: docs Cc:
PR Number:

Description

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

Attachments (1)

37222.patch (828 bytes) - added by grapplerulrich 3 years ago.
Small improvement by updating the code example

Download all attachments as: .zip

Change History (11)

@grapplerulrich
3 years ago

Small improvement by updating the code example

#1 @grapplerulrich
3 years ago

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

#2 @DrewAPicture
3 years ago

  • Keywords has-patch added
  • Version changed from trunk to 2.5

This ticket was mentioned in Slack in #docs by morganestes. View the logs.


3 years ago

#4 @morganestes
3 years ago

  • Keywords needs-docs added

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.

#5 @DrewAPicture
2 years ago

  • Keywords needs-docs removed
  • Milestone changed from Awaiting Review to 4.9

#6 @DrewAPicture
2 years ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

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.

#7 @DrewAPicture
2 years ago

In 41282:

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

See #37222. See #41017.

#8 @DrewAPicture
2 years ago

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.

#9 @grapplerulrich
2 years ago

@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

#10 @DrewAPicture
2 years ago

In 41286:

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

Props grapplerulrich.
See #37222.

Note: See TracTickets for help on using tickets.