Skip to content

Commit 3107205

Browse files
jrfnljrfnl
committed
Documentation: improve information about report data format
This commit adds detailed information about the array format `Report` classes receive in the `generateFileReport()` method to the `Report` interface and to the `Reporter::prepareFileReport()` method which prepares the data. It also makes the parameter specification in the individual reports a little more specific and references the `Report` interface for further details.
1 parent df258d4 commit 3107205

18 files changed

+130
-69
lines changed

‎src/Reporter.php

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -329,7 +329,29 @@ public function cacheFileReport(File $phpcsFile)
329329
*
330330
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file that has been processed.
331331
*
332-
* @return array
332+
* @return array<string, string|int|array> Prepared report data.
333+
* The format of prepared data is as follows:
334+
* ```
335+
* array(
336+
* 'filename' => string The name of the current file.
337+
* 'errors' => int The number of errors seen in the current file.
338+
* 'warnings' => int The number of warnings seen in the current file.
339+
* 'fixable' => int The number of fixable issues seen in the current file.
340+
* 'messages' => array(
341+
* int <Line number> => array(
342+
* int <Column number> => array(
343+
* int <Message index> => array(
344+
* 'message' => string The error/warning message.
345+
* 'source' => string The full error code for the message.
346+
* 'severity' => int The severity of the message.
347+
* 'fixable' => bool Whether this error/warning is auto-fixable.
348+
* 'type' => string The type of message. Either 'ERROR' or 'WARNING'.
349+
* )
350+
* )
351+
* )
352+
* )
353+
* )
354+
* ```
333355
*/
334356
public function prepareFileReport(File $phpcsFile)
335357
{

‎src/Reports/Cbf.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,11 @@ class Cbf implements Report
2828
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2929
* its data should be counted in the grand totals.
3030
*
31-
* @param array $report Prepared report data.
32-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
33-
* @param bool $showSources Show sources?
34-
* @param int $width Maximum allowed line width.
31+
* @param array<string, string|int|array> $report Prepared report data.
32+
* See the {@see Report} interface for a detailed specification.
33+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
34+
* @param bool $showSources Show sources?
35+
* @param int $width Maximum allowed line width.
3536
*
3637
* @return bool
3738
* @throws \PHP_CodeSniffer\Exceptions\DeepExitException

‎src/Reports/Checkstyle.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,11 @@ class Checkstyle implements Report
2424
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2525
* its data should be counted in the grand totals.
2626
*
27-
* @param array $report Prepared report data.
28-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
29-
* @param bool $showSources Show sources?
30-
* @param int $width Maximum allowed line width.
27+
* @param array<string, string|int|array> $report Prepared report data.
28+
* See the {@see Report} interface for a detailed specification.
29+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
30+
* @param bool $showSources Show sources?
31+
* @param int $width Maximum allowed line width.
3132
*
3233
* @return bool
3334
*/

‎src/Reports/Code.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,11 @@ class Code implements Report
2525
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2626
* its data should be counted in the grand totals.
2727
*
28-
* @param array $report Prepared report data.
29-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
30-
* @param bool $showSources Show sources?
31-
* @param int $width Maximum allowed line width.
28+
* @param array<string, string|int|array> $report Prepared report data.
29+
* See the {@see Report} interface for a detailed specification.
30+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
31+
* @param bool $showSources Show sources?
32+
* @param int $width Maximum allowed line width.
3233
*
3334
* @return bool
3435
*/

‎src/Reports/Csv.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,11 @@ class Csv implements Report
2222
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2323
* its data should be counted in the grand totals.
2424
*
25-
* @param array $report Prepared report data.
26-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
27-
* @param bool $showSources Show sources?
28-
* @param int $width Maximum allowed line width.
25+
* @param array<string, string|int|array> $report Prepared report data.
26+
* See the {@see Report} interface for a detailed specification.
27+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28+
* @param bool $showSources Show sources?
29+
* @param int $width Maximum allowed line width.
2930
*
3031
* @return bool
3132
*/

‎src/Reports/Diff.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,11 @@ class Diff implements Report
2222
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2323
* its data should be counted in the grand totals.
2424
*
25-
* @param array $report Prepared report data.
26-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
27-
* @param bool $showSources Show sources?
28-
* @param int $width Maximum allowed line width.
25+
* @param array<string, string|int|array> $report Prepared report data.
26+
* See the {@see Report} interface for a detailed specification.
27+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28+
* @param bool $showSources Show sources?
29+
* @param int $width Maximum allowed line width.
2930
*
3031
* @return bool
3132
*/

‎src/Reports/Emacs.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,11 @@ class Emacs implements Report
2222
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2323
* its data should be counted in the grand totals.
2424
*
25-
* @param array $report Prepared report data.
26-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
27-
* @param bool $showSources Show sources?
28-
* @param int $width Maximum allowed line width.
25+
* @param array<string, string|int|array> $report Prepared report data.
26+
* See the {@see Report} interface for a detailed specification.
27+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28+
* @param bool $showSources Show sources?
29+
* @param int $width Maximum allowed line width.
2930
*
3031
* @return bool
3132
*/

‎src/Reports/Full.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,11 @@ class Full implements Report
2323
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2424
* its data should be counted in the grand totals.
2525
*
26-
* @param array $report Prepared report data.
27-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28-
* @param bool $showSources Show sources?
29-
* @param int $width Maximum allowed line width.
26+
* @param array<string, string|int|array> $report Prepared report data.
27+
* See the {@see Report} interface for a detailed specification.
28+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
29+
* @param bool $showSources Show sources?
30+
* @param int $width Maximum allowed line width.
3031
*
3132
* @return bool
3233
*/

‎src/Reports/Info.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,11 @@ class Info implements Report
2323
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2424
* its data should be counted in the grand totals.
2525
*
26-
* @param array $report Prepared report data.
27-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28-
* @param bool $showSources Show sources?
29-
* @param int $width Maximum allowed line width.
26+
* @param array<string, string|int|array> $report Prepared report data.
27+
* See the {@see Report} interface for a detailed specification.
28+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
29+
* @param bool $showSources Show sources?
30+
* @param int $width Maximum allowed line width.
3031
*
3132
* @return bool
3233
*/

‎src/Reports/Json.php

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,11 @@ class Json implements Report
2323
* and FALSE if it ignored the file. Returning TRUE indicates that the file and
2424
* its data should be counted in the grand totals.
2525
*
26-
* @param array $report Prepared report data.
27-
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
28-
* @param bool $showSources Show sources?
29-
* @param int $width Maximum allowed line width.
26+
* @param array<string, string|int|array> $report Prepared report data.
27+
* See the {@see Report} interface for a detailed specification.
28+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being reported on.
29+
* @param bool $showSources Show sources?
30+
* @param int $width Maximum allowed line width.
3031
*
3132
* @return bool
3233
*/

0 commit comments

Comments
 (0)