Closed (fixed)
Project:
Drupal core
Version:
7.x-dev
Component:
documentation
Priority:
Normal
Category:
Bug report
Assigned:
Issue tags:
Reporter:
Created:
26 Oct 2011 at 13:46 UTC
Updated:
4 Jan 2014 at 01:11 UTC
Jump to comment: Most recent, Most recent file
Comments
Comment #1
jhodgdonOK, that seems like a reasonable idea. That would be a good project for a novice contributor. It just needs to use @see to link to the "themeable" group. See http://drupal.org/node/1354 (links section).
Comment #2
joachim commentedAdding that I think it would be a good idea to put this link fairly high up in the (long and pretty technical in parts) docs for this function. Catch the less technical users before they get scared! :)
Comment #3
jhodgdonOur standards call for putting @see links at the bottom of function doc.
Comment #4
joachim commentedAh. In which case, could this be linked in the body of the documentation, as a descriptive sentence?
Eg, 'The theme function is used to allow [LINK]themeable functions[LINK] to be overridden in a site theme.'
Or even use one that's already there:
All requests for themed output must go through this function. It examines the request and routes it to the appropriate [LINK]theme function[LINK] or template, by checking the theme registry.
Comment #5
jhodgdonYes, that could be done. Sounds like a good idea to turn that sentence that is already there into a link. I think it would still also be beneficial to have the @see at the end.
Comment #6
drupal_was_my_past commentedPatch attached based on #5.
Comment #7
jhodgdonThat's the right idea!
I think:
- we usually like to put @link ... @endlink all on one line (you can put it all on its own line so it will not go over the 80-character limit ) - reason being that the API module doesn't do well with multi-line @links sometimes (or at least it used to not do well, maybe that has been fixed).
- The "or template" can be part of the link text, since the themeable group is used for both.
Comment #8
drupal_was_my_past commentedThanks! Here's the re-rolled patch.
Comment #9
jhodgdonExcellent, thanks!
Comment #10
catchMakes sense, took me a couple of reads to realise @link themeable blah blah @endlink automatically links to the themeable group, but that's just me I think. Committed/pushed to 8.x, moving back to 7.x.
Comment #11
drupal_was_my_past commented7.x ported patch attached for review.
Comment #12
jhodgdonThanks!
Comment #13
webchickNope, it's me too. ;) But we can't exactly comment our comments. :D
Committed and pushed to 7.x. Thanks!