Chris@17
|
1 <?php
|
Chris@17
|
2 /**
|
Chris@17
|
3 * The base class for all PHP_CodeSniffer documentation generators.
|
Chris@17
|
4 *
|
Chris@17
|
5 * Documentation generators are used to print documentation about code sniffs
|
Chris@17
|
6 * in a standard.
|
Chris@17
|
7 *
|
Chris@17
|
8 * @author Greg Sherwood <gsherwood@squiz.net>
|
Chris@17
|
9 * @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
|
Chris@17
|
10 * @license https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
|
Chris@17
|
11 */
|
Chris@17
|
12
|
Chris@17
|
13 namespace PHP_CodeSniffer\Generators;
|
Chris@17
|
14
|
Chris@17
|
15 use PHP_CodeSniffer\Ruleset;
|
Chris@17
|
16 use PHP_CodeSniffer\Autoload;
|
Chris@17
|
17
|
Chris@17
|
18 abstract class Generator
|
Chris@17
|
19 {
|
Chris@17
|
20
|
Chris@17
|
21 /**
|
Chris@17
|
22 * The ruleset used for the run.
|
Chris@17
|
23 *
|
Chris@17
|
24 * @var \PHP_CodeSniffer\Ruleset
|
Chris@17
|
25 */
|
Chris@17
|
26 public $ruleset = null;
|
Chris@17
|
27
|
Chris@17
|
28 /**
|
Chris@17
|
29 * XML documentation files used to produce the final output.
|
Chris@17
|
30 *
|
Chris@17
|
31 * @var string[]
|
Chris@17
|
32 */
|
Chris@17
|
33 public $docFiles = [];
|
Chris@17
|
34
|
Chris@17
|
35
|
Chris@17
|
36 /**
|
Chris@17
|
37 * Constructs a doc generator.
|
Chris@17
|
38 *
|
Chris@17
|
39 * @param \PHP_CodeSniffer\Ruleset $ruleset The ruleset used for the run.
|
Chris@17
|
40 *
|
Chris@17
|
41 * @see generate()
|
Chris@17
|
42 */
|
Chris@17
|
43 public function __construct(Ruleset $ruleset)
|
Chris@17
|
44 {
|
Chris@17
|
45 $this->ruleset = $ruleset;
|
Chris@17
|
46
|
Chris@17
|
47 foreach ($ruleset->sniffs as $className => $sniffClass) {
|
Chris@17
|
48 $file = Autoload::getLoadedFileName($className);
|
Chris@17
|
49 $docFile = str_replace(
|
Chris@17
|
50 DIRECTORY_SEPARATOR.'Sniffs'.DIRECTORY_SEPARATOR,
|
Chris@17
|
51 DIRECTORY_SEPARATOR.'Docs'.DIRECTORY_SEPARATOR,
|
Chris@17
|
52 $file
|
Chris@17
|
53 );
|
Chris@17
|
54 $docFile = str_replace('Sniff.php', 'Standard.xml', $docFile);
|
Chris@17
|
55
|
Chris@17
|
56 if (is_file($docFile) === true) {
|
Chris@17
|
57 $this->docFiles[] = $docFile;
|
Chris@17
|
58 }
|
Chris@17
|
59 }
|
Chris@17
|
60
|
Chris@17
|
61 }//end __construct()
|
Chris@17
|
62
|
Chris@17
|
63
|
Chris@17
|
64 /**
|
Chris@17
|
65 * Retrieves the title of the sniff from the DOMNode supplied.
|
Chris@17
|
66 *
|
Chris@17
|
67 * @param \DOMNode $doc The DOMNode object for the sniff.
|
Chris@17
|
68 * It represents the "documentation" tag in the XML
|
Chris@17
|
69 * standard file.
|
Chris@17
|
70 *
|
Chris@17
|
71 * @return string
|
Chris@17
|
72 */
|
Chris@17
|
73 protected function getTitle(\DOMNode $doc)
|
Chris@17
|
74 {
|
Chris@17
|
75 return $doc->getAttribute('title');
|
Chris@17
|
76
|
Chris@17
|
77 }//end getTitle()
|
Chris@17
|
78
|
Chris@17
|
79
|
Chris@17
|
80 /**
|
Chris@17
|
81 * Generates the documentation for a standard.
|
Chris@17
|
82 *
|
Chris@17
|
83 * It's probably wise for doc generators to override this method so they
|
Chris@17
|
84 * have control over how the docs are produced. Otherwise, the processSniff
|
Chris@17
|
85 * method should be overridden to output content for each sniff.
|
Chris@17
|
86 *
|
Chris@17
|
87 * @return void
|
Chris@17
|
88 * @see processSniff()
|
Chris@17
|
89 */
|
Chris@17
|
90 public function generate()
|
Chris@17
|
91 {
|
Chris@17
|
92 foreach ($this->docFiles as $file) {
|
Chris@17
|
93 $doc = new \DOMDocument();
|
Chris@17
|
94 $doc->load($file);
|
Chris@17
|
95 $documentation = $doc->getElementsByTagName('documentation')->item(0);
|
Chris@17
|
96 $this->processSniff($documentation);
|
Chris@17
|
97 }
|
Chris@17
|
98
|
Chris@17
|
99 }//end generate()
|
Chris@17
|
100
|
Chris@17
|
101
|
Chris@17
|
102 /**
|
Chris@17
|
103 * Process the documentation for a single sniff.
|
Chris@17
|
104 *
|
Chris@17
|
105 * Doc generators must implement this function to produce output.
|
Chris@17
|
106 *
|
Chris@17
|
107 * @param \DOMNode $doc The DOMNode object for the sniff.
|
Chris@17
|
108 * It represents the "documentation" tag in the XML
|
Chris@17
|
109 * standard file.
|
Chris@17
|
110 *
|
Chris@17
|
111 * @return void
|
Chris@17
|
112 * @see generate()
|
Chris@17
|
113 */
|
Chris@17
|
114 abstract protected function processSniff(\DOMNode $doc);
|
Chris@17
|
115
|
Chris@17
|
116
|
Chris@17
|
117 }//end class
|