Jump to content

Topic on Talk:Requests for comment/Deprecation policy

Seb35 (talkcontribs)

It’s great to encourage the use of @internal tags. Some related suggestions:

  • Add a link to either PHPDoc where there is a definition of @internal and/or to the perhaps-future standard PSR-5
  • Is @unstable defined somewhere? It’s not in PHPDoc nor PSR-5; if it’s not properly defined, perhaps remove it and only suggest @internal
  • On the contrary side, I propose to also encourage the use of @api (PHPDoc, PSR-5). The visibility from PHP (public/protected/private) is not always practical, e.g. public is easier for testing purposes, so explicit documentation could be better than implicit. It would clearly say to extension developers they are encouraged to use some function, and in the longer term it will allow the creation of tools to collect statistics about the number of methods with the various visibilities (and non-documented visibility).

For the last point, an example would be ExtensionRegistry.php :) where, I guess, getQueue() and clearQueue() would be @internal and load() would be @api.

Reply to "Explicit visibility"