Add sniff to check for first line descriptions

[andrewnicols]

Replaces:

• phpdocsfistline
• functiondescription

Replaces https://github.com/moodlehq/moodle-local_moodlecheck/pull/142

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

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

Additional details and impacted files

```diff @@ 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 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: 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.