[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       |   Keywords:
  Focuses:  docs         |
-------------------------+-----------------------------
 Our [http://make.wordpress.org/core/handbook/inline-documentation-
 standards/php-documentation-standards/#1-functions-and-class-methods
 documentation standards] say that:

 > "@access: Only use for functions if private. If the function or class
 method is private, it is intended for internal use only, and there will be
 no documentation for it in the code reference."

 AFAIK, `@access` was introduced via phpDocumentor into the defacto phpDoc
 standards during PHP 4. The `public`, `protected` and `private` visbility
 keywords were not introduced for class methods and properties until PHP5,
 but since then, `@access` has been redundant for use in classes.

 There are 979 instances of `@access`. 464 of them are marked as public,
 119 and protected and 396 are private, meaning that nearly 60% of them
 shouldn't be there according to the standards. Many of them are also wrong
 anyway and contradict the code. e.g.

 {{{
 class FooBar {
         /**
          * @access protected
          */
         var $my_property;

         /**
          * @access private
          */
         function _my_func() {}
 }
 }}}

 The `@access` tag is NOT part of the upcoming PSR-5 document, which means
 that documentation generators may not support it.

 ----

 Since the only non-redundant usage for `@access` is on functions, and the
 only valid value according to the documentation standards is `@access
 private`, I propose that this is swapped out for the more descriptively
 accurate `@internal`.

 `@internal` IS part of [https://github.com/php-fig/fig-
 standards/pull/169/files#diff-9a10a11696dc38209c125ea9c57a565fR950 PSR-5].
 It can be used in two ways:

 1. As a normal tag "indicating that the associated structural element is
 used purely for the internal workings of this piece of software". WP-
 Parser [https://github.com/rmccue/WP-
 Parser/commit/013d45757b030c3bf13ed2378f69a3ddc4ceb8d1 already excludes]
 importing functions and methods marked with `@internal` unless explicitly
 requested.

 2. As an inline tag to "add internal comments or additional description
 text inline to the Long Description". This should take the form of
 `{@internal Some comment.}}`.

 WP currently has 124 instances of `@internal`. Of those, the majority are
 for missing short and long descriptions (inline tag). Of the remainder,
 some are normal tags which should be inline tags, and only a few are
 actually used for what are intended to be private functions. Those
 elements which use the normal tag incorrectly, will not be appearing in
 WP-Parser results.

 ----

 To summarise:
  - `@access` is being used more incorrectly than correctly according to
 our documentation standards.
  - `@access` is inconsistent with the code it is describing.
  - `@access` is not in PSR-5, and is generally redundant.
  - `@internal` is in PSR-5, is more flexible and more descriptive.
  - `@internal` is not used correctly, causing incorrect WP-Parser results
 and therefore missing entries on DevHub code reference.

 A plan:
  - Convert normal `@internal` tags to inline `{@internal ...}}` tags where
 appropriate.
  - Remove `@access public` and `@access protected` from everywhere.
  - Convert `@access private` to `@internal` for functions where correct.
  - Remove remaining `@access private` instances.

 Thoughts?

 Related #22234 (and vaguely #16682).

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