@see tags are not correctly handled

I just noticed that a link to another page is effectively shown for the first @see tag.

It is just the other two links that are not correctly handled.

Probably it is not easier to find another page where this happens, but I think I understood what happens. @see tags are correctly parsed; it just that when @see \Drupal\Core\Cache\Cache is handled, @see \Drupal\Core\Cache\Cache is removed from the documentation comment, changing the documentation comment used for the page I am referring in the IS to the following one.

/**
 * A RedirectResponse that contains and can expose cacheability metadata.
 *
 * Supports Drupal's caching concepts: cache tags for invalidation and cache
 * contexts for variations.
 *
 * ableMetadata
 * ableResponseTrait
 */

It happens also in the documentation for template_preprocess_links().

 * @see \Drupal\Core\Utility\LinkGenerator
 * @see \Drupal\Core\Utility\LinkGenerator::generate()
 * @see system_page_attachments()
 */

Also in this case, the first @see link is rendered.

Thanks for the investigation up there, it really helps!

I've checked the code and I think I know where the problem is. To set the "see" property, we are calling $this->setProperty($docblock, "see");

And if we see the code here: https://git.drupalcode.org/project/api/-/blob/2.x/src/Parser.php#L2189-2192

    $docblock[$property] = '';
    while (preg_match('/' . self::RE_TAG_START . $property . '\s(.*?)(?=\n' . self::RE_TAG_START . '|$)/s', $docblock['content'], $matches)) {
      $docblock['content'] = str_replace($matches[0], '', $docblock['content']);
      $docblock[$property] .= "\n\n" . $matches[1];
    }

We can see how we are matching and replacing the matched string in a loop. So, when replacing @see \Drupal\Core\Cache\Cache with empty string from

 * @see \Drupal\Core\Cache\Cache
 * @see \Drupal\Core\Cache\CacheableMetadata
 * @see \Drupal\Core\Cache\CacheableResponseTrait

the resulting code is ableMetadata ableResponseTrait.

So I think that we need to try to replace only one instance at a time.

I've tested https://git.drupalcode.org/project/api/-/merge_requests/37/diffs locally on the first reported file and it fixes the issue. I need to test it in other files and deploy to the dev environments.

fjgarlin → closed merge request !37

I've merged the suggested changes in this commit (together with another fix): https://git.drupalcode.org/project/api/-/commit/1e22de5d23efbe816c6a7888...

I'll deploy to the dev/staging environments.

Staging site: https://api.stage.cluster.drupalsystems.org/api/drupal/core%21lib%21Drup...

Deployed to production. I've fixed manually:
- https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Cache%21C...
- https://api.drupal.org/api/drupal/core%21includes%21theme.inc/function/t...

The rest of the instances will self-heal in the next parsing cycle.
Marking this as fixed.

Automatically closed - issue fixed for 2 weeks with no activity.