Skip to content

Commit 22cc57c

Browse files
gsherwoodjrfnl
gsherwood
authored and
jrfnl
committed
Updated Customisable Sniff Properties (markdown)
1 parent 37ebacd commit 22cc57c

File tree

1 file changed

+57
-29
lines changed

1 file changed

+57
-29
lines changed

‎wiki/Customisable-Sniff-Properties.md

Lines changed: 57 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -199,9 +199,9 @@ This sniff ensures that files use a specific line ending, which can be customise
199199

200200
Property Name | Type | Default | Available Since
201201
----------------- | ---- | ------- | ---------------
202-
lineLimit | int | 80 | -
203202
absoluteLineLimit | int | 100 | -
204203
ignoreComments | bool | false | 3.1.0
204+
lineLimit | int | 80 | -
205205

206206
This sniff checks all lines in a file and generates warnings if they are over `lineLimit` characters in length and errors if they are over `absoluteLineLimit` in length. These properties can be used to set the threshold at which errors are reported.
207207

@@ -298,8 +298,8 @@ If the `error` property is set to `true`, an error will be thrown for violations
298298

299299
Property Name | Type | Default | Available Since
300300
-------------- | ---- | ------- | ---------------
301-
spacing | int | 1 | 3.4.0
302301
ignoreNewlines | bool | false | 3.4.0
302+
spacing | int | 1 | 3.4.0
303303

304304
This sniff checks the spacing after a type cast. By default, the sniff ensures there is one space after the cast, as shown in the following code snippet:
305305

@@ -337,8 +337,8 @@ Sometimes complex statements are broken over multiple lines for readability. By
337337

338338
Property Name | Type | Default | Available Since
339339
-------------- | ---- | ------- | ---------------
340-
spacing | int | 1 | 3.4.0
341340
ignoreNewlines | bool | false | 3.4.0
341+
spacing | int | 1 | 3.4.0
342342

343343
This sniff checks the spacing after a `!` operator. By default, the sniff ensures there is one space after the operator, as shown in the following code snippet:
344344

@@ -386,8 +386,8 @@ By default, this sniff will generate an error if the `!` operator is followed by
386386

387387
Property Name | Type | Default | Available Since
388388
-------------- | ---- | ------- | ---------------
389-
checkFunctions | bool | true | 2.3.0
390389
checkClosures | bool | false | 2.3.0
390+
checkFunctions | bool | true | 2.3.0
391391

392392
The sniff checks the position of the opening brace of a function and/or closure (anonymous function). The sniff only checks functions by default, but the `checkFunctions` and `checkClosures` properties can be used to have the sniff check one or both of these code blocks.
393393

@@ -405,8 +405,8 @@ The sniff checks the position of the opening brace of a function and/or closure
405405

406406
Property Name | Type | Default | Available Since
407407
-------------- | ---- | ------- | ---------------
408-
checkFunctions | bool | true | 2.3.0
409408
checkClosures | bool | false | 2.3.0
409+
checkFunctions | bool | true | 2.3.0
410410

411411
The sniff checks the position of the opening brace of a function and/or closure (anonymous function). The sniff only checks functions by default, but the `checkFunctions` and `checkClosures` properties can be used to have the sniff check one or both of these code blocks.
412412

@@ -424,8 +424,8 @@ The sniff checks the position of the opening brace of a function and/or closure
424424

425425
Property Name | Type | Default | Available Since
426426
------------------ | ---- | ------- | ---------------
427-
complexity | int | 10 | -
428427
absoluteComplexity | int | 20 | -
428+
complexity | int | 10 | -
429429

430430
This sniff checks the cyclomatic complexity for functions by counting the different paths the function includes.
431431

@@ -448,8 +448,8 @@ There are two configurable options:
448448

449449
Property Name | Type | Default | Available Since
450450
-------------------- | ---- | ------- | ---------------
451-
nestingLevel | int | 5 | -
452451
absoluteNestingLevel | int | 10 | -
452+
nestingLevel | int | 5 | -
453453

454454
This sniff checks how many level deep that code is nested within a function.
455455

@@ -488,8 +488,8 @@ Strictly speaking, a name cannot have two capital letters next to each other in
488488

489489
Property Name | Type | Default | Available Since
490490
-------------------| ----- | ----------------------------- | ---------------
491-
forbiddenFunctions | array | [sizeof=>count,delete=>unset] | 2.0.0
492491
error | bool | true | -
492+
forbiddenFunctions | array | [sizeof=>count,delete=>unset] | 2.0.0
493493

494494
This sniff discourages the use of alias functions that are kept in PHP for compatibility with older versions. The sniff can be used to forbid the use of any function by setting the `forbiddenFunctions` property. The property is defined as an array, with the keys being the names of the functions to forbid and the values being the names of suggested alternative functions to use instead. If no alternative function exists (i.e., the function should never be used) specify `null` as the value.
495495

@@ -561,8 +561,8 @@ If the `error` property is set to `false`, a warning will be thrown for violatio
561561

562562
Property Name | Type | Default | Available Since
563563
-------------- | ---- | ------- | ---------------
564-
spacing | int | 0 | 3.3.0
565564
ignoreNewlines | bool | false | 3.3.0
565+
spacing | int | 0 | 3.3.0
566566

567567
This sniff checks the padding inside parenthesis that are not being used by function declarations, function calls, or control structures. By default, the sniff ensures there are zero spaces inside the parenthesis, as shown in the following code snippet:
568568

@@ -600,10 +600,10 @@ Sometimes long statements are broken over multiple lines to work within a maximu
600600

601601
Property Name | Type | Default | Available Since
602602
----------------------- | ----- | ------- | ---------------
603-
indent | int | 4 | -
604603
exact | bool | false | -
605-
tabIndent | bool | false | 2.0.0
606604
ignoreIndentationTokens | array | [] | 1.4.8
605+
indent | int | 4 | -
606+
tabIndent | bool | false | 2.0.0
607607

608608
This sniff checks that code blocks are indented correctly. By default, this sniff ensures that code blocks are indented 4 spaces, but you can change the size of the indent by setting the `indent` property.
609609

@@ -660,8 +660,8 @@ Setting the `ignoreIndentationTokens` property provides the sniff with a list of
660660

661661
Property Name | Type | Default | Available Since
662662
-------------- | ---- | ------- | ---------------
663-
spacing | int | 0 | 3.5.0
664663
ignoreNewlines | bool | false | 3.5.0
664+
spacing | int | 0 | 3.5.0
665665

666666
This sniff checks the spacing after a `...` operator. By default, the sniff ensures there is no space after the operator, but you can enforce a fixed number of spaces by setting the `spacing` property.
667667

@@ -690,9 +690,10 @@ If you want to allow a newline after the operator, you can set the `ignoreNewlin
690690

691691
### PEAR.Commenting.FunctionComment
692692

693-
Property Name | Type | Default | Available Since
694-
----------------- | ------ | ------- | --------------
695-
minimumVisibility | string | private | 3.6.0
693+
Property Name | Type | Default | Available Since
694+
----------------- | ------ | ------------------------ | --------------
695+
minimumVisibility | string | private | 3.6.0
696+
specialMethods | array | [__construct,__destruct] | 3.6.0
696697

697698
This sniff verifies that functions are documented using a docblock. By default, all functions are checked regardless of their visibility, but the sniff can be told to ignore private and protected functions using the `minimumVisibility` property. When set to `protected`, only public and protected functions will be checked. When set to `public`, only public functions will be checked.
698699

@@ -704,7 +705,19 @@ This sniff verifies that functions are documented using a docblock. By default,
704705
</rule>
705706
```
706707

707-
## PEAR Sniffs
708+
This sniff also enforces that function docblocks contain a `@return` tag, except for special methods. By default, the `__construct` and `__destruct` methods do not need to specify a return type, but the sniff can be told to not require a return type for other methods by setting the `specialMethods` sniff property.
709+
710+
```xml
711+
<rule ref="PEAR.Commenting.FunctionComment">
712+
<properties>
713+
<property name="specialMethods" type="array">
714+
<element value="__construct"/>
715+
<element value="__destruct"/>
716+
<element value="ignoreThisFunction"/>
717+
</property>
718+
</properties>
719+
</rule>
720+
```
708721

709722
### PEAR.ControlStructures.ControlSignature
710723

@@ -760,8 +773,8 @@ One of the rules that this sniff enforces is the indent of an assignment that ha
760773

761774
Property Name | Type | Default | Available Since
762775
------------------------- | ---- | ------- | ---------------
763-
indent | int | 4 | 1.3.4
764776
allowMultipleArguments | bool | true | 1.3.6
777+
indent | int | 4 | 1.3.4
765778
requiredSpacesAfterOpen | int | 0 | 1.5.2
766779
requiredSpacesBeforeClose | int | 0 | 1.5.2
767780

@@ -905,10 +918,10 @@ One of the rules that this sniff enforces is the indent of the case terminating
905918

906919
Property Name | Type | Default | Available Since
907920
----------------------- | ----- | ------- | ---------------
908-
indent | int | 4 | -
909921
exact | bool | false | -
910-
tabIndent | bool | false | 2.0.0
911922
ignoreIndentationTokens | array | [] | 1.4.8
923+
indent | int | 4 | -
924+
tabIndent | bool | false | 2.0.0
912925

913926
> Note: All properties are inherited from the [Generic.WhiteSpace.ScopeIndent](#genericwhitespacescopeindent) sniff.
914927
@@ -1005,8 +1018,8 @@ One of the rules that this sniff enforces is the indent of the case terminating
10051018

10061019
Property Name | Type | Default | Available Since
10071020
------------------------- | ---- | ------- | ---------------
1008-
indent | int | 4 | 1.3.4
10091021
allowMultipleArguments | bool | false | 1.4.7
1022+
indent | int | 4 | 1.3.4
10101023
requiredSpacesAfterOpen | int | 0 | 1.5.2
10111024
requiredSpacesBeforeClose | int | 0 | 1.5.2
10121025

@@ -1122,12 +1135,13 @@ One of the rules that this sniff enforces is the indent of a list of implemented
11221135

11231136
### Squiz.Commenting.FunctionComment
11241137

1125-
Property Name | Type | Default | Available Since
1126-
----------------- | ------ | ------- | --------------
1127-
skipIfInheritdoc | bool | false | 3.6.0
1128-
minimumVisibility | string | private | 3.6.0
1138+
Property Name | Type | Default | Available Since
1139+
----------------- | ------ | ------------------------ | --------------
1140+
minimumVisibility | string | private | 3.6.0
1141+
skipIfInheritdoc | bool | false | 3.6.0
1142+
specialMethods | array | [__construct,__destruct] | 3.6.0
11291143

1130-
> Note: The `minimumVisibility` property is inherited from the [PEAR.Commenting.FunctionComment](#pearcommentingfunctioncomment) sniff.
1144+
> Note: The `minimumVisibility` and `specialMethods` properties are inherited from the [PEAR.Commenting.FunctionComment](#pearcommentingfunctioncomment) sniff.
11311145
11321146
This sniff verifies that functions are documented using a docblock. By default, all functions are checked regardless of their visibility, but the sniff can be told to ignore private and protected functions using the `minimumVisibility` property. When set to `protected`, only public and protected functions will be checked. When set to `public`, only public functions will be checked.
11331147

@@ -1139,6 +1153,20 @@ This sniff verifies that functions are documented using a docblock. By default,
11391153
</rule>
11401154
```
11411155

1156+
This sniff also enforces that function docblocks contain a `@return` tag, except for special methods. By default, the `__construct` and `__destruct` methods do not need to specify a return type, but the sniff can be told to not require a return type for other methods by setting the `specialMethods` sniff property.
1157+
1158+
```xml
1159+
<rule ref="Squiz.Commenting.FunctionComment">
1160+
<properties>
1161+
<property name="specialMethods" type="array">
1162+
<element value="__construct"/>
1163+
<element value="__destruct"/>
1164+
<element value="ignoreThisFunction"/>
1165+
</property>
1166+
</properties>
1167+
</rule>
1168+
```
1169+
11421170
If you make use of the `@inheritdoc` tag to inherit the parent function's entire docblock, the sniff will continue to report errors about missing tags unless you set the `skipIfInheritdoc` property to `true`.
11431171

11441172
```xml
@@ -1162,8 +1190,8 @@ public function foo($a, $b) {}
11621190

11631191
Property Name | Type | Default | Available Since
11641192
------------- | ------ | -------- | ---------------
1165-
lineLimit | int | 20 | 2.7.0
11661193
commentFormat | string | //end %s | 2.7.0
1194+
lineLimit | int | 20 | 2.7.0
11671195

11681196
This sniff checks that long blocks of code have a closing comment. The `lineLimit` property allows you to configure the numbers of lines that the code block must span before requiring a comment. By default, the code block must be at least 20 lines long, including the opening and closing lines, but you can change the required length by setting the `lineLimit` property.
11691197

@@ -1260,9 +1288,9 @@ If you prefer to write your code like this, you can set the `requiredSpacesAfter
12601288

12611289
Property Name | Type | Default | Available Since
12621290
------------------------- | ---- | ------- | ---------------
1291+
ignoreNewlines | bool | false | 3.5.4
12631292
requiredSpacesAfterOpen | int | 0 | 1.5.2
12641293
requiredSpacesBeforeClose | int | 0 | 1.5.2
1265-
ignoreNewlines | bool | false | 3.5.4
12661294

12671295
This sniff checks that `for` structures have the correct padding inside their bracketed statement. By default, the sniff ensures there are zero spaces following the opening bracket, and zero spaces preceding the closing bracket, as shown in the following code snippet:
12681296

@@ -1485,8 +1513,8 @@ If the `error` property is set to `true`, an error will be thrown for violations
14851513

14861514
Property Name | Type | Default | Available Since
14871515
-------------- | ---- | ------- | ---------------
1488-
spacing | int | 0 | 2.0.0
14891516
ignoreNewlines | bool | false | 2.3.1
1517+
spacing | int | 0 | 2.0.0
14901518

14911519
One of the rules this sniff enforces is the padding around concatenation operators. By default, the sniff ensures there are zero spaces before and after the concatenation operator, as shown in the following code snippet:
14921520

@@ -1525,8 +1553,8 @@ Sometimes long concatenation statements are broken over multiple lines to work w
15251553
Property Name | Type | Default | Available Since
15261554
------------------ | ---- | ------- | ---------------
15271555
spacing | int | 2 | 1.4.5
1528-
spacingBeforeFirst | int | 2 | 3.3.0
15291556
spacingAfterLast | int | 2 | 3.3.0
1557+
spacingBeforeFirst | int | 2 | 3.3.0
15301558

15311559
This sniff checks that there are two blank lines before and after functions declarations, but you can change the required padding using the `spacing`, `spacingBeforeFirst`, and `spacingAfterLast` properties.
15321560

0 commit comments

Comments
 (0)