Change Details

**Problem** It can be difficult to understand what [[ https://docs.phpdoc.org/glossary.html#term-structural-elements | structural elements ]] are public, and changes would therefor break backwards compatibility, and which structural elements are private, and changing is safe. As an extension developer, it can be unclear what structural elements are safe to use and which ones are not. **Solution** Enforce usage of phpdoc's [[ https://docs.phpdoc.org/references/phpdoc/tags/api.html | @api ]] and [[ https://docs.phpdoc.org/references/phpdoc/tags/internal.html | @internal ]] tags. Every structural element should have one tag or the other (or it could be inherited from the parent, for instance if I add `@api` to a class declaration, it should be assumed that all of the methods are also `@api` unless overridden with `@internal`). This should be enforce with a phpcs sniff.

In T209394#6871970, @Krinkle wrote: Now that we have a [Stable interface policy](https://www.mediawiki.org/wiki/Stable_interface_policy) this becomes even more important so that we don't need to waste time on looking up if a method used in a patch is in fact supported for use. See the policy for details, but an initial version could be just to warn if a method or class tagged `@internal` is called or constructed. We could file additional tasks for less common and/or more complex use cases (such as overriding a method that isn't abstract or explicitly `@stable to override`, etc.). ------ >>! Original task description by @dbarratt > **Problem** > It can be difficult to understand what [[ https://docs.phpdoc.org/glossary.html#term-structural-elements | structural elements ]] are public, and changes would therefor break backwards compatibility, and which structural elements are private, and changing is safe. > > As an extension developer, it can be unclear what structural elements are safe to use and which ones are not. > > **Solution** > Enforce usage of phpdoc's [[ https://docs.phpdoc.org/references/phpdoc/tags/api.html | @api ]] and [[ https://docs.phpdoc.org/references/phpdoc/tags/internal.html | @internal ]] tags. Every structural element should have one tag or the other (or it could be inherited from the parent, for instance if I add `@api` to a class declaration, it should be assumed that all of the methods are also `@api` unless overridden with `@internal`). > > This should be enforce with a phpcs sniff.

**Problem** It can be difficult to understand what [[ https://docs.phpdoc.org/glossary.html#term-structural-elements | structural elements ]] are publicIn T209394#6871970, and changes would therefor break backwards compatibility, and which structural elements are private, and changing is saf@Krinkle wrote: Now that we have a [Stable interface policy](https://www.mediawiki.org/wiki/Stable_interface_policy) this becomes even more important so that we don't need to waste time on looking up if a method used in a patch is in fact supported for use. As an extension developerSee the policy for details, but an initial version could be just to warn if a method or class tagged `@internal` is called or constructed. We could file additional tasks for less common and/or more complex use cases (such as overriding a method that isn't abstract or explicitly `@stable to override`, it can be unclear what structural elements are safe to use and which ones are not.etc.). ------ **Solution**>>! Original task description by @dbarratt > **Problem** > It can be difficult to understand what [[ https://docs.phpdoc.org/glossary.html#term-structural-elements | structural elements ]] are public, and changes would therefor break backwards compatibility, and which structural elements are private, and changing is safe. > > As an extension developer, it can be unclear what structural elements are safe to use and which ones are not. > > **Solution** > Enforce usage of phpdoc's [[ https://docs.phpdoc.org/references/phpdoc/tags/api.html | @api ]] and [[ https://docs.phpdoc.org/references/phpdoc/tags/internal.html | @internal ]] tags. Every structural element should have one tag or the other (or it could be inherited from the parent, for instance if I add `@api` to a class declaration, it should be assumed that all of the methods are also `@api` unless overridden with `@internal`). Enforce usage of phpdoc's [[ https://docs.phpdoc.org/references/phpdoc/tags/api.html | @api ]] and [[ https://docs.phpdoc.org/references/phpdoc/tags/internal.html | @internal ]] tags. Every structural element should have one tag or the other (or it could be inherited from the parent, for instance if I add `@api` to a class declaration, it should be assumed that all of the methods are also `@api` unless overridden with `@internal`)> > This should be enforce with a phpcs sniff. This should be enforce with a phpcs sniff.