Description
Description
As a developer I develop some code and running magento coding standard static tests against my code. But it's not clear what to do in case of some issue.
Example:
PHP Code Sniffer detected 2 violation(s):
FILE: .../app/code/Magento/Checkout/Model/TotalsInformationManagement.php
----------------------------------------------------------------------
FOUND 4 ERRORS AFFECTING 4 LINES
----------------------------------------------------------------------
41 | ERROR | [x] If the @inheritdoc not inline it shouldn’t have
| | braces
43 | ERROR | [x] {@inheritdoc} does not import parameter annotation
65 | ERROR | [x] Missing short description
66 | ERROR | [x] There must be exactly one blank line before tags
----------------------------------------------------------------------
PHPCBF CAN FIX THE 4 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------
Failed asserting that 2 matches expected 0.
Let's imaging I'm just first time created some PR to magento2 and got these issues, I don't really know what to do with following things:
- If the @inheritdoc not inline it shouldn’t have braces
- {@inheritdoc} does not import parameter annotation
- Missing short description
I didn't even knew how to run these static tests, as they were ran on some Magento infra and shown me just result (commands that I could run is not shown anywhere) --> I don't know how to run this phpcbf.
So I'm trying to google these things, but just googling of these reports isn't getting any valid result:
https://www.google.com/search?q=If+the+%40inheritdoc+not+inline+it+shouldn%27t+have+braces+magento2
https://www.google.com/search?q=%7B%40inheritdoc%7D+does+not+import+parameter+annotation+magento2
https://www.google.com/search?q=Missing+short+description+magento2
Only one "There must be exactly one blank line before tags" is quite clear.
This is just example of things that quite obvious.
Let's imaging that should I do in case if i'll get following message: The use of function pathinfo() is discouraged and I didn't even touched the place that was using this function (related to #102).
It will be absolutely not clear.
Proposal
- Document all existing rules and what messages are they reporting.
- Add info WHY it was created, what should be used instead, exceptions (example Technical guidelines > Abstract classes MUST NOT be marked as public @api magento2#25133 (comment)) and how to ignore this rule (in case if you didn't touched that place and don't want to brake anything)