- Issue created by @Charlie ChX Negyesi
I believe we can consider the current "everything must be documented" an utter failure which needs to be thrown away and the requirements completely rethought. It won't be objective, that was tried and failed. Time to do something better.
In specifics, FieldTypeCategoryInterface for example has a single line documentation which just reshuffles the words already in the name of the interface: "Provides an object that returns the category info about the field type" which tell us absolutely nothing meanwhile FieldTypeCategoryInterface::getWeight has six lines of documentation which tells us in very great detail how this method returns the weight of whatever this object represents. The correct balance would be about six lines on FieldTypeCategoryInterface and zero on getWeight. For the six lines, invoke Kipling's six: What and Why and When And How and Where and Who. OK maybe skip the who but the rest are valid questions to expect answers to.
Of course, FieldTypeCategoryInterface is not at all alone in this. RouteProviderInterface "Defines the route provider interface." Or look at MenuLinkInterface "Defines an interface for classes providing a type of menu link." MenuLinkInterface::getWeight? six lines. ::getTitle? Six lines but the summary is useful. ::getDescription? this six lines is worse than useless, this is a bug because getTitle says it returns a localized title but description is mum on localization. Which shows clearly when you need documentation: when it's needful. And no, neither getTitle nor getDescription needs the same information twice, once in summary once in return.
Throw away the current rules and write new ones where the documentation is focused on helping developers instead of passing phpcs.
Everything.
Nothing.
Hopefully a great many things get explained even if not introduced.
Active
11.0 🔥
documentation
