[wp-trac] [WordPress Trac] #27167: Drop @access in favour of @internal

[WordPress Trac]

#27167: Drop @access in favour of @internal
-------------------------+------------------------------
 Reporter:  GaryJ        |       Owner:
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  General      |     Version:  trunk
 Severity:  normal       |  Resolution:
 Keywords:               |     Focuses:  docs
-------------------------+------------------------------

Comment (by nacin):

 We still use the `var` keyword plus `@access private|protected` for all
 properties introduced in a class prior to WP 3.2 (when we moved to PHP
 5.2). Properties meant to be explicit get shifted to `public`, but we
 deliberately don't want to specify a property ''meant'' to be private or
 protected as `public` and we also can't use `private` or `protected`
 because that can cause major errors in existing plugins.

 Thus the examples that follow "Many of them are also wrong anyway and
 contradict the code" are actually correct.

 WP Parser can parse whatever we tell it to. For this case, we can easily
 parse @access for `var` properties and determine whether to document it as
 private or protected. Same for methods.

 I'm fine with converting `@access public` + `var` to `public`, but as
 voiced in #22234, this isn't just a find and replace. It needs to happen
 with a fine-toothed comb to make sure the documentation is actually
 correct, otherwise we back ourselves into a corner.

 We can move to @internal for private-use functions. But `@access
 private|protected` for methods ''meant'' to be private or protected is
 more explicit to me.

 We know we're not following PSR-5, we're just doing what is practical for
 a codebase riddled with private-use functions, properties, and methods
 that we can't actually lock down without breaking things.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/27167#comment:2>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform