Node::load() and similar are inherited from the parent so link doesn't get made on api.d.o

The reason is that Node::load() does not reimplement Entity::load() so you have to see Entity::load() instead.

I am not offering this as a solution but this change record has some more information on the new API: EntityInterface::load(), loadMultiple() and create() added to load and create new entities.

Another approach to documenting this in the way you feel it should be documented would be to implement the load function in Node, and use the {@inheritdoc} annotation. But I don't know whether we ever do that simply for documentation purposes. The "@see" that I posted in #2 would help on its own.

If you tell the user to use Entity::load(), this will be confusing and not the optimum solution.

Actually, that would work.

Hm. What about saying something like this in the @deprecated documentation:

Use \Drupal\node\Entity\Node::load() (see \Drupal\Core\Entity::load() for documentation).

The problem with using a separate @see is that on api.drupal.org, the @see makes a separate See Also section on the page, which is not necessarily located right where the Deprecated section is. So it won't necessarily be clear to people that they would need to look at the See Also section.

Thoughts?

That works for me.

Thanks! Looks good, except:

+++ b/core/modules/node/node.module
@@ -438,7 +438,8 @@ function node_load_multiple(array $nids = NULL, $reset = FALSE) {
+ *   Use \Drupal\node\Entity\Node::load() (see \Drupal\Core\Entity::load() for

That is not the right namespace for Entity::load().

Should be
\Drupal\Core\Entity\Entity::load() I think?

That will teach me to copy and paste.

Yeah, time to learn not to copy my suggestions exactly without checking them. ;)

Thanks!

Thanks @Greg Sims, good catch! The suggested solution makes sense to me.

There are several other similar deprecations in core that need a similar fix; for example for user_load(). Can we fix those in this patch as well? I checked for them by doing this grep:

grep -r "::load()" * |  grep '*'

"Entity::load" works.

A faster finder: egrep -r "\*.*::load\(\)" *

I am tagging this Novice because a novice can follow on with the #8 patch with the information from #10 and #13 to complete the issue.

@XJM can we do it with file_load and term_load, role_load with user_load ?

@snehi Go ahead and write a patch.

Unassigning @Snehi as there has been no activity for three weeks. Picking up on this as a part of catalyst academy. This will be my first ever patch for drupal. Thanks for all the future help :)

We used the following grep command: grep -rn "::load()" * | grep '*' | grep '\.module' to identify the functions to modify and we have adhered to the drupal coding standards which is the 80 character line rule. This is my first patch ever :D

An interdiff on a first-ever patch? That must be some kind of a record.

patch works fine.!

This actually needs a bit more work before it's ready:

1. Not everything in node.module or file.module is fixed in this patch. There is also node_type_multiple() and file_load_multiple(). I didn't look elsewhere... but besides the files that have fixes in this patch, there may also be functions that are not in .module files. So I think the grep in #19 didn't catch everything.

2. +++ b/core/modules/node/node.module
   @@ -240,7 +240,8 @@ function node_mark($nid, $timestamp) {
     * @deprecated in Drupal 8.x, will be removed before Drupal 9.0.
   - *   Use \Drupal\node\Entity\NodeType::loadMultiple().
   + *   Use \Drupal\node\Entity\NodeType::loadMultiple() (see
   + *   \Drupal\Core\Entity\Entity::loadMultiple() for documentation).
     *
     * @see \Drupal\node\Entity\NodeType::load()
   

   We should also fix the @see at the end of this doc block, which (for the same reason) will not work... or maybe just get rid of it. There may be others in Core, which should be caught by a better grep too.

We should also fix the @see at the end of this doc block, which (for the same reason) will not work... or maybe just get rid of it. There may be others in Core, which should be caught by a better grep too.

Not necessarily advocating for anything here, just wanted to bring this up: IDEs will highlight @see's like this just fine, so it does provide some value as is (generally speaking not sure about this particular one). That doesn't of course make it less unfortunate that it's not linked on api.drupal.org

Assigned to myself so i can reroll the patch. I have taken into account the new feedback, thanks for the help :)

As per @jhodgdon suggestion, I have run the following grep: grep -rn "::load()\|:loadMultiple()" * | grep '*' | grep -v 'Test.php' to look for any that I have missed. I fixed those and then also added and removed @see 's to make the documentation more consistent.

Thanks! I think this is fine, and I think all the @see changes make perfect sense -- they will link people to where the docs actually are, which is a good thing.

Note: I could gripe about the order of doc blocks -- we have standards for how these things are supposed to be ordered at https://www.drupal.org/node/1354#order -- but it would be out of scope for this issue, and this patch is not really making that worse than it already is. So let's just ship it.

api.drupal.org has the information available that the Node class has a load method - it's listed at https://api.drupal.org/api/drupal/core%21modules%21node%21src%21Entity%2...

So it seems like it should be possible to resolve that when constructing api.drupal.org links as well. That would be an api module patch and might not be straightforward, but I'm not sure working around it with extra references in core helps. Also why not linking to the interface method rather than the parent class?

OK.

That's definitely a good point about the interface method. Also filed this issue in the API project:
#2656976: Links to inherited class members are not made

I've actually got the API module patch made already (although the fix is not on api.drupal.org yet). So... maybe we should just mark this as Won't Fix?

@Greg Sims the api module is for 7.x only, but the fix there will work for 8.x on d.o, so this is fine as won't fix for core.

@Greg Sims - go to api.drupal.org -- it's fixed there now.

@Greg Sims: If you go to https://api.drupal.org/api/drupal/core!modules!node!node.module/function... now you will see that Node::load() is now a link. It links to Entity::load. The fact that Node::load() is not available in the search autocomplete is a valid point, but I suppose that's another issue (also for API module).

Re #32-35. I think the issue is that it is a head-scratcher to mention Node::load() but link to Entity::load(), even though Entity::load() is technically correct. I think it is fine in terms of the link, but imagine the case where a developer reads the node_load() documentation in the codebase then cannot find anything when searching the API site for Node::load().

Re #34:

To make searching for Node::load() possible, the API site would have to implement full-text search, or, generate a documentation page for every function that was not re-implemented in every level of every inheritance tree.

Why should node::load be any different?

Except that documentation is done for actual methods in a class. Node::load() is not an actual method.

Would it not be possible to use this structure to create the documentation for each function automatically?

This would mean, a separate documentation page for every method that is inherited from a parent class. We don't normally expect to separately document e.g. Node::getFieldDefinitions(), Node::toArray(), Node::getIterator(), User::getFieldDefinitions(), User::toArray(), User::getIterator(), etc., for all content entities - that's not scalable. Node::load() is just a specific case of this.

To make searching for Node::load() possible, the API site would have to implement full-text search

This sounds like the best solution. I actually thought api.drupal.org had full-text search already...

OK.

First of all, the API module does support full-text search. We do not, however, have it turned on for api.drupal.org.

Second, turning on full-text search would not make there be a page on api.drupal.org for Node::load(), and I don't think that the existing page for Entity::load() would appear in full-text search results, because there is no page for Node::load(). At best, a function like node_load(), which has the text "Node::load()" in its documentation, would come up, and then the link would still go to the Entity::load() page.

So. There is not really a Node::load() method. We are not going to make a page for every inherited method. We have a page for the Node class, and you can see all of the inherited methods on it, with their actual names. #38 is correct -- it doesn't scale. So, I'm sorry, but this is as fixed as it will get.

The issue title here is about making *links* -- that was fixed. But making functions that don't exist have pages, and making them appear in the autocomplete, is not going to happen. Full text search could happen -- if you would like to advocate for that, please file an issue in the "api.drupal.org customizations" project if there isn't already one:
https://www.drupal.org/project/apidrupalorg

Back to Won't Fix.