feat(DocCommentLongArraySyntax): Enforce short array syntax for Drupal API doc...

<?php

/**

 * Ensures @code annotations in doc blocks don't contain long array syntax.

 *

 * @category PHP

 * @package  PHP_CodeSniffer

 * @link     http://pear.php.net/package/PHP_CodeSniffer

 */

namespace Drupal\Sniffs\Commenting;

use PHP_CodeSniffer\Files\File;

use PHP_CodeSniffer\Sniffs\Sniff;

/**

 * Ensures @code annotations in doc blocks don't contain long array syntax.

 *

 * @category PHP

 * @package  PHP_CodeSniffer

 * @link     http://pear.php.net/package/PHP_CodeSniffer

 */

class DocCommentLongArraySyntaxSniff implements Sniff

{

    /**

     * Returns an array of tokens this test wants to listen for.

     *

     * @return array<int|string>

     */

    public function register()

    {

        return [T_DOC_COMMENT_OPEN_TAG];

    }//end register()

    /**

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

     *

     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.

     * @param int                         $stackPtr  The position of the current token

     *                                               in the stack passed in $tokens.

     *

     * @return void

     */

    public function process(File $phpcsFile, $stackPtr)

    {

        $tokens     = $phpcsFile->getTokens();

        $commentEnd = $phpcsFile->findNext(T_DOC_COMMENT_CLOSE_TAG, ($stackPtr + 1));

        // Look for @code annotations.

        $codeEnd = $stackPtr;

        do {

            $codeStart = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($codeEnd + 1), $commentEnd, false, '@code');

            if ($codeStart !== false) {

                $codeEnd = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($codeStart + 1), $commentEnd, false, '@endcode');

                if ($codeEnd !== false) {

                    // Check for long array syntax use inside this @code annotation.

                    for ($i = ($codeStart + 1); $i < $codeEnd; $i++) {

                        if (preg_match('/\barray\s*\(/', $tokens[$i]['content']) === 1) {

                            $error = 'Long array syntax used in doc comment code annotation';

                            $phpcsFile->addError($error, $i, 'DocLongArray');

                        }

                    }

                }

            }

        } while ($codeStart !== false);

    }//end process()

}//end class

<?php

/**

 * @file

 * Test long array syntax in doc comments.

 */

/**

 * Long array syntax used.

 * @code

 * $table = array(

 *   '#type' => 'table',

 * );

 * @endcode

 */

function test1() {

}

/**

 * Nested long array syntax used.

 * @code

 * $table = array(

 *   '#attributes' => array(

 *     'id' => 'my-module-table',

 *   ),

 * );

 * @endcode

 */

function test2() {

}

<?php

namespace Drupal\Test\Commenting;

use Drupal\Test\CoderSniffUnitTest;

class DocCommentLongArraySyntaxUnitTest extends CoderSniffUnitTest

{

    /**

     * Returns the lines where errors should occur.

     *

     * The key of the array should represent the line number and the value

     * should represent the number of errors that should occur on that line.

     *

     * @param string $testFile The name of the file being tested.

     *

     * @return array<int, int>

     */

    protected function getErrorList(string $testFile): array

    {

        return [

            11 => 1,

            23 => 1,

            24 => 1,

        ];

    }//end getErrorList()

    /**

     * Returns the lines where warnings should occur.

     *

     * The key of the array should represent the line number and the value

     * should represent the number of warnings that should occur on that line.

     *

     * @param string $testFile The name of the file being tested.

     *

     * @return array<int, int>

     */

    protected function getWarningList(string $testFile): array

    {

        return [];

    }//end getWarningList()

}//end class

   *   Just some Example param.

   * @param ...

   *   Any additional arguments are passed on to the functions called by

   *   drupal_form_submit(), including the unique form constructor function.

   *   self::submitForm(), including the unique form constructor function.

   *   For example, the node_edit form requires that a node object be passed

   *   in here when it is called. Arguments that need to be passed by reference

   *   should not be included here, but rather placed directly in the $form

   *   build info array so that the reference can be preserved. For example, a

   *   form builder function with the following signature:

   *   should not be included here, but rather placed directly in the

   *   $form_state build info array so that the reference can be preserved. For

   *   example, a form builder function with the following signature:

   *   @code

   *   function mymodule_form($form, &$form_state, &$object) {

   *   function mymodule_form($form, FormStateInterface &$form_state, &$object) {

   *   }

   *   @endcode

   *   would be called via drupal_form_submit() as follows:

   *   would be called via self::submitForm() as follows:

   *   @code

   *   $form_state['values'] = $my_form_values;

   *   $form_state['build_info']['args'] = array(&$object);

   *   drupal_form_submit('mymodule_form', $form_state);

   *   $form_state->setValues($my_form_values);

   *   $form_state->addBuildInfo('args', [&$object]);

   *   \Drupal::formBuilder()->submitForm('mymodule_form', $form_state);

   *   @endcode

   */

  public function test1($param1);