Problem/Motivation

This happens all the time. As Drupal changes or removes namespaces the links in @see tags get broken.

Proposed resolution

Fix all broken links.

In Drupal 9 much deprecated code is going to be removed. I expect the number of broken links will be increased significantly.
We might need an automated test for this.

Remaining tasks

Fix all found broken links.
Create a test?

CommentFileSizeAuthor
#10 report-v3.txt50.35 KBchi
#10 check-references-v3.php_.zip1.66 KBchi
#8 report-v2.1.txt53.65 KBchi
#5 check-references-v2.php_.zip1.65 KBchi
#5 report-v2.txt53.91 KBchi
#2 report-v1.txt78.31 KBchi
#2 check-references-v1.php_.zip1.63 KBchi

Comments

Chi created an issue. See original summary.

chi’s picture

chi commented
StatusFileSize
new check-references-v1.php_.zip1.63 KB
new report-v1.txt78.31 KB

Here is a script that can help to find broken links. See attached report.

Basically the reported issues fall into three categories.

  1. Broken links
  2. Links that are not properly formatted
  3. False negatives
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Related issues: +#2341405: Decide on standard for referencing namespaced classes

I'm not exactly sure what the report is telling me?

But as a note... The only real standards we have on namespaces in code docs are:

a) If you use a namespace at all, it must be the fully qualified namespace.
b) Immediately after an @tag, like @var, @see, @param @return (where we are indicating a variable type), you must use the fully-qualified namespace name.

So far, we don't actually have standards that say that in other places in API docs, we must use namespaces. So it is probably OK, for instance, in docs to reference a method on the same class as static::fooBar() or self::fooBar(), or maybe even Foo::fooBar() if the class name is Foo. But it wouldn't be good on class Bar to reference Foo::fooBar() -- in that case, you should probably include the namespace. But this is just my opinion...

There's an issue discussing the standards for this in the Coding Standards project issue queue; linking as related. Probably we should decide on standards before we go around fixing problems that are not really problems (some of the things in the report there may be legal).

chi’s picture

chi commented

I'm not exactly sure what the report is telling me?

It mostly tells you about broken references.
For instance, consider the first line in it.
core/modules/field_ui/src/FieldStorageConfigListBuilder.php -> \Drupal\field\Entity\Field
It indicates that FieldStorageConfigListBuilder.php file contains a reference on \Drupal\field\Entity\Field class which do not exist.

https://git.drupalcode.org/project/drupal/blob/8.8.0-alpha1/core/modules...

chi’s picture

chi commented
StatusFileSize
new report-v2.txt53.91 KB
new check-references-v2.php_.zip1.65 KB

As CS on this is not established yet, I updated the script to exclude records caused by using "wrong" format. So that now the report is supposed to have only records on broken links.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

OK, that's a bit more manageable...

I think there are still some false positives in your script though, like this line:

core/modules/language/tests/src/Unit/ConfigurableLanguageUnitTest.php -> \Drupal\language\Entity\ConfigurableLanguage.

I think it's getting confused by the . which indicates the end of a sentence. That class exists in that namespace.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I'm also not sure what's wrong with this:
core/modules/options/options.api.php -> options_test_allowed_values_callback
That function does exist.
https://api.drupal.org/api/drupal/core%21modules%21options%21tests%21opt...

chi’s picture

chi commented
StatusFileSize
new report-v2.1.txt53.65 KB

That function does exist.

It belongs to options_test module which was not installed when I was building the report. Fixed.

chi’s picture

chi commented

There is a bunch of false positives in the report caused by referencing class methods this way.
https://git.drupalcode.org/project/drupal/blob/8.8.0-alpha1/core/modules...

It'll be hard to fix as there is no indication of whether it is a class method or some global function.

Given that #2341405: Decide on standard for referencing namespaced classes does not even consider that notation I propose we replace it with FQN or self::methodName for now.

chi’s picture

chi commented
StatusFileSize
new check-references-v3.php_.zip1.66 KB
new report-v3.txt50.35 KB

I think it's getting confused by the . which indicates the end of a sentence.

Fixed. The number of positives in the report dropped to 518.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

OK, now these are looking like actual problems.

So it looks like there are several reasons for these errors:

a) Methods being referenced without a class designator. They should probably at least say self::methodName() or ClassName::methodName() instead of the bare methodName().

b) Functions/methods/classes that have been removed or moved to different namespaces

c) Typos

Still not sure how to divide the errors up into issues to be fixed, but maybe (a) could be one issue if it just used self:: as the replacement? Those would require much less thinking/investigating than the others.

chi’s picture

chi commented

They should probably at least say self::methodName() or ClassName::methodName() instead of the bare methodName().

Until #2341405: Decide on standard for referencing namespaced classes is resolved I propose using self::methodName() as it most frequently used so far.

idebr’s picture

idebr commented

Perhaps the reference check is something we can turn into a PHPCS rule? It would help new broken references from creeping in. It does not seem very Drupal-specific either.

chi’s picture

chi commented

Perhaps the reference check is something we can turn into a PHPCS rule?

This would be great but I think it is hardly possible. PHPCS is a pure static analyzer. For checking PHP class existence you have to use class_exists which relies on class loader. And besides in Drupal some namespaces are registered automatically depending on installed extensions. That means a fully bootstrapped Drupal instance is needed to make usage of class_exists reliable.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

quietone’s picture

quietone commented
Component: base system » documentation
Issue tags: -Documentation +Bug Smash Initiative

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

joachim’s picture

joachim commented

Ideally, this shouldn't just check things explicitly linked to with @see but any mention of a qualified classname or qualified classname + method name.

E.g. #3537572: PageVariantInterface docs mention class that doesn't exist

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.