Closed (fixed)
Project:
Drupal core
Version:
9.4.x-dev
Component:
documentation
Priority:
Normal
Category:
Bug report
Assigned:
Unassigned
Issue tags:
Reporter:
Created:
19 Jul 2021 at 04:09 UTC
Updated:
15 Dec 2022 at 17:25 UTC
Jump to comment: Most recent, Most recent file
Comments
Comment #2
tr commentedComment #3
tr commentedComment #4
longwaveThis can't actually happen until 10.x opens because theme functions, while deprecated, still work in 9.x (I originally wrote "supported" but that sounds like they might be a good idea, when they are definitely not).
#3097889: Remove deprecated theme functions already has a patch to remove the supporting code and documentation.
Comment #5
longwaveGood to see that we came to roughly the same end result when updating theme.api.php though :)
Comment #6
tr commentedTheme functions were deprecated all the way back in 8.0.0, but actually using them in D9 causes PHP to load the dblog with tracebacks.
I didn't realize they weren't fully removed until D10. After all, theme.api.php itself says theme functions "are deprecated in Drupal 8.0.x and will be removed before Drupal 9.0.x", but nevertheless IMO we shouldn't be documenting how to use deprecated things in an API overview document like this.
Really, this documentation should have been removed in D8. And certainly in D9! Why wait until D10? The .api.php documentation is different from documentation for deprecated functions, classes, or methods, as those are tied to the code itself. Rather, the .api.php documentation is supposed to show how to use the hooks/API defined by a module. For theme.api.php, it's a high-level overview of the theming system - we certainly do NOT want to be teaching people how to use theme functions at this point. For reference on legacy use, they can go back to the D8 documentation, but for the D9 documentation why would we want to keep explaining how to use theme functions?
Comment #7
vikashsoni commentedI have checked this patch in drupal-9.3.x-dev working fine after patch documentation removed
for ref sharing screenshot ...
Comment #9
joachim commented> Rather, the .api.php documentation is supposed to show how to use the hooks/API defined by a module.
That's true, but a developer looking at a D9 codebase which uses deprecated theme functions is also going to read the .api.php documentation to understand what the code is doing.
Comment #10
joachim commentedOops, didn't mean to change the status!
Comment #11
tr commentedIt really shouldn't take 7+ years to get rid of obsolete documentation. Especially since making regressive API changes in core can be done in under a month.
This is just one of the reasons why Drupal documentation sucks and keeps getting worse - there's no community will to do anything to fix it.
Comment #12
joachim commentedI totally understand your frustration, but the problem here is the code, not the docs. If the code is still working in 9.x because we forgot to remove it in 9.0, then the docs need to describe it.
(And I actually think that Drupal's code docs are way better than most of the PHP packages I see out there.)
Comment #13
tr commentedYeah, I'm frustrated because even the simplest bugs with documentation take years to fix. Years. For example, I participated in a bug report that's been open for > 5 years and has been RTBC for >3 years. DrupalCI tests it every two days, wasting real DA money. It fixes a missing return type in documentation. More than 5 years, and still broken. How many Drupal developers does it take to screw in a light bulb?
80% of my core issues are > 4 years old. Some are 15 years old. If the simple things can't be fixed without endless bikeshedding, then really what hope do we have for making better documentation? I don't even try to contribute to core much anymore, because experience shows that any effort I make will likely be wasted. I'm sure I'm not the only one who feels this way.
The above patch still applies in D10. There is no question (I hope) that theme functions are gone in D10, and that the documentation should be fixed. This is something that can be committed NOW which will improve the documentation without affecting anybody at all.
Comment #14
tr commentedComment #15
longwaveIn 10.0.x we can remove both the documentation and the code, so I think this is now a duplicate of #3097889: Remove deprecated theme functions?
Comment #16
andypostI think it ready, it should not have collisions with removal re #15
Comment #17
longwave#3097889: Remove deprecated theme functions removes both the code and the docs - we usually do them together?
Comment #18
catchWe could potentially keep this open as a 9.4.x backport of #3097889: Remove deprecated theme functions, but definitely that issue is the one to go ahead with in 10.0.x
Marking postponed for now, then we can decide whether to mark as duplicate or leave open as the backport issue (since there's discussion on here about whether to keep the documentation or not, personally I'd remove it in 9.4.x too).
Comment #19
andypostIt could also add changes from #3262500-18: Mark drupal_find_theme_functions() @internal in Drupal 9 as blocker commited
Comment #20
andypostno need to add, back to rtbc
Comment #21
catchComment #23
catchI agree with removing this documentation, for several reasons:
1. Theme functions are entirely obsolete, we didn't even recommend them when 9.0.0 was released.
2. The documentation for theme functions will still be in 9.x branches 9.3.x and lower.
3. This is high-level 'topic' API documentation for new developers, it needs to be concise and accurate. While it might be technically true that the 9.x theme layer supports theme functions, there is not good reason for anyone to encounter them, and as with #1 and #2 there are other places to find out. It's a bit like we also shouldn't document buggy behaviour (except very rarely with a @todo).
Committed 289fbfc and pushed to 9.4.x. Thanks!
Comment #25
bnjmnm