Document all existing rules

[ihor-sviziev]

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)