PageRenderTime 50ms CodeModel.GetById 21ms RepoModel.GetById 0ms app.codeStats 0ms

/.dev/code-sniffs/XLite/Sniffs/PHP/Commenting/FunctionCommentSniff.php

https://github.com/istran/core
PHP | 292 lines | 177 code | 40 blank | 75 comment | 22 complexity | 504fc5e08750e867506dc6ce373d849a MD5 | raw file
Possible License(s): GPL-2.0, BSD-3-Clause
  1. <?php
  2. /**
  3. * Parses and verifies the doc comments for functions.
  4. *
  5. * PHP version 5
  6. *
  7. * @category PHP
  8. * @package PHP_CodeSniffer
  9. * @author Greg Sherwood <gsherwood@squiz.net>
  10. * @author Marc McIntyre <mmcintyre@squiz.net>
  11. * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)
  12. * @license http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
  13. * @version CVS: $Id: cbbde8826ed828ff019fd790f23b2ee764572152 $
  14. * @link http://pear.php.net/package/PHP_CodeSniffer
  15. */
  16. if (class_exists('PHP_CodeSniffer_CommentParser_FunctionCommentParser', true) === false) {
  17. throw new PHP_CodeSniffer_Exception('Class PHP_CodeSniffer_CommentParser_FunctionCommentParser not found');
  18. }
  19. /**
  20. * Parses and verifies the doc comments for functions.
  21. *
  22. * Verifies that :
  23. * <ul>
  24. * <li>A comment exists</li>
  25. * <li>There is a blank newline after the short description.</li>
  26. * <li>There is a blank newline between the long and short description.</li>
  27. * <li>There is a blank newline between the long description and tags.</li>
  28. * <li>Parameter names represent those in the method.</li>
  29. * <li>Parameter comments are in the correct order</li>
  30. * <li>Parameter comments are complete</li>
  31. * <li>A space is present before the first and after the last parameter</li>
  32. * <li>A return type exists</li>
  33. * <li>There must be one blank line between body and headline comments.</li>
  34. * <li>Any throw tag must have an exception class.</li>
  35. * </ul>
  36. *
  37. * @category PHP
  38. * @package PHP_CodeSniffer
  39. * @author Greg Sherwood <gsherwood@squiz.net>
  40. * @author Marc McIntyre <mmcintyre@squiz.net>
  41. * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)
  42. * @license http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
  43. * @version Release: 1.2.0RC1
  44. * @link http://pear.php.net/package/PHP_CodeSniffer
  45. */
  46. class XLite_Sniffs_PHP_Commenting_FunctionCommentSniff extends XLite_TagsSniff
  47. {
  48. /**
  49. * The function comment parser for the current method.
  50. *
  51. * @var PHP_CodeSniffer_Comment_Parser_FunctionCommentParser
  52. */
  53. protected $commentParser = null;
  54. /**
  55. * The current PHP_CodeSniffer_File object we are processing.
  56. *
  57. * @var PHP_CodeSniffer_File
  58. */
  59. protected $currentFile = null;
  60. protected $tags = array(
  61. 'param' => array(
  62. 'required' => false,
  63. 'allow_multiple' => true,
  64. 'order_text' => 'precedes @return',
  65. ),
  66. 'return' => array(
  67. 'required' => true,
  68. 'allow_multiple' => false,
  69. 'order_text' => 'follows @param',
  70. ),
  71. 'throws' => array(
  72. 'required' => false,
  73. 'allow_multiple' => true,
  74. 'order_text' => 'follows @return',
  75. ),
  76. 'access' => array(
  77. 'required' => false,
  78. 'allow_multiple' => false,
  79. 'order_text' => 'follows @throws',
  80. ),
  81. 'see' => array(
  82. 'required' => false,
  83. 'allow_multiple' => false,
  84. 'order_text' => 'follows @access',
  85. ),
  86. 'since' => array(
  87. 'required' => true,
  88. 'allow_multiple' => false,
  89. 'order_text' => 'follows @see',
  90. ),
  91. 'PreRemove' => array(
  92. 'required' => false,
  93. 'allow_multiple' => false,
  94. 'order_text' => 'follows @see',
  95. ),
  96. 'PreUpdate' => array(
  97. 'required' => false,
  98. 'allow_multiple' => false,
  99. 'order_text' => 'follows @see',
  100. ),
  101. 'PrePersist' => array(
  102. 'required' => false,
  103. 'allow_multiple' => false,
  104. 'order_text' => 'follows @see',
  105. ),
  106. );
  107. protected $reqCodeRequire = array('REQ.PHP.4.5.3');
  108. protected $reqCodePHPVersion = false;
  109. protected $reqCodeForbidden = 'REQ.PHP.4.5.3';
  110. protected $reqCodeOnlyOne = 'REQ.PHP.4.5.7';
  111. protected $docBlock = 'method / function';
  112. /**
  113. * Returns an array of tokens this test wants to listen for.
  114. *
  115. * @return array
  116. */
  117. public function register()
  118. {
  119. return array(T_FUNCTION);
  120. }//end register()
  121. /**
  122. * Processes this test, when one of its tokens is encountered.
  123. *
  124. * @param PHP_CodeSniffer_File $phpcsFile The file being scanned.
  125. * @param int $stackPtr The position of the current token
  126. * in the stack passed in $tokens.
  127. *
  128. * @return void
  129. */
  130. public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
  131. {
  132. $tokens = $phpcsFile->getTokens();
  133. $next = $phpcsFile->findNext(T_WHITESPACE, $stackPtr + 1, null, true);
  134. if ($tokens[$next]['code'] !== T_STRING)
  135. return;
  136. $find = array(
  137. T_COMMENT,
  138. T_DOC_COMMENT,
  139. T_CLASS,
  140. T_FUNCTION,
  141. T_OPEN_TAG,
  142. );
  143. $commentEnd = $phpcsFile->findPrevious($find, ($stackPtr - 1));
  144. if ($commentEnd === false) {
  145. return;
  146. }
  147. $this->currentFile = $phpcsFile;
  148. $tokens = $phpcsFile->getTokens();
  149. // If the token that we found was a class or a function, then this
  150. // function has no doc comment.
  151. $code = $tokens[$commentEnd]['code'];
  152. if ($code === T_COMMENT) {
  153. $error = 'You must use "/**" style comments for a function comment';
  154. $phpcsFile->addError($this->getReqPrefix('REQ.PHP.4.5.6') . $error, $stackPtr);
  155. return;
  156. } else if ($code !== T_DOC_COMMENT) {
  157. $error = 'Missing function doc comment';
  158. $phpcsFile->addError($this->getReqPrefix('REQ.PHP.4.5.1') . $error, $stackPtr);
  159. return;
  160. }
  161. // If there is any code between the function keyword and the doc block
  162. // then the doc block is not for us.
  163. $ignore = PHP_CodeSniffer_Tokens::$scopeModifiers;
  164. $ignore[] = T_STATIC;
  165. $ignore[] = T_WHITESPACE;
  166. $ignore[] = T_ABSTRACT;
  167. $ignore[] = T_FINAL;
  168. $prevToken = $phpcsFile->findPrevious($ignore, ($stackPtr - 1), null, true);
  169. if ($prevToken !== $commentEnd) {
  170. $phpcsFile->addError($this->getReqPrefix('REQ.PHP.4.5.1') . 'Missing function doc comment', $stackPtr);
  171. return;
  172. }
  173. $this->_functionToken = $stackPtr;
  174. $this->_classToken = null;
  175. foreach ($tokens[$stackPtr]['conditions'] as $condPtr => $condition) {
  176. if ($condition === T_CLASS || $condition === T_INTERFACE) {
  177. $this->_classToken = $condPtr;
  178. break;
  179. }
  180. }
  181. $this->tags['access']['required'] = !is_null($this->_classToken);
  182. if ($this->tags['access']['required']) {
  183. $this->reqCodeRequire = array('REQ.PHP.4.5.3', 'REQ.PHP.4.5.9');
  184. } else {
  185. $this->reqCodeRequire = array('REQ.PHP.4.5.3');
  186. }
  187. // If the first T_OPEN_TAG is right before the comment, it is probably
  188. // a file comment.
  189. $commentStart = ($phpcsFile->findPrevious(T_DOC_COMMENT, ($commentEnd - 1), null, true) + 1);
  190. $prevToken = $phpcsFile->findPrevious(T_WHITESPACE, ($commentStart - 1), null, true);
  191. if ($tokens[$prevToken]['code'] === T_OPEN_TAG) {
  192. // Is this the first open tag?
  193. if ($stackPtr === 0 || $phpcsFile->findPrevious(T_OPEN_TAG, ($prevToken - 1)) === false) {
  194. $phpcsFile->addError($this->getReqPrefix('REQ.PHP.4.5.1') . 'Missing function doc comment', $stackPtr);
  195. return;
  196. }
  197. }
  198. $comment = $phpcsFile->getTokensAsString($commentStart, ($commentEnd - $commentStart + 1));
  199. $this->_methodName = $phpcsFile->getDeclarationName($stackPtr);
  200. try {
  201. $this->commentParser = new XLite_FunctionCommentParser($comment, $phpcsFile);
  202. $this->commentParser->parse();
  203. } catch (PHP_CodeSniffer_CommentParser_ParserException $e) {
  204. $line = ($e->getLineWithinComment() + $commentStart);
  205. $phpcsFile->addError($this->getReqPrefix('REQ.PHP.4.1.1') . $e->getMessage(), $line);
  206. return;
  207. }
  208. $comment = $this->commentParser->getComment();
  209. if (is_null($comment) === true) {
  210. $error = 'Function doc comment is empty';
  211. $phpcsFile->addError($this->getReqPrefix('REQ.PHP.4.5.2') . $error, $commentStart);
  212. return;
  213. }
  214. $this->checkAccess($stackPtr, $commentStart, $commentEnd);
  215. $this->processTags($commentStart, $commentEnd);
  216. // No extra newline before short description.
  217. $short = $comment->getShortComment();
  218. $newlineCount = 0;
  219. $newlineSpan = strspn($short, $phpcsFile->eolChar);
  220. if ($short !== '' && $newlineSpan > 0) {
  221. $line = ($newlineSpan > 1) ? 'newlines' : 'newline';
  222. $error = "Extra $line found before function comment short description";
  223. $phpcsFile->addError($this->getReqPrefix('REQ.PHP.4.1.7') . $error, ($commentStart + 1));
  224. }
  225. $newlineCount = (substr_count($short, $phpcsFile->eolChar) + 1);
  226. // Exactly one blank line between short and long description.
  227. $long = $comment->getLongComment();
  228. if (empty($long) === false) {
  229. $between = $comment->getWhiteSpaceBetween();
  230. $newlineBetween = substr_count($between, $phpcsFile->eolChar);
  231. if ($newlineBetween !== 2) {
  232. $error = 'There must be exactly one blank line between descriptions in function comment';
  233. $phpcsFile->addError($this->getReqPrefix('REQ.PHP.4.1.19') . $error, ($commentStart + $newlineCount + 1));
  234. }
  235. $newlineCount += $newlineBetween;
  236. }
  237. // Exactly one blank line before tags.
  238. $params = $this->commentParser->getTagOrders();
  239. if (count($params) > 1) {
  240. $newlineSpan = $comment->getNewlineAfter();
  241. if ($newlineSpan !== 2) {
  242. $error = 'There must be exactly one blank line before the tags in function comment';
  243. if ($long !== '') {
  244. $newlineCount += (substr_count($long, $phpcsFile->eolChar) - $newlineSpan + 1);
  245. }
  246. $phpcsFile->addError($this->getReqPrefix('REQ.PHP.4.1.18') . $error, ($commentStart + $newlineCount));
  247. $short = rtrim($short, $phpcsFile->eolChar.' ');
  248. }
  249. }
  250. }//end process()
  251. }//end class
  252. ?>