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

[netweb]

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

[DrewAPicture]

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]

Bail if it isn't private (whoops)

[DrewAPicture]

w/ 1498.3.diff​

[DrewAPicture]

w/ 1498.3.diff​

[DrewAPicture]

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​

[coffee2code]

1498.3.diff​ looks good!

[drewapicture]

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.

[drewapicture]

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.

[DrewAPicture]

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.

[drewapicture]

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.

[drewapicture]

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.