drupal_render api documentation

Why is that?
It's a bug!
http://drupal.org/node/346264#comment-1220620
http://drupalbin.com/1059

@kenorb, if you believe this is a bug (and I do not), please file a bug report against code.

While the drupal_render api documentation might state "Calling this function twice returns NULL the second time.", I do not believe that to be useful. The key feature of drupal_render (and also responsible for this behaviour) is that drupal_render marks whatever it rendered as "printed", and does not process "printed" elements again.

This is a VERY useful feature as you can do this, without having $item['somepart'] rendered twice:

$output = drupal_render($item['somepart']); // renders only $item['somepart].
$output .= drupal_render($item);  // renders the REST of $item.

When you making some patch, how do you know how many times drupal_render has been called?
Look at this patch: http://drupal.org/files/issues/simplenews_template.module.patch (at the end)
Question: How many?
Because I don't know;/

Please keep the issue focussed on the API documentation.

Well, probably drupal_render() should mention how it modifies its input, rather than just saying don't call it twice (i.e. say why).

Please start with Drupal 7.

Adding a short note (see #5) seems like a good Novice project

Here's a patch that adds documentation to reflect @Heine's comment (#2) about the '#printed' flag.

Looks nice, thanks! This is rtbc. :)

This is a nice clarification. Committed to HEAD. Thanks!

Thanks, glad to help :)

This change needs to be ported to the D6 doc as well.

Patch to be completed today

Here it is

Thanks! This patch applies cleanly and looks good to me. Congratulations rdrh555 on (I think) your first core patch!

Thanks, committed.