WordPress.org

Make WordPress Core

Opened 16 months ago

Closed 14 months ago

Last modified 12 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:

Description

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 16 months ago.
25661.2.diff (10.5 KB) - added by DrewAPicture 14 months ago.
Second pass + standards tweaks

Download all attachments as: .zip

Change History (14)

@johnbillion16 months ago

comment:1 @johnbillion16 months ago

  • Keywords has-patch added

Patch.

comment:2 @johnbillion16 months 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: @SergeyBiryukov16 months ago

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

comment:4 in reply to: ↑ 3 @DrewAPicture16 months 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 @DrewAPicture16 months ago

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

comment:6 @scottsweb16 months ago

  • Cc scottsweb added

comment:7 @jdgrimes16 months ago

  • Cc jdg@… added

comment:8 @kpdesign16 months ago

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

@DrewAPicture14 months ago

Second pass + standards tweaks

comment:9 @DrewAPicture14 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 @johnbillion14 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 @ircbot13 months ago

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

comment:12 @DrewAPicture12 months ago

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