Add sniff to check for first line descriptions

[andrewnicols]

Replaces:

• phpdocsfistline
• functiondescription

Replaces moodlehq/moodle-local_moodlecheck#142

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.87%. Comparing base (5af7ee0) to head (ad8be34).

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #134      +/-   ##
============================================
+ Coverage     97.84%   97.87%   +0.03%     
- Complexity      835      844       +9     
============================================
  Files            36       37       +1     
  Lines          2463     2499      +36     
============================================
+ Hits           2410     2446      +36     
  Misses           53       53              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[stronk7]

Q: Does this cover cases like:

/**
 * This is the first line of the block.
 * But the second an following aren't separated enough and
 * make the block to look weird.
 */
<<files, classes, ..., but methods, that I think don't require it, go here >>

I mean, it sounds to me that the 1st line alone (with empty line after), has been always a requirement for them. But we haven't enforced it, I think. And this may be the perfect sniff for that.

[andrewnicols]

Q: Does this cover cases like:

/**
 * This is the first line of the block.
 * But the second an following aren't separated enough and
 * make the block to look weird.
 */
<<files, classes, ..., but methods, that I think don't require it, go here >>

I mean, it sounds to me that the 1st line alone (with empty line after), has been always a requirement for them. But we haven't enforced it, I think. And this may be the perfect sniff for that.

It doesn't cover that case right now, but it's not hard to add. Still, I'd prefer to do it as a separate PR in this case because there are a couple of ways to do it.

[stronk7]

Still, I'd prefer to do it as a separate PR in this case because there are a couple of ways to do it.

Agreed, we can create a new issue with some thoughts about what we may need to check:

• Blank line between summary (short desc) and description (and for which elements).
• Blank like between descriptions and tags.
• Maybe some ordering and spacing between tag "groups" (copyright, author, license => params => return => other tags)
• ....
  (I'd look to what the phpdoc proposal says for anything not explicitly defined in our guidelines)

I'll proceed to review this soon... ciao :-)

[stronk7]

Have created #136 to have the discussion above registered.