The current API doc for element_children() (http://api.drupal.org/api/drupal/includes--common.inc/function/element_c...) only says this:
Return the children of an element, optionally sorted by weight.
In fact, it is not explained anywhere right now what a "child" is. This related issue is about adding this information to the documentation of drupal_render(): #1253828: drupal_render doc should explain what "child" means.
I wonder if it would not be a good idea to add a similar explanation to the doc of element_children(), in order to increase the chance that a developer wondering "How do I extract all elements that are not #-properties from an array?" finding the doc of this function. Right now, the documentation is really only useful to someone who already knows what a "child" is.
Comment | File | Size | Author |
---|---|---|---|
#8 | doc-element_children-1258176-7.patch | 710 bytes | sven.lauer |
#3 | doc-element_children-1258176-3-minimal.patch | 479 bytes | sven.lauer |
#3 | doc-element_children-1258176-3-extensive.patch | 882 bytes | sven.lauer |
Comments
Comment #1
jhodgdonSounds like a good idea!
Comment #2
sven.lauer CreditAttribution: sven.lauer commentedOkay, I'll see if I can find the time to do a patch. Probably after #1253828: drupal_render doc should explain what "child" means is in/decided, so that we can link there for details.
Comment #3
sven.lauer CreditAttribution: sven.lauer commentedAttaching two patches. The 'minimal' one contains a minimal change with a reference to drupal_render(). Th 'extensive' one tries to explain why the distinction of '#'-properties and 'children' is useful in the first place.
One might ague that this information should go into the doc of drupal_render(), but I kind of like the current doc there. Also, the notion of #-properties vs. children is useful more generally, and element_children() seems a good place to say why.
Comment #4
jhodgdonPresumably you wanted these to be reviewed - which one are you advocating?
Comment #5
sven.lauer CreditAttribution: sven.lauer commentedUps, yes, forgot to set the status.
I am in favor of the more extensive one.
Comment #6
jhodgdonHm. Actually, I like the idea of only maintaining the "what is a child" docs in one place, so I think the minimal approach is better? The extensive one seems a bit repetitive to me anyway.
Other things to fix in this patch:
- Verb tense in the first line of this doc block "Return the children of an element, optionally sorted by weight." --> returns
- @param "$elements The element to be sorted." seems ... The parameter name should be $element not $elements I think, and it should say "the element whose children are to be listed" or something like that?
- I also think "The children of a given array " should be "The children of an element" (use consistent terminology)?
Comment #7
sven.lauer CreditAttribution: sven.lauer commentedOkay ... my thinking was that the drupal_render()-doc does not quite explain the general rationale of making use of #-properties and children (in the sense that it is a way to represent a tree structure together with node-specific properties in a single structured array). And also that this kind of explanation maybe should not be in drupal_render(), because the concept is more general (even though renderable arrays may be the only place the concept is used right now). Re-reading the extensive patch, I agree that it is somewhat redundant, though.
Also, I would not have rolled two patches if I had not been in two minds about this ... so I guess I agree with your reasoning.
Rerolling,
- taking into account the person feature of the initial verb.
- I kind of was bothered by "return(s) the children ..." because the function will not return the children (arrays), but rather their keys in the parent array. Changed this to "Identifies the children ...", which seems more correct wrt what the function does.
- Wrt to the @param: Ugh, completely failed to see this.
- Wrt to the parameters' name: $elements is what the parameter is named in the function signature ... should something like this be changed in a doc patch?
- Finally, we have the element/element ambiguity--- "element" as a drupal term vs. "element" as "a thing in an array". Making the change suggested would have ended up as "The children of an element are those elements that have a key that does not start with a '#'"---so I replaced the suggested "element" with "element array" and went with "key/value pair" for the other occurrence.
Comment #8
sven.lauer CreditAttribution: sven.lauer commentedAaaand actually attaching the patch.
Comment #9
jhodgdonThis looks good to me. Minimal but sufficient. :)
Comment #10
webchickCommitted and pushed to 8.x and 7.x. Thanks!