The LineLengthSniff sniff appears to allow @link to be > 80 chars, which is permissible in the coding standard. When the @link is in a list, the sniff creates a warning.

FILE: .../core/core.api.php
----------------------------------------------------------------------
FOUND 0 ERRORS AND 3 WARNINGS AFFECTING 3 LINES
----------------------------------------------------------------------
68 | WARNING | Line exceeds 80 characters; contains 93 characters
...

end

* - @link https://www.drupal.org/project/examples Examples project (sample modules) @endlink

CommentFileSizeAuthor
#4 2791183-4.patch2.22 KBdawehner

Comments

Everett Zufelt created an issue. See original summary.

pfrenssen’s picture

pfrenssen
Location Sofia
commented
Status: Active » Postponed (maintainer needs more info)

Can you check if it works if you have it on a separate line?

These keywords that are preceded with an @ are PHPDoc tags. They are used to generate the API documentation. If they are used inline in a list they are ignored. They need to start on a new line, as per the PHPDoc documentation (emphasis mine):

Each tag is preceded by an at-sign (@) and starts on a new line.

pfrenssen’s picture

pfrenssen
Location Sofia
commented
Status: Postponed (maintainer needs more info) » Active

Ah no I am mistaken, our own coding standards allow this to be inline, here is the relevant section from the API documentation and comment standards:

@link is followed by a space; followed by the name of a function, name of a class, file name, group identifier, or URL; followed by a space; followed by the link text; followed by @endlink. The entire @link ... @endlink must be on the same line, and must be preceded and followed by whitespace or newlines. It is not necessary to use @link ... @endlink to make a link to a function, class, or file if the link text would be the same as the function name, class name, or file name (those will turn into links in text without using @link ... @endlink.

Drupal standards: The @link ... @endlink line is allowed to exceed 80 characters. If it will fit on the preceding or following line along with additional text in the same paragraph that precedes or follows it without exceeding 80 characters, it can be placed on a line with other text. However, if putting it with other text would make the line exceed 80 characters, place it on its own line.

dawehner’s picture

dawehner
Primary language German
commented
Status: Active » Needs work
StatusFileSize
new 2791183-4.patch2.22 KB

Tried to start writing a test for that + a fix. This isn't done yet.

klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented

Instead of patches we now use pull requests against https://github.com/klausi/coder , please file one there and link it here.

Everett Zufelt’s picture

Everett Zufelt commented

@dawehner ,, perhaps the test at LineLengthUnitTest.inc should include a nested list as well? I believe your code will also cover this case.

dawehner’s picture

dawehner
Primary language German
commented

@dawehner ,, perhaps the test at LineLengthUnitTest.inc should include a nested list as well? I believe your code will also cover this case.

Good idea. I'm actually wondering whether we should change the behaviour to simply check whether the @ is the first character before any alphanumeric one. This could cover a good bunch of usecases. Ideas?

Everett Zufelt’s picture

Everett Zufelt commented

Good idea. I'm actually wondering whether we should change the behaviour to simply check whether the @ is the first character before any alphanumeric one. This could cover a good bunch of usecases. Ideas?

I'm typically more in favor of testing for specific cases than for blanket cases. That being said, I'm brand new to the Coder issue queue, and don't know what is the norm.

Here are some scenarios that your suggestion would pass as valid:

 * !!! @link https://www.drupal.org/project/examples Examples project (sample modules) @endlink
 * ??? @link https://www.drupal.org/project/examples Examples project (sample modules) @endlink
 * <@link https://www.drupal.org/project/examples Examples project (sample modules) @endlink

  • klausi committed 268e0a1 on 8.x-2.x 
    fix(LineLengthSniff): Allow @link lines to exceed characters if in a...
klausi’s picture

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

Committed a fix, thanks for reporting!

Status: Fixed » Closed (fixed)

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