protected function Drupal_Sniffs_Commenting_FunctionCommentSniff::processParams in Coder 7.2

Process the function parameter comments.

Parameters

int $commentStart The position in the stack where: the comment started.

Return value

void

1 call to Drupal_Sniffs_Commenting_FunctionCommentSniff::processParams()

Drupal_Sniffs_Commenting_FunctionCommentSniff::process in coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php

Processes this test, when one of its tokens is encountered.

File

coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php, line 421

Class

Drupal_Sniffs_Commenting_FunctionCommentSniff

Parses and verifies the doc comments for functions. Largely copied from Squiz_Sniffs_Commenting_FunctionCommentSniff.

Code

protected function processParams($commentStart) {
  $realParams = $this->currentFile
    ->getMethodParameters($this->_functionToken);
  $params = $this->commentParser
    ->getParams();
  $foundParams = array();
  if (empty($params) === false) {

    // There must be an empty line before the parameter block.
    if (substr_count($params[0]
      ->getWhitespaceBefore(), $this->currentFile->eolChar) < 2) {
      $error = 'There must be an empty line before the parameter block';
      $errorPos = $params[0]
        ->getLine() + $commentStart;
      $this->currentFile
        ->addError($error, $errorPos, 'SpacingBeforeParams');
    }
    $lastParm = count($params) - 1;
    if (substr_count($params[$lastParm]
      ->getWhitespaceAfter(), $this->currentFile->eolChar) !== 2) {
      $error = 'Last parameter comment requires a blank newline after it';
      $errorPos = $params[$lastParm]
        ->getLine() + $commentStart;
      $this->currentFile
        ->addError($error, $errorPos, 'SpacingAfterParams');
    }
    $checkPos = 0;
    foreach ($params as $param) {
      $paramComment = trim($param
        ->getComment());
      $errorPos = $param
        ->getLine() + $commentStart;

      // Make sure that there is only one space before the var type.
      if ($param
        ->getWhitespaceBeforeType() !== ' ') {
        $error = 'Expected 1 space before variable type';
        $this->currentFile
          ->addError($error, $errorPos, 'SpacingBeforeParamType');
      }

      // Make sure they are in the correct order,
      // and have the correct name.
      $pos = $param
        ->getPosition();
      $paramName = '[ UNKNOWN ]';
      if ($param
        ->getVarName() !== '') {
        $paramName = $param
          ->getVarName();
      }

      // Make sure the names of the parameter comment matches the
      // actual parameter.
      $matched = false;

      // Parameter documentation can be ommitted for some parameters, so
      // we have to search the rest for a match.
      while (isset($realParams[$checkPos]) === true) {
        $realName = $realParams[$checkPos]['name'];
        $expectedParamName = $realName;
        $isReference = $realParams[$checkPos]['pass_by_reference'];

        // Append ampersand to name if passing by reference.
        if ($isReference === true && substr($paramName, 0, 1) === '&') {
          $expectedParamName = '&' . $realName;
        }
        if ($expectedParamName === $paramName) {
          $matched = true;
          break;
        }
        $checkPos++;
      }
      if ($matched === false && $paramName !== '...') {
        if ($checkPos >= $pos) {
          $code = 'ParamNameNoMatch';
          $data = array(
            $paramName,
            $realParams[$pos - 1]['name'],
            $pos,
          );
          $error = 'Doc comment for var %s does not match ';
          if (strtolower($paramName) === strtolower($realParams[$pos - 1]['name'])) {
            $error .= 'case of ';
            $code = 'ParamNameNoCaseMatch';
          }
          $error .= 'actual variable name %s at position %s';
          $this->currentFile
            ->addError($error, $errorPos, $code, $data);

          // Reset the parameter position to check for following
          // parameters.
          $checkPos = $pos - 1;
        }
        else {

          // We must have an extra parameter comment.
          $error = 'Superfluous doc comment at position ' . $pos;
          $this->currentFile
            ->addError($error, $errorPos, 'ExtraParamComment');
        }

        //end if
      }

      //end if
      $checkPos++;
      if ($param
        ->getVarName() === '') {
        $error = 'Missing parameter name at position ' . $pos;
        $this->currentFile
          ->addError($error, $errorPos, 'MissingParamName');
      }
      if ($param
        ->getType() === '') {
        $error = 'Missing parameter type at position ' . $pos;
        $this->currentFile
          ->addError($error, $errorPos, 'MissingParamType');
      }
      if (in_array($param
        ->getType(), array(
        'unknown_type',
        '<type>',
        'type',
      )) === true) {
        $error = 'Expected a valid @param data type, but found %s';
        $data = array(
          $param
            ->getType(),
        );
        $this->currentFile
          ->addError($error, $errorPos, 'InvalidParamType', $data);
      }
      if (isset($this->invalidTypes[$param
        ->getType()]) === true) {
        $error = 'Invalid @param data type, expected %s but found %s';
        $data = array(
          $this->invalidTypes[$param
            ->getType()],
          $param
            ->getType(),
        );
        $this->currentFile
          ->addError($error, $errorPos, 'InvalidParamTypeName', $data);
      }
      if ($paramComment === '') {
        $error = 'Missing comment for param "%s" at position %s';
        $data = array(
          $paramName,
          $pos,
        );
        $this->currentFile
          ->addError($error, $errorPos, 'MissingParamComment', $data);
      }
      else {
        if (substr_count($param
          ->getWhitespaceBeforeComment(), $this->currentFile->eolChar) !== 1) {
          $error = 'Parameter comment must be on the next line at position ' . $pos;
          $this->currentFile
            ->addError($error, $errorPos, 'ParamCommentNewLine');
        }
        else {
          if (substr_count($param
            ->getWhitespaceBeforeComment(), ' ') !== 3) {
            $error = 'Parameter comment indentation must be 2 additional spaces at position ' . $pos;
            $this->currentFile
              ->addError($error, $errorPos + 1, 'ParamCommentIndentation');
          }
        }
      }
    }

    //end foreach
  }

  //end if
  $realNames = array();
  foreach ($realParams as $realParam) {
    $realNames[] = $realParam['name'];
  }
}