Remove @access tags from core DocBlocks

[DrewAPicture]

Per discussion in #core-docs last week, we're finally to the point where we can remove @access notations from DocBlocks throughout core, with a few exceptions:

• Any standalone core functions marked private
• Any classes marked private (such as the List Table classes, for instance)

The ​parser that builds the ​Code Reference already references actual method visibility as derived with phpDocumentor, meaning that output will be unchanged following the removals.

In terms of anything marked private (including the aforementioned exceptions) the Code Reference theme already handles displaying a specially-designed callout box.

[DrewAPicture]

41452.diff​ covers classes in wp-includes.

[DrewAPicture]

41452.2.diff​ covers classes in wp-admin

[DrewAPicture]

wp-admin

[DrewAPicture]

wp-includes

[DrewAPicture]

The first passes appeared to miss some files. Maybe I was accidentally skipping them when I was clicking though or something.

Anyway, 41452-wp-admin.diff​ covers wp-admin, and 41452-wp-includes.diff​ covers wp-includes.

[SergeyBiryukov]

Replying to DrewAPicture:

Per discussion in #core-docs last week, we're finally to the point where we can remove @access notations from DocBlocks throughout core, with a few exceptions:

• Any standalone core functions marked private
• Any classes marked private (such as the List Table classes, for instance)

Great idea, having @access public in the DocBlocks is redundant, as it's already in the code itself.

[DrewAPicture]

In 41161:

Docs: Remove @access notations from method DocBlocks in wp-admin/* classes.

Prior to about 2013, many class methods lacked even access modifiers which made the @access notations that much more useful. Now that we've gotten to a point where the codebase is more mature from a maintenance perspective and we can finally remove these notations. Notable exceptions to this change include standalone functions notated as private as well as some classes still considered to represent "private" APIs.

See #41452.

[DrewAPicture]

In 41162:

Docs: Remove @access notations from method DocBlocks in wp-includes/* classes.

Prior to about 2013, many class methods lacked even access modifiers which made the @access notations that much more useful. Now that we've gotten to a point where the codebase is more mature from a maintenance perspective and we can finally remove these notations. Notable exceptions to this change include standalone functions notated as private as well as some classes still considered to represent "private" APIs.

See #41452.

[DrewAPicture]

Note: the ​inline documentation standards for PHP have been updated to reflect this change.

[DrewAPicture]

@jrf: Leaving a note for you here assuming you may need to make adjustments to any WPCS rules around @access tags.

@coffee2code: I grokked the parser and wporg-developer code last week and I think we're good in terms of parsing since we store the method visibility in meta and already check against it with a fallback to the access tag. The fallback can continue to handle the exceptions outlined above.

[jrf]

@DrewAPicture At this moment the WPCS Docs ruleset does not (yet) check these kind of things in that much detail.
When the ruleset is improved in the future, this will need to be taken into account by whoever does the improving.

[DrewAPicture]

Made typo in [41168] which was also against this ticket.

[DrewAPicture]

This is all done. If we come across any that were missed, let's handle them in separate tickets.

[SergeyBiryukov]

In 42748:

Docs: Remove @access notation from WP_Taxonomy::$meta_box_sanitize_cb.

See #42505, #41452.

[SergeyBiryukov]

In 42749:

Twenty Fourteen: Remove redundant @access and @static notations from classes.

Props birgire.
See #41452, #42803, #42505.