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.
API page: http://api.drupal.org/api/drupal/includes%21common.inc/function/drupal_r...
The documentation page says:
If #theme is not present and the element has children, they are rendered and concatenated into a string by drupal_render_children().
That is not what drupal_render()
does, as the function contains the following code.
// If #theme was not set and the element has children, render them now.
// This is the same process as drupal_render_children() but is inlined
// for speed.
if ($elements['#children'] == '') {
foreach ($children as $key) {
$elements['#children'] .= drupal_render($elements[$key]);
}
}
The call to drupal_render_children()
has been replaced by inline code, but that fact is not reflected in the documentation.
Comment | File | Size | Author |
---|---|---|---|
#8 | fix-documentation-1619084-8.patch | 943 bytes | apaderno |
#2 | fixes-documentation-1619084-2.patch | 759 bytes | apaderno |
#1 | fixes-documentation-1619084-1.patch | 750 bytes | apaderno |
Comments
Comment #1
apadernoThis is a first tentative to fixe the documentation.
Comment #2
apadernoThis is probably preferable.
Comment #3
jhodgdonHmmm... Previously, drupal_render_children() took care of the whole process of rendering and concatenating, so I don't really like the current wording talking about the function itself in 3rd person as it were...
How about something like:
If #theme is not present and the element has children, each child is itself rendered by a call to drupal_render(), and the results are concatenated.
Comment #5
apadernoThe patch in #2 just replaces
drupal_render_children()
withdrupal_render()
.This would contrast with what the previous sentences says.
In the first case, the theme function renders the element's children; in the second case, the child items are rendered by
drupal_render()
.Comment #6
jhodgdonI am still not happy with this wording and I think it's confusing and innacurate.
Comment #7
jhodgdonComment #8
apadernoComment #9
jhodgdonI'm happy with that patch (not surprising, see #3). Any other opinions?
If we need to do another patch, we could fix the punctuation in the line right above the changes:
Should be "children (for example, buttons or textfields), the theme..." probably? In any case, if e.g. is used, it needs to be followed by a comma.
Comment #10
apadernoThe comma after e.g. is not strictly necessary, even if it is normally used. Looking at the Corpus of Contemporary American English, I find the following sentences. (Emphasis is mine.)
The examples I reported here are classified as academic context, from the CoCA.
I think that using for example between parentheses should be more clear, even for those users who don't speak english as first language. There are many instances of e.g. in all the documentation, and such change should be done also for those cases.
What I would propose is the following:
drupal_render()
doesn't reference a function that is not called fromdrupal_render()
.At this point, we can decide to replace e.g. with for example between parentheses. If we decide to leave e.g. instead of for example, the documentation would not at least use i.e. when it should not be used.
Comment #11
jhodgdonThe best thing is not to use e.g. or i.e. at all. They are very often misused. I would prefer to see them replace with "that is" and "for example", or omitted entirely when not necessary (for instance, I think i.e. really doesn't have a place in technical documentation for the most part).
Comment #12
apadernoThe purpose of this patch is replacing the reference to
drupal_render_children()
, which is not even used fromdrupal_render()
.It's not that e.g. is used only in the documentation for
drupal_render()
. It seems that replacing e.g. in another patch makes more sense.Comment #13
jhodgdonOK, you are right -- let's not worry about the e.g. line in this patch. I'll get it committed shortly.
Comment #14
jhodgdonCommitted above patch to both 7.x and 8.x. Thanks!