[PP-1] @see tags don't use fully qualified class/interface names

Hi @kiamlaluno,

Here by i attached the patch. Please let me know for changes.

Thanks & Regards,
Gnanagowthaman sankar

Patch

Thanks & Regards,
Gnanagowthaman sankar

Patch tested and applies cleanly.

git apply -v see_tags_dont_use_fully_qualified_class_interface_names-3102478-2.patch
Checking patch core/lib/Drupal/Core/Database/database.api.php...
Applied patch core/lib/Drupal/Core/Database/database.api.php cleanly.

Follow a new patch , and @kiamlaluno can you help us here to understand what do you mean by "The patch should also change all the content of the file, not just two comments." so we can help out more easily.

Thankyou

+1 RTBC.

The failing test isn't related to #6 patch. So changing status.

Kindly review a new patch which is collaborate with #3103803 : @see tags don't use fully qualified class/interface names

Hi I have reviewed #16. Failed to apply patch for test file changes.

/core/modules/system/src/Tests/System/SystemConfigFormTestBase.php

oh ok Thanks @kiamlaluno for reminding me to update my local copy. I will do and will test it again.

Thanks @Hardik_Patel_12 for the patch.Classname has been changed to appropriate namespace of @see tags.

Gentle hint to anyone reviewing this, can you also look at #3100251: Several code comments have incorrect namespaces for classes or interfaces they reference which is similar?

Thanks for the contributions here, and trying to improve Drupal core!

Some issues with the latest patch in #16:

1. +++ b/core/lib/Drupal/Core/Database/Query/Condition.php
   @@ -211,14 +211,14 @@ public function compile(Connection $connection, PlaceholderInterface $queryPlace
   -          // @see ConditionInterface::condition() method (and thus have the
   +          // @see \Drupal\Core\Condition\ConditionInterface::condition() method (and thus have the
   ...
   -          // @see ConditionInterface::where() method. Put brackets around
   +          // @see \Drupal\Core\Condition\ConditionInterface::where() method. Put brackets around
   

   These comments now exceed 80 chars wide, trading one code standard "violation" for another. ;)

2. +++ b/core/lib/Drupal/Core/Entity/ContentEntityBase.php
   @@ -49,7 +49,7 @@
   -   * @see ContentEntityBase::getFieldDefinitions()
   +   * @see \Drupal\Core\ContentEntityBase::getFieldDefinitions()
   

   I think #3112830: [policy, no patch] Allow static::methodName() and/or self::methodName() in @see comments when referring to the same class is the better solution when referring to other methods in the same class.

3. +++ b/core/lib/Drupal/Core/Field/FieldDefinitionInterface.php
   @@ -187,8 +187,8 @@ public function isRequired();
   -   * @see FieldDefinitionInterface::getDefaultValue()
   -   * @see FieldDefinitionInterface::getDefaultValueCallback()
   +   * @see \Drupal\Core\Field\FieldDefinitionInterface::getDefaultValue()
   +   * @see \Drupal\Core\Field\FieldDefinitionInterface::getDefaultValueCallback()
   
   @@ -202,8 +202,8 @@ public function getDefaultValueLiteral();
   -   * @see FieldDefinitionInterface::getDefaultValue()
   -   * @see FieldDefinitionInterface::getDefaultValueLiteral()
   +   * @see \Drupal\Core\Field\FieldDefinitionInterface::getDefaultValue()
   +   * @see \Drupal\Core\Field\FieldDefinitionInterface::getDefaultValueLiteral()
   
   @@ -222,8 +222,8 @@ public function getDefaultValueCallback();
   -   * @see FieldDefinitionInterface::getDefaultValueLiteral()
   -   * @see FieldDefinitionInterface::getDefaultValueCallback()
   +   * @see \Drupal\Core\Field\FieldDefinitionInterface::getDefaultValueLiteral()
   +   * @see \Drupal\Core\Field\FieldDefinitionInterface::getDefaultValueCallback()
   

   Same here.

4. +++ b/core/lib/Drupal/Core/Image/ImageFactory.php
   @@ -78,7 +78,7 @@ public function getToolkitId() {
   -   * @see ImageFactory::setToolkitId()
   +   * @see self::setToolkitId()
   

   Right, you're doing it here... why not be consistent about it?

5. +++ b/core/tests/Drupal/KernelTests/Core/Plugin/PluginTestBase.php
   @@ -48,8 +48,8 @@ protected function setUp() {
   +    // @see \Drupal\plugin_test\Plugin\TestPluginManager::_construct().
   +    // @see \Drupal\plugin_test\Plugin\MockBlockManager::_construct().
   

   I thought we don't end with the period for @see comments. I believe this should be:
   @see \Drupal\plugin_test\Plugin\MockBlockManager::_construct()

6. +++ b/core/tests/Drupal/KernelTests/Core/Plugin/PluginTestBase.php
   @@ -48,8 +48,8 @@ protected function setUp() {
   diff --git a/core/tests/Drupal/Tests/BrowserTestBase.php b/core/tests/Drupal/Tests/BrowserTestBase.php
   
   diff --git a/core/tests/Drupal/Tests/BrowserTestBase.php b/core/tests/Drupal/Tests/BrowserTestBase.php
   index 4845bf8..aca7d04 100644
   
   index 4845bf8..aca7d04 100644
   --- a/core/tests/Drupal/Tests/BrowserTestBase.php
   
   --- a/core/tests/Drupal/Tests/BrowserTestBase.php
   +++ b/core/tests/Drupal/Tests/BrowserTestBase.php
   
   +++ b/core/tests/Drupal/Tests/BrowserTestBase.php
   +++ b/core/tests/Drupal/Tests/BrowserTestBase.php
   @@ -257,7 +257,7 @@ protected function initMink() {
   
   @@ -257,7 +257,7 @@ protected function initMink() {
    
        // Copies cookies from the current environment, for example, XDEBUG_SESSION
        // in order to support Xdebug.
   -    // @see BrowserTestBase::initFrontPage()
   +    // @see \Drupal\Tests\BrowserTestBase::initFrontPage()
   

   static:: or self:: would be better.

7. +++ b/core/tests/Drupal/Tests/Component/Datetime/DateTimePlusTest.php
   @@ -602,7 +602,7 @@ public function providerTestDateTimestamp() {
   -   * @see DateTimePlusTest::testDateDiff()
   +   * @see \Drupal\Tests\Component\Datetime\DateTimePlusTest::testDateDiff()
   

   And here.

Generally, is this issue trying to fix all @see references in all of core? I haven't grepped to verify if this fixes them all. The summary is only talking about a single file, but the patch is doing more than that. The summary should be updated to reflect the intention and scope of this change.

I'm strongly in favor of:

a) Postponing this until #3112830: [policy, no patch] Allow static::methodName() and/or self::methodName() in @see comments when referring to the same class is fixed and officially adopted as the standard (since core does it already, but it's not technically documented as our standard).

b) Then making sure this one issue fixes all lingering places that don't fully qualify the class in any @see comment, anywhere, in all of core (not separate issues for files, directories, subsystems, etc).

c) If @see is pointing to a constant or method in the same class, use static:: or self:: (consistently). Otherwise, use the fully qualified class name.

Thanks!
-Derek

Yeah, that, too. ;) I believe the standards (and IDE integration) expects @see only in docblocks at the start of functions, and that they're not supposed to be used in inline comments. I personally disagree with this, but it's obviously not up to me. ;)

we will work on VbContribution2020

I did changes based on @dww suggestions. Kindly review patch

I've re-rolled patch for 9.1

For the the updates and new patches, folks!

However, per #26.a, I'm going to formally postpone this issue on resolving #3112830: [policy, no patch] Allow static::methodName() and/or self::methodName() in @see comments when referring to the same class, first. Once that's fixed, we can proceed here. Until that happens, we're potentially wasting our time doing the wrong things.

Thanks,
-Derek

Just adding Coding Standards tag.

Turns out this is a duplicate of an earlier issue, #2662208: Fix @see documentation in core. However, this has a more discussion. So, I will close the older one in favor of this one and add credit. Coding standards issues are usually tasks, so changing category as well.