http://api.drupal.org/api/function/hook_filter_info/7 was extended and extended over time during the Filter API revamp for D7. Reading it once again, I failed to understand it.
One essential information is missing, which makes this a bug report: The registered filter names (array keys) have to be namespaced/prefixed by module name.
A detailed analysis of what's described there and what needs to be explained will follow.
| Comment | File | Size | Author |
|---|---|---|---|
| #14 | 735196-14.patch | 19.26 KB | jhodgdon |
| #13 | 735196-13.patch | 19.01 KB | jhodgdon |
| #8 | drupal.filter-docs.8.patch | 19.85 KB | sun |
Comments
Comment #1
qasimzee commentedsubscribe
Comment #2
sunComment #3
sunAlthough badly needed, this is D8 material according to the rules (I had to learn today). It may be backported at a later point in time (though that's unlikely).
Comment #4
sunComment #5
mattyoung commented~
Comment #6
damien tournoud commentedComment #7
jhodgdonsun: when you reported this issue, you said you would provide a detailed list of what needs to be done. Could you possibly do that now?
Also moving to the doc component and removing the tag. It sounds like this is a purely API doc issue, right?
Comment #8
sunThanks for reminding me ;)
OK, attached patch is what I want to see.
Unfortunately, many contributed modules followed Filter module's ugly example of naming the callbacks _MODULE_CALLBACKNAME(), which is plain nuts. (See http://api.drupal.org/api/drupal/modules--filter--filter.module/group/st...)
For D8, I want to remove those manual callback definitions entirely and go with straight hooks instead. Thus, the more modules are going to implement the documented hook_filter_FILTER_VERB() pattern, the better. Likewise, some modules took over the insanely stupid settings form code form Filter module's filters.
Note that many parts are merely copied/moved around -- I've rewritten small parts only.
Is this sufficient for someone to take over?
Comment #9
jhodgdonUmmm... So is this a D8 issue now, or are you advocating something like the above patch be committed to D7? I'm a bit confused (obviously).
Comment #10
sunThe patch is absolutely intended for D7. The part about D8 was merely to provide some underlying reasoning for the recommended callback names.
As mentioned (and repeated) as "note" in the phpDocs of the patch, those are not really hooks, but merely recommended filter callback function names.
Thus, two purposes:
1) Clarifying the individual filter API callbacks, their parameters, function bodies, and return values.
2) Recommending a filter callback function name pattern that doesn't involve private function names, and is most likely future-proof with regard to D8+. That latter, of course, not being guaranteed, but that doesn't matter.
btw, I'm in IRC, if you'd like to discuss. :)
Comment #11
jhodgdonThanks for the clarification.
I'm not happy with the current patch:
a) We can't have /** docblocks starting with @todo. They need to start with a one-line summary.
b) We don't want to name something hook_* if it's not really a hook.
c) I think the current way the file is structured will be putting the callback functions you've defined into the Hooks topic/group on api.drupal.org, which is also not great.
d) There are some editing/structure issues as well. For instance, normally we document the structure of a return value array in the @return, not in the function description body.
So we need to figure out how to document these suggested callback names... sort of a meta-issue, but I don't really want to have this patch committed until we figure that out.
Comment #12
jhodgdonI guess we can call the functions hook_* because sun and I can't think of a better naming convention for the API docs at the moment. Anyway, I'll clean up the doc and submit a new patch.
Comment #13
jhodgdonHere's a new patch, with completely rewritten documentation. Note that the hunks from filter.module are not really documentation, just cleaning up the code that sun did.
Comment #14
jhodgdonOne small change: better example for the filter tips function.
Comment #15
sunRocks! Thank you, jhodgdon!
Comment #16
dries commentedNice improvements. Committed to CVS HEAD. Thanks.