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.

<?php
 
// 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.

Files: 
CommentFileSizeAuthor
#8 fix-documentation-1619084-8.patch943 byteskiamlaluno
PASSED: [[SimpleTest]]: [MySQL] 37,011 pass(es).
[ View ]
#2 fixes-documentation-1619084-2.patch759 byteskiamlaluno
PASSED: [[SimpleTest]]: [MySQL] 36,847 pass(es).
[ View ]
#1 fixes-documentation-1619084-1.patch750 byteskiamlaluno
PASSED: [[SimpleTest]]: [MySQL] 36,851 pass(es).
[ View ]

Comments

Status:Active» Needs review
StatusFileSize
new750 bytes
PASSED: [[SimpleTest]]: [MySQL] 36,851 pass(es).
[ View ]

This is a first tentative to fixe the documentation.

StatusFileSize
new759 bytes
PASSED: [[SimpleTest]]: [MySQL] 36,847 pass(es).
[ View ]

This is probably preferable.

Status:Needs review» Needs work

Hmmm... 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.

Status:Needs work» Needs review

The patch in #2 just replaces drupal_render_children() with drupal_render().

If #theme is not present and the element has children, they are rendered and concatenated into a string by drupal_render().

This would contrast with what the previous sentences says.

#theme is the theme function called first. If it is set and the element has any children, it is the responsibility of the theme function to render these children.

In the first case, the theme function renders the element's children; in the second case, the child items are rendered by drupal_render().

I am still not happy with this wording and I think it's confusing and innacurate.

Status:Needs review» Needs work

Status:Needs work» Needs review
StatusFileSize
new943 bytes
PASSED: [[SimpleTest]]: [MySQL] 37,011 pass(es).
[ View ]

I'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:

  * these children. For elements that are not allowed to have any children,
  * e.g. buttons or textfields, the theme function can be used to render the

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.

The 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.)

  • Well controlled diabetes and otherwise good health (i.e. no complications) using diet alone, or only one medicine such as metformin, a dipeptidyl peptidase-4 inhibitor (drugs ending in gliptin, e.g. sitagliptin), or a thiazolidinedione (ending in glitazone e.g. pioglitazone).
  • NICE sets out best evidence within the context of cost effectiveness, and clinicians can choose not to prescribe a treatment, despite patient preference, if they think it unsafe e.g. steroid injections for hay fever - or ineffective.
  • What is the daily fluid intake, in terms of type (e.g. caffeine drinks) and quantity?
  • Less common causes of NE include conditions such as abnormalities of the urinary tract, neurological conditions, and endocrine disorders e.g. diabetes.

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:

  • Commit this patch. In this way, the documentation for drupal_render() doesn't reference a function that is not called from drupal_render().
  • Change i.e. with e.g. when it is necessary. (See the other issue report I opened.)

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.

Status:Needs review» Needs work

The 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).

The purpose of this patch is replacing the reference to drupal_render_children(), which is not even used from drupal_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.

Status:Needs work» Reviewed & tested by the community

OK, you are right -- let's not worry about the e.g. line in this patch. I'll get it committed shortly.

Status:Reviewed & tested by the community» Fixed

Committed above patch to both 7.x and 8.x. Thanks!

Status:Fixed» Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.