WordPress.org

Making WordPress.org

Opened 22 months ago

Closed 21 months ago

Last modified 21 months ago

#1498 closed enhancement (fixed)

Developer code reference should include warnings for "@access private" functions

Reported by: netweb Owned by: DrewAPicture
Milestone: Priority: normal
Component: Developer Hub Keywords: has-patch has-screenshots commit
Cc:

Description

Currently the codex includes a warning on functions that are marked with @access private, the developer reference does not currently include these.

e.g. Developer Reference: https://developer.wordpress.org/reference/functions/get_post_type_labels/

Vs the codex counterpart: https://codex.wordpress.org/Function_Reference/get_post_type_labels
https://cldup.com/-OYyJx-RgH.png

Attachments (6)

1498_private_message.png (52.0 KB) - added by DrewAPicture 21 months ago.
1498.diff (6.5 KB) - added by DrewAPicture 21 months ago.
1498.2.diff (6.6 KB) - added by DrewAPicture 21 months ago.
Bail if it isn't private (whoops)
1498.3_with_callout.png (61.7 KB) - added by DrewAPicture 21 months ago.
w/ 1498.3.diff
1498.3_fallback.png (61.6 KB) - added by DrewAPicture 21 months ago.
w/ 1498.3.diff
1498.3.diff (7.2 KB) - added by DrewAPicture 21 months ago.

Download all attachments as: .zip

Change History (16)

#1 @DrewAPicture
22 months ago

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

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


21 months ago

#3 @DrewAPicture
21 months ago

  • Keywords has-patch has-screenshots added; needs-patch removed
  • Type changed from defect to enhancement

Added 1498.diff:

  • Introduces a get_private_access_message() function to retrieve the message
  • Relocates a chunk of logic from DevHub_Formatting::make_doclink_clickable() into a new DevHub_Formatting::get_internal_element_link() method. This allows us to reuse that logic for linking internal elements elsewhere
  • Adds a single new CSS class, private-access
  • Only handles displaying the message for private standalone functions and hooks. Private methods fall under a different context in terms of inheritance access.

See 1498_private_message.png for what this would look like.

@DrewAPicture
21 months ago

@DrewAPicture
21 months ago

Bail if it isn't private (whoops)

#4 @DrewAPicture
21 months ago

1498.3.diff addresses some patch feedback from @coffee2code. I also opted to leverage the 'alert' callout styles if the class is available (via the Handbook plugin):

1498.3.diff:

  • Fixes a typo in a variable name
  • Uses link_internal_element() for the new static method name (will be committed separately)
  • Uses the WPorg_Handbook_Callout_Boxes class to generate the private access message (if available)
  • Improves the fallback styles to better mimic the 'alert' callout styles

See 1498.3_with_callout.png and 1498.3_fallback.png

#5 @coffee2code
21 months ago

  • Keywords commit added

1498.3.diff looks good!

#6 @drewapicture
21 months ago

In 2430:

DevHub: Introduce DevHub_Formatting::link_internal_element(), which splits out logic from DevHub_Formatting::make_doclink_clickable() to make it reusable elsewhere.

The new link_internal_element() method serves to generate link markup for internal elements including properties, classes and methods, standalone functions, and hooks.

See #1498.

#7 @drewapicture
21 months ago

In 2431:

DevHub: Introduce a new template tag, get_private_access_message(), which generates a message for standalone functions or hooks marked with a private @access tag in their respective Docblocks.

If the Handbook plugin is available, more specifically if the WPorg_Handbook_Callout_Boxes class is available, the message markup is generated as an 'alert'-type callout box. Otherwise, fall-back markup and styles are applied to the message.

If an alternative function is referenced via an @see tag in the function or hook DocBlock, make a good-faith effort to try to link to the reference page for that element as an alternative within the access message text.

See #1498.

#8 @DrewAPicture
21 months ago

Forgot to props @netweb for the message text in [2431], so let's make sure to do it when the stylesheet is bumped to close this.

#9 @drewapicture
21 months ago

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

In 2432:

DevHub: Bump the version on main.css following [2431].

Part props netweb for furnishing message text already in use in the Codex.

Fixes #1498.

#10 @drewapicture
21 months ago

In 2437:

DevHub: Avoid strict standards errors on variables passed by reference in get_deprecated() and get_private_access_message() template tags.

See #1551. See #1498.

Note: See TracTickets for help on using tickets.