Fix 'Drupal.Commenting.DocComment.ShortNotCapital' coding standard

Partial work.

The patch contains a lot of modifications which are out of scope. Please remove them. At 17 I also pointed out another type of issue.

1. +++ b/core/tests/Drupal/Tests/Component/Datetime/DateTimePlusTest.php
   @@ -151,9 +151,9 @@ public function testTimestamp($input, array $initial, array $transform) {
       * @param string $input
       *   Input argument for DateTimePlus().
       * @param array $initial
   -   *   @see testTimestamp()
       * @param array $transform
   -   *   @see testTimestamp()
   +   *
   +   * @see testTimestamp()
   

   Out of scope.

2. +++ b/core/tests/Drupal/Tests/Component/Datetime/DateTimePlusTest.php
   @@ -164,17 +164,16 @@ public function testDateTimestamp($input, array $initial, array $transform) {
   -   * Assertion helper for testTimestamp and testDateTimestamp since they need
   -   * different dataProviders.
   +   * Assertion helper for testTimestamp and testDateTimestamp since they need different dataProviders.
       *
       * @param DateTimePlus $date
       *   DateTimePlus to test.
   -   * @input mixed $input
   +   * @param mixed $input
       *   The original input passed to the test method.
       * @param array $initial
   -   *   @see testTimestamp()
       * @param array $transform
   -   *   @see testTimestamp()
   +   *
   +   * @see testTimestamp()
       */
   

   Out of scope.

3. +++ b/core/tests/Drupal/Tests/Component/Datetime/DateTimePlusTest.php
   @@ -247,8 +246,7 @@ public function testInvalidDates($input, $timezone, $format, $message, $class) {
   -   * Tests that DrupalDateTime can detect the right timezone to use.
   -   * When specified or not.
   +   * Tests that DrupalDateTime can detect the right timezone to use. When specified or not.
   

   Out of scope.

4. +++ b/core/tests/Drupal/Tests/Component/Datetime/DateTimePlusTest.php
   @@ -268,8 +266,7 @@ public function testDateTimezone($input, $timezone, $expected_timezone, $message
   -   * Test that DrupalDateTime can detect the right timezone to use when
   -   * constructed from a datetime object.
   +   * Test that DrupalDateTime can detect the right timezone to use when constructed from a datetime object.
   

   Out of scope.

5. +++ b/core/tests/Drupal/Tests/Component/Utility/EnvironmentTest.php
   @@ -17,9 +17,6 @@ class EnvironmentTest extends TestCase {
   -   * @dataProvider providerTestCheckMemoryLimit
   -   * @covers ::checkMemoryLimit
   -   *
       * @param string $required
       *   The required memory argument for
       *   \Drupal\Component\Utility\Environment::checkMemoryLimit().
   @@ -29,6 +26,9 @@ class EnvironmentTest extends TestCase {
   
   @@ -29,6 +26,9 @@ class EnvironmentTest extends TestCase {
       * @param bool $expected
       *   The expected return value from
       *   \Drupal\Component\Utility\Environment::checkMemoryLimit().
   +   *
   +   * @dataProvider providerTestCheckMemoryLimit
   +   * @covers ::checkMemoryLimit
       */
   

   Out of scope.

6. +++ b/core/tests/Drupal/Tests/Component/Utility/VariableTest.php
   @@ -64,17 +64,17 @@ public function providerTestExport() {
   -        // 2 backslashes. \\
   +        // 2 backslashes \\.
            "'\\'",
            '\\',
          ],
          [
   -        // Double-quote "
   +        // Double-quote ".
            "'\"'",
            "\"",
          ],
          [
   -        // Single-quote '
   +        // Single-quote '.
   

   Out of scope.

7. +++ b/core/tests/Drupal/Tests/Component/Utility/VariableTest.php
   @@ -100,13 +100,13 @@ public function providerTestExport() {
   -   * @dataProvider providerTestExport
   -   * @covers ::export
   -   *
       * @param string $expected
       *   The expected exported variable.
       * @param mixed $variable
       *   The variable to be exported.
   +   *
   +   * @dataProvider providerTestExport
   +   * @covers ::export
       */
   

   Out of scope.

8. +++ b/core/tests/Drupal/Tests/Core/Access/AccessResultTest.php
   @@ -884,16 +884,15 @@ public function testOrIfCacheabilityMerging() {
   -   * @covers ::allowedIfHasPermissions
   -   *
   -   * @dataProvider providerTestAllowedIfHasPermissions
   -   *
       * @param string[] $permissions
       *   The permissions to check for.
       * @param string $conjunction
       *   The conjunction to use when checking for permission. 'AND' or 'OR'.
       * @param \Drupal\Core\Access\AccessResult $expected_access
       *   The expected access check result.
   +   *
   +   * @dataProvider providerTestAllowedIfHasPermissions
   +   * @covers ::allowedIfHasPermissions
   

   Out of scope.

9. +++ b/core/tests/Drupal/Tests/Core/Common/AttributesTest.php
   @@ -57,7 +57,7 @@ public function testDrupalAttributes($attributes, $expected, $message) {
   -   * Test attribute iteration
   +   * Test attribute iteration.
   

   Out of scope.

10. +++ b/core/tests/Drupal/Tests/Core/Config/CachedStorageTest.php
    @@ -14,6 +14,8 @@
    +   * The cache factory.
    +   *
        * @var \Drupal\Core\Cache\CacheFactoryInterface|\PHPUnit_Framework_MockObject_MockObject
    

    Out of scope.

11. +++ b/core/tests/Drupal/Tests/Core/Config/Entity/ConfigEntityTypeTest.php
    @@ -30,8 +30,7 @@ protected function setUpConfigEntityType($definition) {
    -   * Tests that we get an exception when the length of the config prefix that is
    -   * returned by getConfigPrefix() exceeds the maximum defined prefix length.
    +   * Tests that we get an exception when the length of the config prefix that is returned by getConfigPrefix() exceeds the maximum defined prefix length.
    
    @@ -51,8 +50,7 @@ public function testConfigPrefixLengthExceeds() {
    -   * Tests that a valid config prefix returned by getConfigPrefix()
    -   * does not throw an exception and is formatted as expected.
    +   * Tests that a valid config prefix returned by getConfigPrefix() does not throw an exception and is formatted as expected.
    

    Out of scope.

12. +++ b/core/tests/Drupal/Tests/Core/DrupalKernel/DrupalKernelTest.php
    @@ -197,7 +197,7 @@ public function testFindSitePath() {
    -   * A fake autoloader for testing
    +   * A fake autoloader for testing.
    
    +++ b/core/tests/Drupal/Tests/Core/Extension/ModuleHandlerTest.php
    @@ -152,7 +152,7 @@ public function testGetModuleList() {
    -   * Confirm we get back a module from the module list
    +   * Confirm we get back a module from the module list.
    

    Out of scope.

13. +++ b/core/tests/Drupal/Tests/Core/Language/LanguageUnitTest.php
    @@ -83,14 +83,13 @@ public function testIsDefault() {
    -   * @covers ::sort
    -   *
    -   * @dataProvider providerTestSortArrayOfLanguages
    -   *
        * @param \Drupal\Core\Language\LanguageInterface[] $languages
        *   An array of language objects.
        * @param array $expected
        *   The expected array of keys.
    +   *
    +   * @dataProvider providerTestSortArrayOfLanguages
    +   * @covers ::sort
    

    Out of scope.

14. +++ b/core/tests/Drupal/Tests/Core/ParamConverter/EntityConverterTest.php
    @@ -95,7 +95,7 @@ public function testConvert($value, array $definition, array $defaults, $expecte
    -   * Provides test data for testConvert
    +   * Provides test data for testConvert.
    

    Out of scope.

15. +++ b/core/tests/Drupal/Tests/Core/Path/PathValidatorTest.php
    @@ -26,6 +26,7 @@ class PathValidatorTest extends UnitTestCase {
    +   *
    

    Out of scope.

16. +++ b/core/tests/Drupal/Tests/Core/Render/BubbleableMetadataTest.php
    @@ -396,7 +396,7 @@ public function testMergeAttachmentsFeedMerging($a, $b, $expected) {
    -   * Data provider for testMergeAttachmentsFeedMerging
    +   * Data provider for testMergeAttachmentsFeedMerging.
    
    @@ -455,7 +455,7 @@ public function testMergeAttachmentsHtmlHeadMerging($a, $b, $expected) {
    -   * Data provider for testMergeAttachmentsHtmlHeadMerging
    +   * Data provider for testMergeAttachmentsHtmlHeadMerging.
    
    @@ -528,7 +528,7 @@ public function testMergeAttachmentsHtmlHeadLinkMerging($a, $b, $expected) {
    -   * Data provider for testMergeAttachmentsHtmlHeadLinkMerging
    +   * Data provider for testMergeAttachmentsHtmlHeadLinkMerging.
    
    @@ -594,7 +594,7 @@ public function testMergeAttachmentsHttpHeaderMerging($a, $b, $expected) {
    -   * Data provider for testMergeAttachmentsHttpHeaderMerging
    +   * Data provider for testMergeAttachmentsHttpHeaderMerging.
    

    Out of scope.

17. +++ b/core/tests/Drupal/Tests/Core/Render/RendererRecursionTest.php
    @@ -26,7 +26,7 @@ protected function setUpRenderRecursionComplexElements() {
    -   * ::renderRoot() may not be called inside of another ::renderRoot() call.
    +   * The method ::renderRoot() may not be called inside of another ::renderRoot() call.
    

    Let's try to not add new issues.

18. +++ b/core/tests/Drupal/Tests/Core/Routing/RouteMatchTestBase.php
    @@ -22,6 +22,7 @@
    +   *
        * @return \Drupal\Core\Routing\RouteMatchInterface
    

    Out of scope.

19. +++ b/core/tests/Drupal/Tests/Core/Routing/UrlGeneratorTest.php
    @@ -175,8 +175,7 @@ protected function setUp() {
    -   * Return value callback for the getAliasByPath() method on the mock alias
    -   * manager.
    +   * Return value callback for the getAliasByPath() method on the mock alias manager.
    

    Out of scope.

20. +++ b/core/tests/Drupal/Tests/Core/Routing/UrlGeneratorTest.php
    @@ -429,7 +428,7 @@ public function testAbsoluteURLGenerationUsingInterfaceConstants() {
    -   * Confirms that explicitly setting the base_url works with generated routes
    +   * Confirms that explicitly setting the base_url works with generated routes.
    

    Out of scope.

21. +++ b/core/tests/Drupal/Tests/Core/Site/SettingsTest.php
    @@ -66,7 +66,7 @@ public function testGetInstance() {
    -   * Tests Settings::getHashSalt();
    +   * Tests Settings::getHashSalt().
        *
    

    Out of scope.

22. +++ b/core/tests/Drupal/Tests/Core/StackMiddleware/NegotiationMiddlewareTest.php
    @@ -20,6 +20,8 @@
    +   * The app kernel.
    +   *
    
    +++ b/core/tests/Drupal/Tests/Core/StringTranslation/TranslationManagerTest.php
    @@ -33,6 +33,7 @@ protected function setUp() {
    +   *
    
    +++ b/core/tests/Drupal/Tests/Core/Template/AttributeTest.php
    @@ -74,6 +74,7 @@ public function testRemove() {
    +   *
    
    @@ -102,6 +103,7 @@ public function testSetAttribute() {
    +   *
    
    @@ -141,6 +143,7 @@ public function testRemoveAttribute() {
    +   *
    
    @@ -193,6 +196,7 @@ public function testAddClasses() {
    +   *
    
    @@ -224,6 +228,7 @@ public function testRemoveClasses() {
    +   *
    
    @@ -239,6 +244,7 @@ public function testHasClass() {
    +   *
    
    @@ -257,6 +263,7 @@ public function testChainAddRemoveClasses() {
    +   *
    

    Out of scope.

23. +++ b/core/tests/Drupal/Tests/Core/Template/AttributeTest.php
    @@ -273,7 +280,7 @@ public function testTwigAddRemoveClasses($template, $expected, $seed_attributes
    -   * Provides tests data for testEscaping
    +   * Provides tests data for testEscaping.
    
    +++ b/core/tests/Drupal/Tests/Core/Template/TwigExtensionTest.php
    @@ -71,7 +71,7 @@ public function setUp() {
    -   * Tests the escaping
    +   * Tests the escaping.
    
    @@ -94,7 +94,7 @@ public function testEscaping($template, $expected) {
    -   * Provides tests data for testEscaping
    +   * Provides tests data for testEscaping.
    

    Out of scope.

24. +++ b/core/tests/Drupal/Tests/Core/Theme/AjaxBasePageNegotiatorTest.php
    @@ -17,23 +17,23 @@
    -   * @var \Drupal\Core\Theme\AjaxBasePageNegotiator
    -   *
        * The AJAX base page negotiator.
    +   *
    +   * @var \Drupal\Core\Theme\AjaxBasePageNegotiator
    ...
    -   * @var \Drupal\Core\Access\CsrfTokenGenerator|\Prophecy\Prophecy\ProphecyInterface
    -   *
        * The CSRF token generator.
    +   *
    +   * @var \Drupal\Core\Access\CsrfTokenGenerator|\Prophecy\Prophecy\ProphecyInterface
    ...
    -   * @var \Symfony\Component\HttpFoundation\RequestStack
    -   *
        * The request stack.
    +   *
    +   * @var \Symfony\Component\HttpFoundation\RequestStack
    

    Out of scope.

25. +++ b/core/tests/Drupal/Tests/Core/TypedData/RecursiveContextualValidatorTest.php
    @@ -251,6 +251,7 @@ public function testValidatePropertyWithInvalidObjects($object) {
    +   *
    
    +++ b/core/tests/Drupal/Tests/Core/UnroutedUrlTest.php
    @@ -15,7 +15,7 @@
    -   * The URL assembler
    +   * The URL assembler.
    
    +++ b/core/tests/Drupal/Tests/EntityViewTrait.php
    @@ -30,6 +30,7 @@
    +   *
    

    Out of scope.

Looks better!

+++ b/core/tests/Drupal/Tests/Core/Render/RendererRecursionTest.php
@@ -26,7 +26,8 @@ protected function setUpRenderRecursionComplexElements() {
-   * ::renderRoot() may not be called inside of another ::renderRoot() call.
+   * The method ::renderRoot() may not be called inside of another
+   * ::renderRoot() call.

Can we put this on one line?

I would just remove (optional) as it's not part of Coding standards and is not used consistently even in the classes where it is present.

@borisson_'s #5 note from his last comment still needs to be addressed.

Other than that all issues mentioned by @borisson_ are solved and there aren't any new. Looks good to me!

+++ b/core/phpcs.xml.dist
@@ -38,7 +38,6 @@
-    <exclude name="Drupal.Commenting.DocComment.ShortNotCapital"/>
     <exclude name="Drupal.Commenting.DocComment.ShortFullStop"/>

We should add ShortNotCapital in the comment from above that statement. Please make sure it's in alpha order. Sorry for not pointing this earlier.

Other than that the patch looks fine and includes the other mentioned changes. Still applies cleanly and no cs issues.

Indeed! Just add it there then. :)

Great! RTBC then!

The failing test doesn't relate to modifications in this patch.
I guess it's related to this #2924201: Resolve random failure in LayoutBuilderTest so that it can be added to HEAD. Back to RTBC!

Regarding "(optional)" I added #2925237: ShortNotCapital triggered by non-letters.
Regarding "{@inheritdoc}" we already have #2904801: @inheritdoc without { } is treated as a tag and gives missleading message. The problem is widespread.