Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new Sniff to restrict line length in docblocks #171

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

jaymcp
Copy link
Member

@jaymcp jaymcp commented Mar 10, 2025

Description

This PR introduces the Sniff BigBite.Commenting.DocCommentLineLength. This Sniff allows one to restrict the number of characters allowed on one line in a docblock.
The default warning threshold is 80 characters; the default error threshold is 100 characters. Both are configurable.

The line length restriction will not be imposed upon WordPress plugin or theme comments, as their descriptions will generally exceed the default bounds. It will also not apply to lines whose text wholly contains unbreakable strings (such as URIs).

Indentation and * do not contribute to the line length calculations by default. This is configurable.

So, the following are acceptable by default:

/**
 * This is a short block comment.
 */

/**
 * Plugin Name: Valid
 * Description: This is a really long description of the plugin, that exceeds the line length, but does a good job of explaining the plugin's purpose.
 */

                          /**
                          * I'm indented a lot, but my content is shorter than 80 characters.
                          */

This will trigger a warning:

/**
 * This is a block comment that exceeds the warning length of 80 characters, but will not error.
 */

And this will trigger an error:

/**
 * This is a block comment that exceeds the absolute maximum (default) length of 100 characters, and will error.
 */

Usage

To disable this rule:

<rule ref="BigBite">
  <exclude name="BigBite.Commenting.DocCommentLineLength" />
</rule>

To override the default config:

<rule ref="BigBite.Commenting.DocCommentLineLength">
  <properties>
    <property name="lineLimit" value="120" />
    <property name="absoluteLineLimit" value="150" />
    <property name="includeIndentation" value="true" />
  </properties>
</rule>

Types of changes (if applicable):

  • Bug fix (non-breaking change which fixes an issue).
  • New feature (non-breaking change which adds functionality).
  • Breaking change (fix or feature that would cause existing functionality to not work as expected).

Checklist (if applicable):

  • All checks pass when running `composer run all-checks.

@jaymcp jaymcp requested a review from a team March 10, 2025 15:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant