Meanwhile, I've encountered another problem that supports the point that we need to document functions, this or another way: Phan barfs about functions using Database::selectField().[1] I've suppressed the warnings for now, but would like a more permanent solution.
----- [1] https://integration.wikimedia.org/ci/job/mwext-php70-phan-jessie/2199/consol...
On Fri, May 19, 2017 at 3:12 AM, Jeroen De Dauw jeroendedauw@gmail.com wrote:
Hey,
Personally I'm not using this in my projects and would object to those tags being added as they are IMO clutter. Those projects have some relevant differences with MediaWiki that all contribute to those tags being more clutter than helpful:
- Good OO: small classes and interfaces, favoring of composition over
inheritance and thus very rarely inheriting concrete code
- Simple well named methods with no or few parameters: documentation
explaining something beyond type is seldomly needed
- Usage of scalar type hints, nullable type hints and return type hints via
usage of PHP 7.1
And of course following any of those points has benefits way beyond not needing inheritdoc tags as crutch.
Cheers
-- Jeroen De Dauw | https://entropywins.wtf | https://keybase.io/jeroendedauw Software craftsmanship advocate ~=[,,_,,]:3 _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l