Make WordPress Core

Opened 2 years ago

Closed 21 months ago

Last modified 20 months ago

#25661 closed defect (bug) (fixed)

Inline Docs: Document shortcode attribute arrays

Reported by: johnbillion Owned by: DrewAPicture
Milestone: 3.9 Priority: normal
Severity: normal Version:
Component: Shortcodes Keywords: has-patch
Focuses: docs Cc:


The various shortcodes in core accept numerous attributes, but these aren't documented in the inline docs for the callback functions. Upcoming patch fixes that.

Attachments (2)

25661.diff (10.6 KB) - added by johnbillion 2 years ago.
25661.2.diff (10.5 KB) - added by DrewAPicture 21 months ago.
Second pass + standards tweaks

Download all attachments as: .zip

Change History (14)

@johnbillion2 years ago

comment:1 @johnbillion2 years ago

  • Keywords has-patch added


comment:2 @johnbillion2 years ago

For those interested, my colleague Scott has written a plugin which adds autosuggest functionality for shortcodes. We're hoping to add support for the shortcode attributes too by reading the docblock, hence this patch.

comment:3 follow-up: @SergeyBiryukov2 years ago

$output = '' and $html = '' should probably be moved above the docblocks.

comment:4 in reply to: ↑ 3 @DrewAPicture2 years ago

Replying to SergeyBiryukov:

$output = '' and $html = '' should probably be moved above the docblocks.

Actually, a couple of weeks ago we opted to take the approach of leaving the original value in the hook call and referencing a nonexistent variable in the phpdoc. So rather than creating a one-time variable, we'd just continue to pass '' and reference $html in the doc block.

comment:5 @DrewAPicture2 years ago

  • Summary changed from Inline Docs: Array notation documentation for shortcode attributes to Inline Docs: Document shortcode attribute arrays

comment:6 @scottsweb2 years ago

  • Cc scottsweb added

comment:7 @jdgrimes2 years ago

  • Cc jdg@… added

comment:8 @kpdesign23 months ago

  • Owner set to DrewAPicture
  • Status changed from new to reviewing

@DrewAPicture21 months ago

Second pass + standards tweaks

comment:9 @DrewAPicture21 months ago

  • Milestone changed from Awaiting Review to 3.9

I'd like to get this in for 3.9 – I think it would certainly set a good example for documenting shortcodes going forward.25661.2.diff brings a few descriptions and tags up to standard, and tweaks a few other things.

comment:10 @johnbillion21 months ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 26915:

Inline documentation for core shortcode attributes.

Props DrewAPicture, johnbillion.
Fixes #25661.

comment:11 @ircbot21 months ago

This ticket was mentioned in IRC in #wordpress-dev by johnbillion. View the logs.

comment:12 @DrewAPicture20 months ago

  • Component changed from Inline Docs to Shortcodes
  • Focuses docs added
Note: See TracTickets for help on using tickets.