From b13374f2b1f59ab2e7ac07e68c4dee141c82e2ab Mon Sep 17 00:00:00 2001 From: Alex Pott <alex.a.pott@googlemail.com> Date: Fri, 29 Apr 2016 09:53:52 +0100 Subject: [PATCH] Issue #2707641 by alexpott, anoopjohn: Ensure core compliance to Drupal.Commenting.FunctionComment.ParamCommentIndentation (part 2) --- core/includes/theme.inc | 18 +++++------ core/lib/Drupal/Core/Asset/CssOptimizer.php | 8 ++--- .../Drupal/Core/Config/StorableConfigBase.php | 4 +-- core/lib/Drupal/Core/Entity/entity.api.php | 16 ++++------ .../lib/Drupal/Core/Render/Element/Button.php | 7 ++--- core/lib/Drupal/Core/Render/Element/Date.php | 8 ++--- core/lib/Drupal/Core/Render/Element/Radio.php | 8 ++--- .../Core/Theme/ThemeManagerInterface.php | 4 +-- core/lib/Drupal/Core/Url.php | 14 ++++----- .../modules/book/src/BookManagerInterface.php | 6 ++-- .../field/src/Entity/FieldStorageConfig.php | 8 ++--- .../tests/src/Kernel/FilterUnitTest.php | 20 ++++++------ core/modules/node/node.api.php | 8 ++--- .../user/src/Tests/UserAdminLanguageTest.php | 6 ++-- core/modules/user/user.module | 6 ++-- .../views/src/Plugin/views/display/Block.php | 2 +- .../views/src/Plugin/views/query/Sql.php | 22 ++++++------- .../views/tests/src/Kernel/ModuleTest.php | 3 +- core/phpcs.xml.dist | 31 +++++++++++++++++++ 19 files changed, 109 insertions(+), 90 deletions(-) diff --git a/core/includes/theme.inc b/core/includes/theme.inc index 33b1769f462a..5a3442a844fb 100644 --- a/core/includes/theme.inc +++ b/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() diff --git a/core/lib/Drupal/Core/Asset/CssOptimizer.php b/core/lib/Drupal/Core/Asset/CssOptimizer.php index f47354403c86..2a316fa62352 100644 --- a/core/lib/Drupal/Core/Asset/CssOptimizer.php +++ b/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. */ diff --git a/core/lib/Drupal/Core/Config/StorableConfigBase.php b/core/lib/Drupal/Core/Config/StorableConfigBase.php index 80a0fb68cf90..ef856e0ecc3d 100644 --- a/core/lib/Drupal/Core/Config/StorableConfigBase.php +++ b/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() diff --git a/core/lib/Drupal/Core/Entity/entity.api.php b/core/lib/Drupal/Core/Entity/entity.api.php index ca1835eabd6e..ca8bef5a969f 100644 --- a/core/lib/Drupal/Core/Entity/entity.api.php +++ b/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() * diff --git a/core/lib/Drupal/Core/Render/Element/Button.php b/core/lib/Drupal/Core/Render/Element/Button.php index e75c55e0ff9c..c5b84f078d1e 100644 --- a/core/lib/Drupal/Core/Render/Element/Button.php +++ b/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. diff --git a/core/lib/Drupal/Core/Render/Element/Date.php b/core/lib/Drupal/Core/Render/Element/Date.php index e318a233fbaf..dcee06228ca5 100644 --- a/core/lib/Drupal/Core/Render/Element/Date.php +++ b/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'. diff --git a/core/lib/Drupal/Core/Render/Element/Radio.php b/core/lib/Drupal/Core/Render/Element/Radio.php index 58086fbbf0be..ae20284b9f78 100644 --- a/core/lib/Drupal/Core/Render/Element/Radio.php +++ b/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. diff --git a/core/lib/Drupal/Core/Theme/ThemeManagerInterface.php b/core/lib/Drupal/Core/Theme/ThemeManagerInterface.php index aba617a9dadd..2af80749c53c 100644 --- a/core/lib/Drupal/Core/Theme/ThemeManagerInterface.php +++ b/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 */ diff --git a/core/lib/Drupal/Core/Url.php b/core/lib/Drupal/Core/Url.php index 0f5b4e501b64..bf978bfc200a 100644 --- a/core/lib/Drupal/Core/Url.php +++ b/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. diff --git a/core/modules/book/src/BookManagerInterface.php b/core/modules/book/src/BookManagerInterface.php index 8f219427fd76..65acde5b6d9b 100644 --- a/core/modules/book/src/BookManagerInterface.php +++ b/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); diff --git a/core/modules/field/src/Entity/FieldStorageConfig.php b/core/modules/field/src/Entity/FieldStorageConfig.php index ba36e834873a..d04454ed38c4 100644 --- a/core/modules/field/src/Entity/FieldStorageConfig.php +++ b/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') { diff --git a/core/modules/filter/tests/src/Kernel/FilterUnitTest.php b/core/modules/filter/tests/src/Kernel/FilterUnitTest.php index c4744bbd571d..860f6723d5fd 100644 --- a/core/modules/filter/tests/src/Kernel/FilterUnitTest.php +++ b/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) { diff --git a/core/modules/node/node.api.php b/core/modules/node/node.api.php index 11689c3b62bb..e347423dca68 100644 --- a/core/modules/node/node.api.php +++ b/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() diff --git a/core/modules/user/src/Tests/UserAdminLanguageTest.php b/core/modules/user/src/Tests/UserAdminLanguageTest.php index 68ebfad279c2..03baa044e834 100644 --- a/core/modules/user/src/Tests/UserAdminLanguageTest.php +++ b/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( diff --git a/core/modules/user/user.module b/core/modules/user/user.module index 2fa279ac7cb7..dd8c05d2e285 100644 --- a/core/modules/user/user.module +++ b/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(); diff --git a/core/modules/views/src/Plugin/views/display/Block.php b/core/modules/views/src/Plugin/views/display/Block.php index 9ab56d801310..fe37d919f65f 100644 --- a/core/modules/views/src/Plugin/views/display/Block.php +++ b/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'))) { diff --git a/core/modules/views/src/Plugin/views/query/Sql.php b/core/modules/views/src/Plugin/views/query/Sql.php index d55ae5648ab9..54bb98157a51 100644 --- a/core/modules/views/src/Plugin/views/query/Sql.php +++ b/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 */ diff --git a/core/modules/views/tests/src/Kernel/ModuleTest.php b/core/modules/views/tests/src/Kernel/ModuleTest.php index 74159abd9e23..32c7198492a5 100644 --- a/core/modules/views/tests/src/Kernel/ModuleTest.php +++ b/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) { diff --git a/core/phpcs.xml.dist b/core/phpcs.xml.dist index c52b7c4142d2..ce06ebcdbf6b 100644 --- a/core/phpcs.xml.dist +++ b/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"/> -- GitLab