It would be nice to have a sniff that detects a missing newline before an @throws tag in a function docblock.

CommentFileSizeAuthor
#6 interdiff.txt3.68 KBpfrenssen
#6 2382349-6-coder-newline_between_tags.patch4.45 KBpfrenssen
#4 2382349-4-coder-newline_between_tags.patch4.43 KBpfrenssen
#1 2382349-1-coder-newline_before_throws.patch1.26 KBpfrenssen

Comments

pfrenssen’s picture

pfrenssen
Location Sofia
commented
Status: Active » Needs review
StatusFileSize
new 2382349-1-coder-newline_before_throws.patch1.26 KB

Here's a patch for 7.x-2.x.

klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented
Version: 7.x-2.x-dev » 8.x-2.x-dev
Status: Needs review » Needs work

Should be fixed in 8.x-2.x first, if it is a problem there. Can you check? And this should come with a test case, see the examples in coder_sniffer/Test.

pfrenssen’s picture

pfrenssen
Location Sofia
commented
Title: Add sniff that detects missing newline before @throws tag » Add sniff that detects missing newline before a different @tag

I just looked up the exact specification in the coding standards, and it is a general rule to have a newline inbetween all different tags, this is not exclusive to @param, @return and @throws:

From Drupal API documentation standards for order of documentation sections:

Separate different-type sections by a blank line (for instance, all the @param documentation goes together, with a blank line before the first parameter and a blank line after the last parameter before the @return section starts).

So we can actually add a generic sniff, and remove the specific sniffs that are currently used for @param and @return.

pfrenssen’s picture

pfrenssen
Location Sofia
commented
Status: Needs work » Needs review
StatusFileSize
new 2382349-4-coder-newline_between_tags.patch4.43 KB

Added sniff + test to check for newlines between @tag sections for the 8.x-2.x branch.

klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented
Status: Needs review » Needs work

Looks almost ready!

  1. +++ b/coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php
@@ -217,12 +220,13 @@ class Drupal_Sniffs_Commenting_DocCommentSniff implements PHP_CodeSniffer_Sniff
+                if ($isNewGroup = $tokens[$prev]['line'] !== ($tokens[$tag]['line'] - 1)) {

    Please move the assignment out of the if() to make it more obvious what is going on. 

  2. +++ b/coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php
--- a/coder_sniffer/Drupal/Test/bad/BadUnitTest.php
+++ b/coder_sniffer/Drupal/Test/bad/BadUnitTest.php

    BadUnitTest is for legacy only, please move this to DocCommentSniffUnitTest.

pfrenssen’s picture

pfrenssen
Location Sofia
commented
Status: Needs work » Needs review
StatusFileSize
new 2382349-6-coder-newline_between_tags.patch4.45 KB
new interdiff.txt3.68 KB

Thanks! Some good points, addressed them in this new patch.

klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented
Status: Needs review » Fixed

Committed, thanks!

  • klausi committed ad88678 on 8.x-2.x authored by pfrenssen 
    Issue #2382349 by pfrenssen: Add sniff that detects missing newline...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.