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
.