Chris@0: Chris@0: * @author Marc McIntyre Chris@0: * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600) Chris@0: * @license https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence Chris@0: * @link http://pear.php.net/package/PHP_CodeSniffer Chris@0: */ Chris@0: Chris@0: /** Chris@0: * The base class for all PHP_CodeSniffer documentation generators. Chris@0: * Chris@0: * Documentation generators are used to print documentation about code sniffs Chris@0: * in a standard. Chris@0: * Chris@0: * @category PHP Chris@0: * @package PHP_CodeSniffer Chris@0: * @author Greg Sherwood Chris@0: * @author Marc McIntyre Chris@0: * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600) Chris@0: * @license https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence Chris@0: * @version Release: @package_version@ Chris@0: * @link http://pear.php.net/package/PHP_CodeSniffer Chris@0: */ Chris@0: abstract class PHP_CodeSniffer_DocGenerators_Generator Chris@0: { Chris@0: Chris@0: /** Chris@0: * The name of the coding standard we are generating docs for. Chris@0: * Chris@0: * @var string Chris@0: */ Chris@0: private $_standard = ''; Chris@0: Chris@0: /** Chris@0: * An array of sniffs that we are limiting the generated docs to. Chris@0: * Chris@0: * If this array is empty, docs are generated for all sniffs in the Chris@0: * supplied coding standard. Chris@0: * Chris@0: * @var string Chris@0: */ Chris@0: private $_sniffs = array(); Chris@0: Chris@0: Chris@0: /** Chris@0: * Constructs a PHP_CodeSniffer_DocGenerators_Generator object. Chris@0: * Chris@0: * @param string $standard The name of the coding standard to generate Chris@0: * docs for. Chris@0: * @param array $sniffs An array of sniffs that we are limiting the Chris@0: * generated docs to. Chris@0: * Chris@0: * @see generate() Chris@0: */ Chris@0: public function __construct($standard, array $sniffs=array()) Chris@0: { Chris@0: $this->_standard = $standard; Chris@0: $this->_sniffs = $sniffs; Chris@0: Chris@0: }//end __construct() Chris@0: Chris@0: Chris@0: /** Chris@0: * Retrieves the title of the sniff from the DOMNode supplied. Chris@0: * Chris@0: * @param DOMNode $doc The DOMNode object for the sniff. Chris@0: * It represents the "documentation" tag in the XML Chris@0: * standard file. Chris@0: * Chris@0: * @return string Chris@0: */ Chris@0: protected function getTitle(DOMNode $doc) Chris@0: { Chris@0: return $doc->getAttribute('title'); Chris@0: Chris@0: }//end getTitle() Chris@0: Chris@0: Chris@0: /** Chris@0: * Retrieves the name of the standard we are generating docs for. Chris@0: * Chris@0: * @return string Chris@0: */ Chris@0: protected function getStandard() Chris@0: { Chris@0: return $this->_standard; Chris@0: Chris@0: }//end getStandard() Chris@0: Chris@0: Chris@0: /** Chris@0: * Generates the documentation for a standard. Chris@0: * Chris@0: * It's probably wise for doc generators to override this method so they Chris@0: * have control over how the docs are produced. Otherwise, the processSniff Chris@0: * method should be overridden to output content for each sniff. Chris@0: * Chris@0: * @return void Chris@0: * @see processSniff() Chris@0: */ Chris@0: public function generate() Chris@0: { Chris@0: $standardFiles = $this->getStandardFiles(); Chris@0: Chris@0: foreach ($standardFiles as $standard) { Chris@0: $doc = new DOMDocument(); Chris@0: $doc->load($standard); Chris@0: $documentation = $doc->getElementsByTagName('documentation')->item(0); Chris@0: $this->processSniff($documentation); Chris@0: } Chris@0: Chris@0: }//end generate() Chris@0: Chris@0: Chris@0: /** Chris@0: * Returns a list of paths to XML standard files for all sniffs in a standard. Chris@0: * Chris@0: * Any sniffs that do not have an XML standard file are obviously not included Chris@0: * in the returned array. If documentation is only being generated for some Chris@0: * sniffs (ie. $this->_sniffs is not empty) then all others sniffs will Chris@0: * be filtered from the results as well. Chris@0: * Chris@0: * @return string[] Chris@0: */ Chris@0: protected function getStandardFiles() Chris@0: { Chris@0: $phpcs = new PHP_CodeSniffer(); Chris@0: $phpcs->process(array(), $this->_standard); Chris@0: $sniffs = $phpcs->getSniffs(); Chris@0: Chris@0: $standardFiles = array(); Chris@0: foreach ($sniffs as $className => $sniffClass) { Chris@0: $object = new ReflectionObject($sniffClass); Chris@0: $sniff = $object->getFilename(); Chris@0: if (empty($this->_sniffs) === false) { Chris@0: // We are limiting the docs to certain sniffs only, so filter Chris@0: // out any unwanted sniffs. Chris@0: $parts = explode('_', $className); Chris@0: $sniffName = $parts[0].'.'.$parts[2].'.'.substr($parts[3], 0, -5); Chris@0: if (in_array($sniffName, $this->_sniffs) === false) { Chris@0: continue; Chris@0: } Chris@0: } Chris@0: Chris@0: $standardFile = str_replace( Chris@0: DIRECTORY_SEPARATOR.'Sniffs'.DIRECTORY_SEPARATOR, Chris@0: DIRECTORY_SEPARATOR.'Docs'.DIRECTORY_SEPARATOR, Chris@0: $sniff Chris@0: ); Chris@0: $standardFile = str_replace('Sniff.php', 'Standard.xml', $standardFile); Chris@0: Chris@0: if (is_file($standardFile) === true) { Chris@0: $standardFiles[] = $standardFile; Chris@0: } Chris@0: }//end foreach Chris@0: Chris@0: return $standardFiles; Chris@0: Chris@0: }//end getStandardFiles() Chris@0: Chris@0: Chris@0: /** Chris@0: * Process the documentation for a single sniff. Chris@0: * Chris@0: * Doc generators must implement this function to produce output. Chris@0: * Chris@0: * @param DOMNode $doc The DOMNode object for the sniff. Chris@0: * It represents the "documentation" tag in the XML Chris@0: * standard file. Chris@0: * Chris@0: * @return void Chris@0: * @see generate() Chris@0: */ Chris@0: protected abstract function processSniff(DOMNode $doc); Chris@0: Chris@0: Chris@0: }//end class