Issue #2707641 by alexpott, anoopjohn: Ensure core compliance to...

Issue #2707641 by alexpott, anoopjohn: Ensure core compliance to Drupal.Commenting.FunctionComment.ParamCommentIndentation (part 2)

core/includes/theme.inc

@@ -580,6 +580,15 @@ function template_preprocess_datetime_wrapper(&$variables) {
  *
  * Default template: links.html.twig.
  *
+ * Unfortunately links templates duplicate the "active" class handling of l()
+ * and LinkGenerator::generate() because it needs to be able to set the "active"
+ * class not on the links themselves ("a" tags), but on the list items ("li"
+ * tags) that contain the links. This is necessary for CSS to be able to style
+ * list items differently when the link is active, since CSS does not yet allow
+ * one to style list items only if it contains a certain element with a certain
+ * class. I.e. we cannot yet convert this jQuery selector to a CSS selector:
+ * jQuery('li:has("a.is-active")')
+ *
  * @param array $variables
  *   An associative array containing:
  *   - links: An array of links to be themed. Each link should be itself an
@@ -622,15 +631,6 @@ function template_preprocess_datetime_wrapper(&$variables) {
  *     http://juicystudio.com/article/screen-readers-display-none.php and
  *     http://www.w3.org/TR/WCAG-TECHS/H42.html for more information.
  *
- * Unfortunately links templates duplicate the "active" class handling of l()
- * and LinkGenerator::generate() because it needs to be able to set the "active"
- * class not on the links themselves ("a" tags), but on the list items ("li"
- * tags) that contain the links. This is necessary for CSS to be able to style
- * list items differently when the link is active, since CSS does not yet allow
- * one to style list items only if it contains a certain element with a certain
- * class. I.e. we cannot yet convert this jQuery selector to a CSS selector:
- *   jQuery('li:has("a.is-active")')
- *
  * @see \Drupal\Core\Utility\LinkGenerator
  * @see \Drupal\Core\Utility\LinkGenerator::generate()
  * @see system_page_attachments()

core/lib/Drupal/Core/Asset/CssOptimizer.php

@@ -236,14 +236,14 @@ protected function processCss($contents, $optimize = FALSE) {
   /**
    * Prefixes all paths within a CSS file for processFile().
    *
-   * @param array $matches
-   *   An array of matches by a preg_replace_callback() call that scans for
-   *   url() references in CSS files, except for external or absolute ones.
-   *
    * Note: the only reason this method is public is so color.module can call it;
    * it is not on the AssetOptimizerInterface, so future refactorings can make
    * it protected.
    *
+   * @param array $matches
+   *   An array of matches by a preg_replace_callback() call that scans for
+   *   url() references in CSS files, except for external or absolute ones.
+   *
    * @return string
    *   The file path.
    */

core/lib/Drupal/Core/Config/StorableConfigBase.php

@@ -60,13 +60,13 @@ abstract class StorableConfigBase extends ConfigBase {
   /**
    * Saves the configuration object.
    *
+   * Must invalidate the cache tags associated with the configuration object.
+   *
    * @param bool $has_trusted_data
    *   Set to TRUE if the configuration data has already been checked to ensure
    *   it conforms to schema. Generally this is only used during module and
    *   theme installation.
    *
-   * Must invalidate the cache tags associated with the configuration object.
-   *
    * @return $this
    *
    * @see \Drupal\Core\Config\ConfigInstaller::createConfiguration()

core/lib/Drupal/Core/Entity/entity.api.php

@@ -1263,7 +1263,9 @@ function hook_entity_query_alter(\Drupal\Core\Entity\Query\QueryInterface $query
  * Act on entities being assembled before rendering.
  *
  * @param &$build
- *   A renderable array representing the entity content.
+ *   A renderable array representing the entity content. The module may add
+ *   elements to $build prior to rendering. The structure of $build is a
+ *   renderable array as expected by drupal_render().
  * @param \Drupal\Core\Entity\EntityInterface $entity
  *   The entity object.
  * @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display
@@ -1272,10 +1274,6 @@ function hook_entity_query_alter(\Drupal\Core\Entity\Query\QueryInterface $query
  * @param $view_mode
  *   The view mode the entity is rendered in.
  *
- * The module may add elements to $build prior to rendering. The
- * structure of $build is a renderable array as expected by
- * drupal_render().
- *
  * @see hook_entity_view_alter()
  * @see hook_ENTITY_TYPE_view()
  *
@@ -1297,7 +1295,9 @@ function hook_entity_view(array &$build, \Drupal\Core\Entity\EntityInterface $en
  * Act on entities of a particular type being assembled before rendering.
  *
  * @param &$build
- *   A renderable array representing the entity content.
+ *   A renderable array representing the entity content. The module may add
+ *   elements to $build prior to rendering. The structure of $build is a
+ *   renderable array as expected by drupal_render().
  * @param \Drupal\Core\Entity\EntityInterface $entity
  *   The entity object.
  * @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display
@@ -1306,10 +1306,6 @@ function hook_entity_view(array &$build, \Drupal\Core\Entity\EntityInterface $en
  * @param $view_mode
  *   The view mode the entity is rendered in.
  *
- * The module may add elements to $build prior to rendering. The
- * structure of $build is a renderable array as expected by
- * drupal_render().
- *
  * @see hook_ENTITY_TYPE_view_alter()
  * @see hook_entity_view()
  *

core/lib/Drupal/Core/Render/Element/Button.php

@@ -72,10 +72,9 @@ public static function processButton(&$element, FormStateInterface $form_state,
    *
    * @param array $element
    *   An associative array containing the properties of the element.
-   *   Properties used: #attributes, #button_type, #name, #value.
-   *
-   * The #button_type property accepts any value, though core themes have CSS that
-   * styles the following button_types appropriately: 'primary', 'danger'.
+   *   Properties used: #attributes, #button_type, #name, #value. The
+   *   #button_type property accepts any value, though core themes have CSS that
+   *   styles the following button_types appropriately: 'primary', 'danger'.
    *
    * @return array
    *   The $element with prepared variables ready for input.html.twig.

core/lib/Drupal/Core/Render/Element/Date.php

@@ -76,11 +76,9 @@ public static function processDate(&$element, FormStateInterface $form_state, &$
    * @param array $element
    *   An associative array containing the properties of the element.
    *   Properties used: #title, #value, #options, #description, #required,
-   *   #attributes, #id, #name, #type, #min, #max, #step, #value, #size.
-   *
-   * Note: The input "name" attribute needs to be sanitized before output, which
-   *       is currently done by initializing Drupal\Core\Template\Attribute with
-   *       all the attributes.
+   *   #attributes, #id, #name, #type, #min, #max, #step, #value, #size. The
+   *   #name property will be sanitized before output. This is currently done by
+   *   initializing Drupal\Core\Template\Attribute with all the attributes.
    *
    * @return array
    *   The $element with prepared variables ready for #theme 'input__date'.

core/lib/Drupal/Core/Render/Element/Radio.php

@@ -43,11 +43,9 @@ public function getInfo() {
    * @param array $element
    *   An associative array containing the properties of the element.
    *   Properties used: #required, #return_value, #value, #attributes, #title,
-   *   #description.
-   *
-   * Note: The input "name" attribute needs to be sanitized before output, which
-   *       is currently done by initializing Drupal\Core\Template\Attribute with
-   *       all the attributes.
+   *   #description. The #name property will be sanitized before output. This is
+   *   currently done by initializing Drupal\Core\Template\Attribute with all
+   *   the attributes.
    *
    * @return array
    *   The $element with prepared variables ready for input.html.twig.

core/lib/Drupal/Core/Theme/ThemeManagerInterface.php

@@ -65,7 +65,8 @@ public function setActiveTheme(ActiveTheme $active_theme);
   /**
    * Passes alterable variables to specific $theme_TYPE_alter() implementations.
    *
-   * It also invokes alter hooks for all base themes.
+   * Executes an alter hook on the current theme. It also invokes alter hooks
+   * for all base themes.
    *
    * $theme specifies the theme name of the active theme and all its base
    * themes.
@@ -114,7 +115,6 @@ public function setActiveTheme(ActiveTheme $active_theme);
    *   (optional) An additional variable that is passed by reference. If more
    *   context needs to be provided to implementations, then this should be an
    *   associative array as described above.
-   * Execute the alter hook on the current theme.
    *
    * @see \Drupal\Core\Extension\ModuleHandlerInterface
    */

core/lib/Drupal/Core/Url.php

@@ -228,7 +228,10 @@ public static function fromUserInput($user_input, $options = []) {
    *   that are known not to be handled by the Drupal routing system (such as
    *   static files), use base: for the scheme to get a link relative to the
    *   Drupal base path (like the <base> HTML element). For a link to an entity
-   *   you may use entity:{entity_type}/{entity_id} URIs.
+   *   you may use entity:{entity_type}/{entity_id} URIs. The internal: scheme
+   *   should be avoided except when processing actual user input that may or
+   *   may not correspond to a Drupal route. Normally use Url::fromRoute() for
+   *   code linking to any any Drupal page.
    * @param array $options
    *   (optional) An associative array of additional URL options, with the
    *   following elements:
@@ -249,14 +252,9 @@ public static function fromUserInput($user_input, $options = []) {
    *     defined, the current scheme is used, so the user stays on HTTP or HTTPS
    *     respectively. TRUE enforces HTTPS and FALSE enforces HTTP.
    *
-   * Note: the internal: scheme should be avoided except when processing actual
-   * user input that may or may not correspond to a Drupal route. Normally use
-   * Url::fromRoute() for code linking to any any Drupal page.
-   *
-   * You can call access() on the returned object to do access checking.
-   *
    * @return \Drupal\Core\Url
-   *   A new Url object with properties depending on the URI scheme.
+   *   A new Url object with properties depending on the URI scheme. Call the
+   *   access() method on this to do access checking.
    *
    * @throws \InvalidArgumentException
    *   Thrown when the passed in path has no scheme.

core/modules/book/src/BookManagerInterface.php

@@ -135,11 +135,11 @@ public function bookTreeCollectNodeLinks(&$tree, &$node_links);
   /**
    * Provides book loading, access control and translation.
    *
-   * @param array $link
-   *   A book link.
-   *
    * Note: copied from _menu_link_translate() in menu.inc, but reduced to the
    * minimal code that's used.
+   *
+   * @param array $link
+   *   A book link.
    */
   public function bookLinkTranslate(&$link);
 

core/modules/field/src/Entity/FieldStorageConfig.php

@@ -222,6 +222,10 @@ class FieldStorageConfig extends ConfigEntityBase implements FieldStorageConfigI
   /**
    * Constructs a FieldStorageConfig object.
    *
+   * In most cases, Field entities are created via
+   * FieldStorageConfig::create($values)), where $values is the same parameter
+   * as in this constructor.
+   *
    * @param array $values
    *   An array of field properties, keyed by property name. Most array
    *   elements will be used to set the corresponding properties on the class;
@@ -232,10 +236,6 @@ class FieldStorageConfig extends ConfigEntityBase implements FieldStorageConfigI
    *   - entity_type: required.
    *   - type: required.
    *
-   * In most cases, Field entities are created via
-   * FieldStorageConfig::create($values)), where $values is the same
-   * parameter as in this constructor.
-   *
    * @see entity_create()
    */
   public function __construct(array $values, $entity_type = 'field_storage_config') {

core/modules/filter/tests/src/Kernel/FilterUnitTest.php

@@ -861,17 +861,15 @@ function testUrlFilter() {
    *   An associative array, whereas each key is an arbitrary input string and
    *   each value is again an associative array whose keys are filter output
    *   strings and whose values are Booleans indicating whether the output is
-   *   expected or not.
-   *
-   * For example:
-   * @code
-   * $tests = array(
-   *   'Input string' => array(
-   *     '<p>Input string</p>' => TRUE,
-   *     'Input string<br' => FALSE,
-   *   ),
-   * );
-   * @endcode
+   *   expected or not. For example:
+   *   @code
+   *   $tests = array(
+   *     'Input string' => array(
+   *       '<p>Input string</p>' => TRUE,
+   *       'Input string<br' => FALSE,
+   *     ),
+   *   );
+   *   @endcode
    */
   function assertFilteredString($filter, $tests) {
     foreach ($tests as $source => $tasks) {

core/modules/node/node.api.php

@@ -208,15 +208,15 @@ function hook_node_access_records(\Drupal\node\NodeInterface $node) {
  *
  * A module may deny all access to a node by setting $grants to an empty array.
  *
+ * The preferred use of this hook is in a module that bridges multiple node
+ * access modules with a configurable behavior, as shown in the example with the
+ * 'is_preview' field.
+ *
  * @param array $grants
  *   The $grants array returned by hook_node_access_records().
  * @param \Drupal\node\NodeInterface $node
  *   The node for which the grants were acquired.
  *
- * The preferred use of this hook is in a module that bridges multiple node
- * access modules with a configurable behavior, as shown in the example with the
- * 'is_preview' field.
- *
  * @see hook_node_access_records()
  * @see hook_node_grants()
  * @see hook_node_grants_alter()

core/modules/user/src/Tests/UserAdminLanguageTest.php

@@ -149,11 +149,11 @@ function testActualNegotiation() {
   /**
    * Sets the User interface negotiation detection method.
    *
-   * @param bool $admin_first
-   *   Whether the admin negotiation should be first.
-   *
    * Enables the "Account preference for administration pages" language
    * detection method for the User interface language negotiation type.
+   *
+   * @param bool $admin_first
+   *   Whether the admin negotiation should be first.
    */
   function setLanguageNegotiation($admin_first = FALSE) {
     $edit = array(

core/modules/user/user.module

@@ -447,12 +447,12 @@ function user_template_preprocess_default_variables_alter(&$variables) {
  *
  * Default template: username.html.twig.
  *
+ * Modules that make any changes to variables like 'name' or 'extra' must ensure
+ * that the final string is safe.
+ *
  * @param array $variables
  *   An associative array containing:
  *   - account: The user account (\Drupal\Core\Session\AccountInterface).
- *
- * Modules that make any changes to variables like 'name' or 'extra' must ensure
- * that the final string is safe.
  */
 function template_preprocess_username(&$variables) {
   $account = $variables['account'] ?: new AnonymousUserSession();

core/modules/views/src/Plugin/views/display/Block.php

@@ -320,7 +320,7 @@ public function blockValidate(ViewsBlock $block, array $form, FormStateInterface
    * @param \Drupal\Core\Form\FormStateInterface $form_state
    *   The current state of the form.
    *
-   * * @see \Drupal\views\Plugin\Block\ViewsBlock::blockSubmit()
+   * @see \Drupal\views\Plugin\Block\ViewsBlock::blockSubmit()
    */
   public function blockSubmit(ViewsBlock $block, $form, FormStateInterface $form_state) {
     if ($items_per_page = $form_state->getValue(array('override', 'items_per_page'))) {

core/modules/views/src/Plugin/views/query/Sql.php

@@ -789,6 +789,17 @@ public function clearFields() {
    * ensuring that all fields are fully qualified (TABLE.FIELD) and that
    * the table already exists in the query.
    *
+   * The $field, $value and $operator arguments can also be passed in with a
+   * single DatabaseCondition object, like this:
+   * @code
+   * $this->query->addWhere(
+   *   $this->options['group'],
+   *   db_or()
+   *     ->condition($field, $value, 'NOT IN')
+   *     ->condition($field, $value, 'IS NULL')
+   * );
+   * @endcode
+   *
    * @param $group
    *   The WHERE group to add these to; groups are used to create AND/OR
    *   sections. Groups cannot be nested. Use 0 as the default group.
@@ -804,17 +815,6 @@ public function clearFields() {
    *   complex options such as IN, LIKE, LIKE BINARY, or BETWEEN. Defaults to =.
    *   If $field is a string you have to use 'formula' here.
    *
-   * The $field, $value and $operator arguments can also be passed in with a
-   * single DatabaseCondition object, like this:
-   * @code
-   *   $this->query->addWhere(
-   *     $this->options['group'],
-   *     db_or()
-   *       ->condition($field, $value, 'NOT IN')
-   *       ->condition($field, $value, 'IS NULL')
-   *   );
-   * @endcode
-   *
    * @see \Drupal\Core\Database\Query\ConditionInterface::condition()
    * @see \Drupal\Core\Database\Query\Condition
    */

core/modules/views/tests/src/Kernel/ModuleTest.php

@@ -115,6 +115,8 @@ public function testViewsGetHandler() {
   /**
    * Defines an error handler which is used in the test.
    *
+   * Because this is registered in set_error_handler(), it has to be public.
+   *
    * @param int $error_level
    *   The level of the error raised.
    * @param string $message
@@ -127,7 +129,6 @@ public function testViewsGetHandler() {
    *   An array that points to the active symbol table at the point the error
    *   occurred.
    *
-   * Because this is registered in set_error_handler(), it has to be public.
    * @see set_error_handler()
    */
   public function customErrorHandler($error_level, $message, $filename, $line, $context) {

core/phpcs.xml.dist

@@ -18,6 +18,37 @@
   <rule ref="Drupal.CSS.ColourDefinition"/>
   <rule ref="Drupal.Commenting.DocCommentStar"/>
   <rule ref="Drupal.Commenting.FileComment"/>
+  <rule ref="Drupal.Commenting.FunctionComment">
+    <exclude name="Drupal.Commenting.FunctionComment.IncorrectParamVarName"/>
+    <exclude name="Drupal.Commenting.FunctionComment.IncorrectTypeHint"/>
+    <exclude name="Drupal.Commenting.FunctionComment.$InReturnType"/>
+    <exclude name="Drupal.Commenting.FunctionComment.InvalidNoReturn"/>
+    <exclude name="Drupal.Commenting.FunctionComment.InvalidReturn"/>
+    <exclude name="Drupal.Commenting.FunctionComment.InvalidReturnNotVoid"/>
+    <exclude name="Drupal.Commenting.FunctionComment.InvalidTypeHint"/>
+    <exclude name="Drupal.Commenting.FunctionComment.Missing"/>
+    <exclude name="Drupal.Commenting.FunctionComment.MissingFile"/>
+    <exclude name="Drupal.Commenting.FunctionComment.MissingParamComment"/>
+    <exclude name="Drupal.Commenting.FunctionComment.MissingParamName"/>
+    <exclude name="Drupal.Commenting.FunctionComment.MissingParamType"/>
+    <exclude name="Drupal.Commenting.FunctionComment.MissingReturnComment"/>
+    <exclude name="Drupal.Commenting.FunctionComment.MissingReturnType"/>
+    <exclude name="Drupal.Commenting.FunctionComment.ParamCommentFullStop"/>
+    <exclude name="Drupal.Commenting.FunctionComment.ParamCommentNewLine"/>
+    <exclude name="Drupal.Commenting.FunctionComment.ParamCommentNotCapital"/>
+    <exclude name="Drupal.Commenting.FunctionComment.ParamNameNoMatch"/>
+    <exclude name="Drupal.Commenting.FunctionComment.ReturnCommentIndentation"/>
+    <exclude name="Drupal.Commenting.FunctionComment.SeeAdditionalText"/>
+    <exclude name="Drupal.Commenting.FunctionComment.SeePunctuation"/>
+    <exclude name="Drupal.Commenting.FunctionComment.SpacingAfter"/>
+    <exclude name="Drupal.Commenting.FunctionComment.SpacingAfterParamType"/>
+    <exclude name="Drupal.Commenting.FunctionComment.ThrowsComment"/>
+    <exclude name="Drupal.Commenting.FunctionComment.ThrowsNoFullStop"/>
+    <exclude name="Drupal.Commenting.FunctionComment.ThrowsNotCapital"/>
+    <exclude name="Drupal.Commenting.FunctionComment.TypeHintMissing"/>
+    <exclude name="Drupal.Commenting.FunctionComment.VoidReturn"/>
+    <exclude name="Drupal.Commenting.FunctionComment.WrongStyle"/>
+  </rule>
   <rule ref="Drupal.ControlStructures.ElseIf"/>
   <rule ref="Drupal.Files.EndFileNewline"/>
   <rule ref="Drupal.Files.TxtFileLineLength"/>