Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Coming from #2228795: Where did hook_url_outbound_alter go?, but that's just a symptom of an overall issue.
That issue points out that an old hook in Drupal 7—hook_url_outbound_alter()—is now replaced by a class-implementing-an-interface/tagged service combo. The patch there rightfully removes the outdated documentation about hook_url_outbound_alter(), but replaces it with nothing, leaving only the chance notice at https://drupal.org/node/2238759. Which is fine if you a) used Drupal 7, b) had any idea this hook existed in Drupal 7 to know to search for it in the API change records. But fast-forward a couple of years, when Drupal 8 is released to wild acclaim, and widely used by a tremendous number of new developers, none of whom ever touched D7. How will they ever learn of this extension point, or any other similar extension point, in core/contrib?
In the past, searching for "Hook_" would bring up all (well, most... "themable" is another set) of core's extension points. Now, we don't have a similar method to replace it. How do I discover all of the plugins, the tagged services, and other discoverables? While the new topic-based pages on api.d.o will cover the big areas, places like this are basically only accessible by walking through D8 very carefully in a step-debugger. :\
I feel like there are other issues that touch on at least parts of this, but it feels like this needs some dedicated discussion around it.
Comments
Comment #1
xjmComment #2
jhodgdonHow is this different from #2148255: [meta] Make better D8 api.d.o landing page, linked to high-level overview topics, and put it in Core api.php files?
If there is a specific developer topic that we need to add to the landing page, then file an issue to add the topic. I don't think we have a systematic problem -- we have the landing page so that people will "discover" topics that they might need to know about (like entry points for module developers).
Comment #3
xjmThis is more specific, and probably a sub-issue of that meta. It's specifically about things like tagged services, request attributes, annotation keys, etc. etc. Not just "discovering topics"; a specific subset of important API that we do not yet have a way of documenting.
Comment #4
jhodgdonOK then.
Comment #5
webchickI think this issue is a little different, more like… this title.
I think ideally, this would slot into the parent issue like so:
- We would have a topic page linked from the api.d.o home page that describes the overall concept of a WHATEVER and what it does. (That's the parent issue.)
- This would link to a table similar to the one at https://api.drupal.org/api/drupal/modules%21system%21theme.api.php/group... (or maybe the table would just show up down below like it does here), which has all of those WHATEVERs in core enumerated below. (That's this issue.)
Does that distinction make sense?
Comment #6
jhodgdonUh, er, all topics have the abillity to include lists of things (functions, classes, etc.). You just use @ingroup. ?!? Or are you talking about something that the API module builds automagically?
Comment #7
webchickRight. Something automagical, because we can't stick an @ingroup in the middle of a YAML file, at least as far as I know.
Comment #8
jhodgdonOK, how will the API module detect a "discoverable" then? And what are they -- classes? YML files? What? Because if they are classes, the @ingroup can go in the class, and if they are YML files... that is a bit weird.
Comment #9
jhodgdonUm... And can someone please write up an issue summary explaining what this is about? What are these "discoverables" you are talking about here? I don't think I understand what this issue is about. At all. Or how it is different from "We need more topics on the API landing page", or why the "things" displayed in the list need to be automagical for any of these new topics, or ... I'm just really confused here.
For instance... The API module is currently discovering all Annotation classes because they have @Annotation in their class, and it is treating this as "@ingroup annotation", which someone wrote up documentation for. That was actionable and we got it done.
This issue, on the other hand, is nebulous and not actionable, so far. Please make it concrete and actionable, or close the issue, because if it's a nebulous "We need a strategy" issue, we already had an issue about that and we do have a strategy, which is "make topics and add things to them with @ingroup".
Comment #10
webchickYeah, I need help making it actionable because I have no idea what all of these things are. I just know they exist, and every time I ask "how do I see a list of all of those things?" I get "Hmmm" in response from core devs. ;P But this is a fair issue status atm.
Comment #11
webchickI guess though, here's an example of what I mean.
From #2200229: Use entity access for Views UI routes.
These are both in routing.yml files.
In this sampling, we can see a number of properties, including:
- _entity_form
- _title
- _permission
- _entity_create_access
- _entity_access
- _csrf_token
etc.
...how do I get a dynamic list of all possible routing properties, along with links to documentation so I can see the difference between _entity_access and _entity_create_access?
Comment #12
jhodgdonThis is a perfect example of what I'm talking about. This isn't a "discoverable", this is documentation that needs to be written if it doesn't already exist. Routing properties that go into routing.yml files should be documented in the Routing topic on api.drupal.org, and/or the Routing docs under drupal.org/developing/api/8. I do not think there would be a way for anything automagical on drupal.org to "collect and document what properties you can put into routing.yml files". It could maybe collect "properties people have put into routing.yml files", but it wouldn't know what they were being used for or where to look for documentation for them. So, this is documentation that needs to be written up by a person.
Comment #13
webchickHm. But that sucks, because manually-written documentation will naturally fall out of date. :( If we had to manually update a list whenever we added a hook, for example, the list would always be wrong. Instead you search "hook_" and you always have the up-to-date list. @ingroups can also be missed, but they're far less likely to be, since it's one line instead of several, and sticking one in when it's missing is a Novice task that can be picked off in 10 seconds.
Comment #14
catchManual routing docs are at https://drupal.org/node/2092643
Comment #15
webchickWe discussed this a bunch on IRC and agreed how to handle it is in the individual sub-issues linked off #2148255: [meta] Make better D8 api.d.o landing page, linked to high-level overview topics, and put it in Core api.php files to be on the lookout for dynamic "listing thingies" that would make sense as part of each section, and open separate issues in the API queue for each, like #2244683: Add a dynamic listing of services.
I still think this overall problem is huge and it makes me sad to close out a critical issue about it, but I don't have the experience/knowledge to make it actionable, so…
Comment #16
xjmCan we keep this open to track the sub-issues? It is listed as a meta, after all. I agree the proper course of action is to file individual issues for individual problems, but at present it's hard to know where to start. Re-scoping a bit to focus on that, rather than on how it gets exposed to the API module. We need to change our culture so that documenting these is as much a required step in creating a patch as documenting a hook or class. To do that, we need to establish clear patterns, so let's collect them in one spot.
Remember, hook documentation is also added manually to the *.api.php.
Comment #19
xjmComment #20
jhodgdonUntil this issue actually has sub-issues, or an issue summary explaining what it is covering or what documentation is missing, I am downgrading it. If I cannot figure out what documentation is missing, and no one can articulate it by filing sub-issues, it is not critical.
Comment #21
catchchx opened two issues, not linked to this one. I've added this as the parent. Those are two very concrete things that we have no obvious way to document at the moment.
Comment #22
chx CreditAttribution: chx commented> no one can articulate it by filing sub-issues
Yeah that's the problem that makes me lose sleep at night in general not just this issue: no one can articulate it but me. I wanted to leave, you know? Heck, supposedly I left. Anyways, I will review again my NYC notes to file more.
Comment #23
catchWith plugins + events + services plus the high-level routing change notice all having critical issues, I think this is everything.
If we find something else that's completely lacking centralized documentation we can just open a new issue for that, closing this as duplicate.
Comment #24
jhodgdonWe need this to stay open until the child issues are dealt with. However, not critical at this point.
Comment #25
chx CreditAttribution: chx commentedIt absolutely is critical in the sense of we can't release like this. And, now, apparently route names join the parade #2321815: Document not to request the Route object
Comment #26
jhodgdonSo... What else do you think needs to be done on this issue, besides child issues we've filed already?
Comment #27
catchYes I don't think there's anything in this issue not handled by the already critical child issues. If we find something new that's not documented, then we can open new major or critical issues for those too.
Comment #28
xjmThis issue was marked as a beta target for the 8.0.x beta, but is not applicable as an 8.1.x beta target, so untagging.
Comment #37
DamienMcKennaPushing this to D9.