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.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

apaderno’s picture

Status: Active » Needs review
FileSize
750 bytes

This is a first tentative to fixe the documentation.

apaderno’s picture

This is probably preferable.

jhodgdon’s picture

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.

apaderno’s picture

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

jhodgdon’s picture

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

jhodgdon’s picture

Status: Needs review » Needs work
apaderno’s picture

Status: Needs work » Needs review
FileSize
943 bytes
jhodgdon’s picture

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.

apaderno’s picture

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.

jhodgdon’s picture

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

apaderno’s picture

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.

jhodgdon’s picture

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.

jhodgdon’s picture

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.