Issue #2721909 by anoopjohn: Fix Drupal.Commenting.FunctionComment.ReturnCommentIndentation

core/includes/install.core.inc

@@ -1084,7 +1084,7 @@ function install_verify_completed_task() {
  *   The site path.
  *
  * @return bool
- *  TRUE if there are no database errors.
+ *   TRUE if there are no database errors.
  */
 function install_verify_database_settings($site_path) {
   if ($database = Database::getConnectionInfo()) {

core/includes/install.inc

@@ -115,8 +115,8 @@ function drupal_install_profile_distribution_name() {
  * Loads the installation profile, extracting its defined version.
  *
  * @return string Distribution version defined in the profile's .info.yml file.
- * Defaults to \Drupal::VERSION if no version is explicitly provided
- * by the installation profile.
+ *   Defaults to \Drupal::VERSION if no version is explicitly provided
+ *   by the installation profile.
  *
  * @see install_profile_info()
  */
@@ -139,7 +139,7 @@ function drupal_install_profile_distribution_version() {
  * Detects all supported databases that are compiled into PHP.
  *
  * @return
- *  An array of database types compiled into PHP.
+ *   An array of database types compiled into PHP.
  */
 function drupal_detect_database_types() {
   $databases = drupal_get_database_types();
@@ -724,7 +724,7 @@ function drupal_verify_install_file($file, $mask = NULL, $type = 'file') {
  *   (optional) Whether to output messages. Defaults to TRUE.
  *
  * @return
- *  TRUE/FALSE whether or not the directory was successfully created.
+ *   TRUE/FALSE whether or not the directory was successfully created.
  */
 function drupal_install_mkdir($file, $mask, $message = TRUE) {
   $mod = 0;
@@ -773,7 +773,7 @@ function drupal_install_mkdir($file, $mask, $message = TRUE) {
  *   (optional) Whether to output messages. Defaults to TRUE.
  *
  * @return
- *  TRUE/FALSE whether or not we were able to fix the file's permissions.
+ *   TRUE/FALSE whether or not we were able to fix the file's permissions.
  */
 function drupal_install_fix_file($file, $mask, $message = TRUE) {
   // If $file does not exist, fileperms() issues a PHP warning.

core/includes/update.inc

@@ -65,7 +65,7 @@ function update_check_incompatibility($name, $type = 'module') {
  * Returns whether the minimum schema requirement has been satisfied.
  *
  * @return array
- *  A requirements info array.
+ *   A requirements info array.
  */
 function update_system_schema_requirements() {
   $requirements = array();

core/lib/Drupal/Component/Annotation/Plugin.php

@@ -49,7 +49,7 @@ public function __construct($values) {
    *   The annotation array.
    *
    * @return array
-   *  The parsed annotation as a definition.
+   *   The parsed annotation as a definition.
    */
   protected function parse(array $values) {
     $definitions = array();

core/lib/Drupal/Core/Cache/Cache.php

@@ -149,7 +149,7 @@ public static function invalidateTags(array $tags) {
    * Gets all cache bin services.
    *
    * @return array
-   *  An array of cache backend objects keyed by cache bins.
+   *   An array of cache backend objects keyed by cache bins.
    */
   public static function getBins() {
     $bins = array();

core/lib/Drupal/Core/Cache/CacheableDependencyInterface.php

@@ -37,7 +37,7 @@ public function getCacheContexts();
    * When this object is modified, these cache tags will be invalidated.
    *
    * @return string[]
-   *  A set of cache tags.
+   *   A set of cache tags.
    */
   public function getCacheTags();
 

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

@@ -93,28 +93,28 @@ public function rename($name, $new_name);
   /**
    * Encodes configuration data into the storage-specific format.
    *
+   * This is a publicly accessible static method to allow for alternative
+   * usages in data conversion scripts and also tests.
+   *
    * @param array $data
    *   The configuration data to encode.
    *
    * @return string
    *   The encoded configuration data.
-   *
-   * This is a publicly accessible static method to allow for alternative
-   * usages in data conversion scripts and also tests.
    */
   public function encode($data);
 
   /**
    * Decodes configuration data from the storage-specific format.
    *
+   * This is a publicly accessible static method to allow for alternative
+   * usages in data conversion scripts and also tests.
+   *
    * @param string $raw
    *   The raw configuration data string to decode.
    *
    * @return array
    *   The decoded configuration data as an associative array.
-   *
-   * This is a publicly accessible static method to allow for alternative
-   * usages in data conversion scripts and also tests.
    */
   public function decode($raw);
 

core/lib/Drupal/Core/Extension/module.api.php

@@ -72,6 +72,8 @@
  * frequently called should be left in the main module file so that they are
  * always available.
  *
+ * See system_hook_info() for all hook groups defined by Drupal core.
+ *
  * @return
  *   An associative array whose keys are hook names and whose values are an
  *   associative array containing:
@@ -79,8 +81,6 @@
  *     system will determine whether a file with the name $module.$group.inc
  *     exists, and automatically load it when required.
  *
- * See system_hook_info() for all hook groups defined by Drupal core.
- *
  * @see hook_hook_info_alter()
  */
 function hook_hook_info() {

core/lib/Drupal/Core/Plugin/ContextAwarePluginBase.php

@@ -41,11 +41,11 @@ protected function createContextFromConfiguration(array $context_configuration)
   /**
    * {@inheritdoc}
    *
-   * @return \Drupal\Core\Plugin\Context\ContextInterface
-   *   The context object.
-   *
    * This code is identical to the Component in order to pick up a different
    * Context class.
+   *
+   * @return \Drupal\Core\Plugin\Context\ContextInterface
+   *   The context object.
    */
   public function getContext($name) {
     // Check for a valid context value.

core/lib/Drupal/Core/Render/RenderCacheInterface.php

@@ -64,7 +64,7 @@ public function get(array $elements);
    *   this array.
    *
    * @return bool|null
-   *  Returns FALSE if no cache item could be created, NULL otherwise.
+   *   Returns FALSE if no cache item could be created, NULL otherwise.
    *
    * @see ::get()
    */

core/lib/Drupal/Core/Routing/UrlGenerator.php

@@ -253,7 +253,7 @@ protected function doGenerate(array $variables, array $defaults, array $tokens,
    *   $parameters merged in.
    *
    * @return string
-   *  The url path corresponding to the route, without the base path.
+   *   The url path corresponding to the route, without the base path.
    */
   protected function getInternalPathFromRoute($name, SymfonyRoute $route, $parameters = array(), $query_params = array()) {
     // The Route has a cache of its own and is not recompiled as long as it does

core/lib/Drupal/Core/Routing/UrlGeneratorInterface.php

@@ -21,7 +21,7 @@ interface UrlGeneratorInterface extends VersatileGeneratorInterface {
    *   \Symfony\Component\Routing\Generator\UrlGeneratorInterface::generate().
    *
    * @return string
-   *  The internal Drupal path corresponding to the route.
+   *   The internal Drupal path corresponding to the route.
    */
   public function getPathFromRoute($name, $parameters = array());
 

core/lib/Drupal/Core/StringTranslation/Translator/FileTranslation.php

@@ -82,7 +82,7 @@ public function findTranslationFiles($langcode = NULL) {
    *   want to find translation files.
    *
    * @return string
-   *  String file pattern.
+   *   String file pattern.
    */
   protected function getTranslationFilesPattern($langcode = NULL) {
     // The file name matches: drupal-[release version].[language code].po

core/modules/book/src/BookManagerInterface.php

@@ -18,6 +18,8 @@ interface BookManagerInterface {
    * Since this can be the full tree including hidden items, the data returned
    * may be used for generating an an admin interface or a select.
    *
+   * Note: based on menu_tree_all_data().
+   *
    * @param int $bid
    *   The Book ID to find links for.
    * @param array|null $link
@@ -31,8 +33,6 @@ interface BookManagerInterface {
    *
    * @return array
    *   An tree of menu links in an array, in the order they should be rendered.
-   *
-   * Note: based on menu_tree_all_data().
    */
   public function bookTreeAllData($bid, $link = NULL, $max_depth = NULL);
 

core/modules/contact/src/ContactFormInterface.php

@@ -21,7 +21,7 @@ public function getRecipients();
    * Returns an auto-reply message to send to the message author.
    *
    * @return string
-   *  An auto-reply message
+   *   An auto-reply message
    */
   public function getReply();
 

core/modules/content_translation/src/Controller/ContentTranslationController.php

@@ -77,8 +77,8 @@ public function prepareTranslation(ContentEntityInterface $entity, LanguageInter
    *   The route match.
    * @param string $entity_type_id
    *   (optional) The entity type ID.
-   * @return array Array of page elements to render.
-   * Array of page elements to render.
+   * @return array
+   *   Array of page elements to render.
    */
   public function overview(RouteMatchInterface $route_match, $entity_type_id = NULL) {
     /** @var \Drupal\Core\Entity\ContentEntityInterface $entity */

core/modules/field/src/Tests/FieldTestBase.php

@@ -17,7 +17,7 @@ abstract class FieldTestBase extends WebTestBase {
    * @param $cardinality
    *   Number of values to generate.
    * @return
-   *  An array of random values, in the format expected for field values.
+   *   An array of random values, in the format expected for field values.
    */
   function _generateTestFieldValues($cardinality) {
     $values = array();

core/modules/field/tests/src/Kernel/FieldKernelTestBase.php

@@ -158,7 +158,7 @@ protected function entityValidateAndSave(EntityInterface $entity) {
    * @param $cardinality
    *   Number of values to generate.
    * @return
-   *  An array of random values, in the format expected for field values.
+   *   An array of random values, in the format expected for field values.
    */
   protected function _generateTestFieldValues($cardinality) {
     $values = array();

core/modules/file/src/Plugin/migrate/destination/EntityFile.php

@@ -147,7 +147,7 @@ public function import(Row $row, array $old_destination_id_values = array()) {
    *   (optional) FILE_EXISTS_REPLACE (default) or FILE_EXISTS_RENAME.
    *
    * @return bool
-   *  TRUE on success, FALSE on failure.
+   *   TRUE on success, FALSE on failure.
    */
   protected function writeFile($source, $destination, $replace = FILE_EXISTS_REPLACE) {
     if ($this->configuration['move']) {
@@ -190,8 +190,8 @@ protected function getOverwriteMode(Row $row) {
    *   The URI or path.
    *
    * @return string|false
-   *  The directory component of the path or URI, or FALSE if it could not
-   *  be determined.
+   *   The directory component of the path or URI, or FALSE if it could not
+   *   be determined.
    */
   protected function getDirectory($uri) {
     $dir = $this->fileSystem->dirname($uri);
@@ -213,8 +213,8 @@ protected function getDirectory($uri) {
    *   The destination URI.
    *
    * @return bool
-   *  TRUE if the source and destination URIs refer to the same physical path,
-   *  otherwise FALSE.
+   *   TRUE if the source and destination URIs refer to the same physical path,
+   *   otherwise FALSE.
    */
   protected function isLocationUnchanged($source, $destination) {
     if ($this->isLocalUri($source) && $this->isLocalUri($destination)) {

core/modules/file/src/Tests/FileListingTest.php

@@ -148,7 +148,7 @@ function testFileListingPages() {
    * Creates and saves a test file.
    *
    * @return \Drupal\Core\Entity\EntityInterface
-   *  A file entity.
+   *   A file entity.
    */
   protected function createFile() {
     // Create a new file entity.

core/modules/language/src/DefaultLanguageItem.php

@@ -40,7 +40,7 @@ public function applyDefaultValue($notify = TRUE) {
    *   The entity whose language code to be loaded.
    *
    * @return string
-   *  A string language code.
+   *   A string language code.
    */
   public function getDefaultLangcode(EntityInterface $entity) {
     return language_get_default_langcode($entity->getEntityTypeId(), $entity->bundle());

core/modules/node/node.api.php

@@ -64,6 +64,8 @@
  * sure to restore your {node_access} record after node_access_rebuild() is
  * called.
  *
+ * For a detailed example, see node_access_example.module.
+ *
  * @param \Drupal\Core\Session\AccountInterface $account
  *   The account object whose grants are requested.
  * @param string $op
@@ -73,8 +75,6 @@
  *   An array whose keys are "realms" of grants, and whose values are arrays of
  *   the grant IDs within this realm that this user is being granted.
  *
- * For a detailed example, see node_access_example.module.
- *
  * @see node_access_view_all_nodes()
  * @see node_access_rebuild()
  * @ingroup node_access

core/modules/search/src/SearchPageInterface.php

@@ -45,7 +45,7 @@ public function isIndexable();
    * Returns the path for the search.
    *
    * @return string
-   *  The part of the path for this search page that comes after 'search'.
+   *   The part of the path for this search page that comes after 'search'.
    */
   public function getPath();
 

core/modules/simpletest/simpletest.module

@@ -259,7 +259,7 @@ function simpletest_phpunit_configuration_filepath() {
  *   this variable.
  *
  * @return string
- *  The results as returned by exec().
+ *   The results as returned by exec().
  */
 function simpletest_phpunit_run_command(array $unescaped_test_classnames, $phpunit_file, &$status = NULL) {
   // Setup an environment variable containing the database connection so that

core/modules/simpletest/src/Form/SimpletestResultsForm.php

@@ -214,7 +214,7 @@ public function submitForm(array &$form, FormStateInterface $form_state) {
    *   The test_id to retrieve results of.
    *
    * @return array
-   *  Array of results grouped by test_class.
+   *   Array of results grouped by test_class.
    */
   protected function getResults($test_id) {
     return $this->database->select('simpletest')

core/modules/system/src/Controller/AdminController.php

@@ -13,7 +13,7 @@ class AdminController extends ControllerBase {
    * Prints a listing of admin tasks, organized by module.
    *
    * @return array
-   *  A render array containing the listing.
+   *   A render array containing the listing.
    */
   public function index() {
     $module_info = system_get_info('module');

core/modules/system/src/Plugin/views/field/BulkForm.php

@@ -394,7 +394,7 @@ public function viewsFormSubmit(&$form, FormStateInterface $form_state) {
    * Returns the message to be displayed when there are no selected items.
    *
    * @return string
-   *  Message displayed when no items are selected.
+   *   Message displayed when no items are selected.
    */
   protected function emptySelectedMessage() {
     return $this->t('No items selected.');

core/modules/system/src/Tests/Entity/EntityCacheTagsTestBase.php

@@ -229,7 +229,7 @@ protected function selectViewMode($entity_type) {
    *   The entity that the referencing entity should reference.
    *
    * @return \Drupal\Core\Entity\EntityInterface[]
-   *  An array containing a referencing entity and a non-referencing entity.
+   *   An array containing a referencing entity and a non-referencing entity.
    */
   protected function createReferenceTestEntities($referenced_entity) {
     // All referencing entities should be of the type 'entity_test'.

core/modules/taxonomy/taxonomy.module

@@ -377,7 +377,7 @@ function taxonomy_term_load_multiple(array $tids = NULL) {
  *   (optional) An array of entity IDs. If omitted, all entities are loaded.
  *
  * @return array
- *  An array of vocabulary objects, indexed by vid.
+ *   An array of vocabulary objects, indexed by vid.
  */
 function taxonomy_vocabulary_load_multiple(array $vids = NULL) {
   return Vocabulary::loadMultiple($vids);

core/modules/toolbar/src/Element/Toolbar.php

@@ -59,7 +59,7 @@ public function getInfo() {
    *   A renderable array.
    *
    * @return array
-   *  A renderable array.
+   *   A renderable array.
    *
    * @see toolbar_page_top()
    */

core/modules/user/src/SharedTempStore.php

@@ -163,7 +163,7 @@ public function setIfNotExists($key, $value) {
    *
    * @return bool
    *   TRUE if the data was set, or FALSE if it already exists and is not owned
-   * by $this->user.
+   *   by $this->user.
    */
   public function setIfOwner($key, $value) {
     if ($this->setIfNotExists($key, $value)) {

core/modules/views/src/Controller/ViewAjaxController.php

@@ -104,7 +104,7 @@ public static function create(ContainerInterface $container) {
    *   The current request object.
    *
    * @return \Drupal\views\Ajax\ViewAjaxResponse
-   *  The view response as ajax response.
+   *   The view response as ajax response.
    *
    * @throws \Symfony\Component\HttpKernel\Exception\NotFoundHttpException
    *   Thrown when the view was not found.

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

@@ -568,7 +568,7 @@ public function getSpecialBlocks();
    * Renders the exposed form as block.
    *
    * @return string|null
-   *  The rendered exposed form as string or NULL otherwise.
+   *   The rendered exposed form as string or NULL otherwise.
    */
   public function viewExposedFormBlocks();
 

core/modules/views/src/Plugin/views/field/FieldHandlerInterface.php

@@ -140,7 +140,7 @@ public function getValue(ResultRow $values, $field = NULL);
    * by in the style settings.
    *
    * @return bool
-   *  TRUE if this field handler is groupable, otherwise FALSE.
+   *   TRUE if this field handler is groupable, otherwise FALSE.
    */
   public function useStringGroupBy();
 
@@ -215,7 +215,7 @@ public function advancedRender(ResultRow $values);
    *   Whether or not to use empty() to check the value.
    *
    * @return bool
-   * TRUE if the value is considered empty, FALSE otherwise.
+   *   TRUE if the value is considered empty, FALSE otherwise.
    */
   public function isValueEmpty($value, $empty_zero, $no_skip_empty = TRUE);
 

core/modules/views/src/Tests/Plugin/NumericFormatPluralTest.php

@@ -136,7 +136,7 @@ function testNumericFormatPlural() {
    * Creates and saves a test file.
    *
    * @return \Drupal\Core\Entity\EntityInterface
-   *  A file entity.
+   *   A file entity.
    */
   protected function createFile() {
     // Create a new file entity.

core/modules/views/src/ViewExecutable.php

@@ -2376,7 +2376,7 @@ public function setShowAdminLinks($show_admin_links) {
    * Returns whether admin links should be rendered on the view.
    *
    * @return bool
-   *  TRUE if admin links should be rendered, else FALSE.
+   *   TRUE if admin links should be rendered, else FALSE.
    */
   public function getShowAdminLinks() {
     if (!isset($this->showAdminLinks)) {

core/modules/views/src/Views.php

@@ -295,8 +295,8 @@ public static function getDisabledViews() {
    *   If TRUE, the list of views is sorted ascending.
    *
    * @return array
-   *  an associative array for use in select.
-   *  - key: view name and display id separated by ':', or the view name only
+   *   An associative array for use in select.
+   *   - key: view name and display id separated by ':', or the view name only.
    */
   public static function getViewsAsOptions($views_only = FALSE, $filter = 'all', $exclude_view = NULL, $optgroup = FALSE, $sort = FALSE) {
 

core/phpcs.xml.dist

@@ -59,7 +59,6 @@
     <exclude name="Drupal.Commenting.FunctionComment.ParamCommentFullStop"/>
     <exclude name="Drupal.Commenting.FunctionComment.ParamCommentNotCapital"/>
     <exclude name="Drupal.Commenting.FunctionComment.ParamNameNoMatch"/>
-    <exclude name="Drupal.Commenting.FunctionComment.ReturnCommentIndentation"/>
     <exclude name="Drupal.Commenting.FunctionComment.TypeHintMissing"/>
     <exclude name="Drupal.Commenting.FunctionComment.VoidReturn"/>
   </rule>

core/tests/Drupal/KernelTests/Core/Entity/EntityAutocompleteTest.php

@@ -146,7 +146,7 @@ public function testSelectionSettingsHandling() {
    *   The label of the entity to query by.
    *
    * @return mixed
-   *  The JSON value encoded in its appropriate PHP type.
+   *   The JSON value encoded in its appropriate PHP type.
    */
   protected function getAutocompleteResult($input) {
     $request = Request::create('entity_reference_autocomplete/' . $this->entityType . '/default');

core/tests/Drupal/Tests/Component/Utility/ImageTest.php

@@ -35,11 +35,10 @@ public function testScaleDimensions($input, $output) {
    *
    * @return array
    *   Keyed array containing:
-   * - 'input' - Array which contains input for
-   *   Image::scaleDimensions().
-   * - 'output' - Array which contains expected output after passing
-   *   through Image::scaleDimensions. Also contains a boolean
-   *   'return_value' which should match the expected return value.
+   *   - 'input' - Array which contains input for Image::scaleDimensions().
+   *   - 'output' - Array which contains expected output after passing
+   *     through Image::scaleDimensions. Also contains a boolean
+   *     'return_value' which should match the expected return value.
    *
    * @see testScaleDimensions()
    */

core/tests/Drupal/Tests/Component/Utility/UnicodeTest.php

@@ -474,11 +474,11 @@ public function testValidateUtf8($text, $expected, $message) {
   /**
    * Provides data for self::testValidateUtf8().
    *
+   * Invalid UTF-8 examples sourced from http://stackoverflow.com/a/11709412/109119.
+   *
    * @return array
    *   An array of arrays, each containing the parameters for
    *   self::testValidateUtf8().
-   *
-   * Invalid UTF-8 examples sourced from http://stackoverflow.com/a/11709412/109119.
    */
   public function providerTestValidateUtf8() {
     return array(

core/tests/Drupal/Tests/Component/Uuid/UuidTest.php

@@ -77,7 +77,7 @@ public function testValidation($uuid, $is_valid, $message) {
    * Dataprovider for UUID instance tests.
    *
    * @return array
-   *  An array of arrays containing
+   *   An array of arrays containing
    *   - The Uuid to check against.
    *   - (bool) Whether or not the Uuid is valid.
    *   - Failure message.