\Drupal\Core\Render\RendererInterface::render() docs do not mention most of the base # attributes, adding default attributes to elements or how rendering works

Is this a core API documentation issue? It seems to be pointing to a documentation page on api.drupal.org. In which case you can:
a) just edit the page and fix it (preferable)
b) move this issue to the Documentation project issue queue.

OK, good point. So the drupal_render() documentation currently says:

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.

We need it to also say here that if there is a #markup property, that is concatenated as well (before the children). I'm sure there's a concise and precise/accurate way to say that. Seems like a good Novice project.

As for the on-line documentation you mentioned in the original issue here, please either file an issue in the Documentation project about that, or (preferably) edit the page and fix it. Thanks!

And note that this is Drupal 8.x only. The 7.x drupal_render() does *not* do this at all.

Actually, it's even more complicated than that, sigh. In 8.x, the sequence is:
- #children is set to '' if it was unset prior to the call to drupal_render().
- If #theme is set and #render_children is not, set #children to the output of theme(), using #theme as the theme hook. [Note: theme() returns an empty string if the theme hook is not matched.]
- if #children is still identical to '', render the children and concatenate them; store the result in #children.
- if #theme is not set and #markup is, prepend #markup to #children.

Sigh. I'm not sure how to write that out in clear concise prose... but we may not need every technicality to get into the documentation. I think the basic idea is that if #theme hasn't been defined or the theme hook hasn't been implemented, #markup and the rendered children are concatenated as the default output.

I'm not sure exactly what you're saying in #6...

It's true that if #type is not set, and #markup is, then #type is set to "markup" in drupal_render(). And this happens before the defaults are added from hook_element_info() for the #type. That should be mentioned if it isn't already in the documentation... and it isn't... actually the documentation doesn't even say that defaults are added from hook_element_info(), and it should.

It's also true that defaults for many elements set #theme; however, in Drupal 8, there is no default #theme for markup elements. So I don't think we need to worry about this in our discussion of #markup.

This is becoming "not a novice"... Oh I see you already removed that tag. Good!

Care to make a patch?

In Drupal 8, setting the type to 'markup' really doesn't do anything, since system_element_info() doesn't add a pre-render or anything else there. So I don't think you really need to worry about it.

And just as a note, #type is never overridden -- it is only set to 'markup' if it wasn't set previously.

So... Let's just document that:
- Elements without #type are set to type 'markup' if #markup is set.
- All elements have defaults from hook_element_info() added to them before any other processing.
- The main rendering step is normally done by calling theme() with the theme hook given in #theme.
- If #theme hasn't been defined or the theme hook hasn't been implemented, #markup and the rendered children are concatenated as the main rendering step output.

Maybe some clarification between the terminology of "element" vs. "renderable array" is also needed?

RE #11...
- In light of the first issue, we should now say that ... well I'm not sure because I don't quite understand what that issue does (it needs a change notice).
- In light of the second issue, we should not now say that #type is set to '#markup' if it is omitted. I guess that items without a #type are OK.

What a concept! I like the idea of #14.

Let's see if I like the details... I think it's mostly good, but I have a few suggestions:

a) I am not sure I would refer to "this element", since the input is $elements. Maybe it would be OK if there was an explanation that it refers to the outermost array of $elements at the beginning?

b) Third bullet point:

If this element has #type defined and the defaults attributes for this element have not already been merged in (#defaults_loaded = TRUE) then the defaults for this type of element, defined in hook_element_info() are merged into the array.

- "defaults attributes" should be "default attributes"
- missing comma after hook_element_info()
- you might want to note that #defaults_loaded is then set to TRUE so that the defaults are not merged again? ... or ... when/where does this actually happen? hmmm.

c) After #pre_render, #printed is checked again, which isn't in your list.

d) Detail: #theme is only used if #render_children is not set:

 if ($theme_is_implemented && !isset($elements['#render_children'])) {
 

Oh I see you mention this later on... I would mention it in each bullet point where it's relevant rather than getting to it later on.

e) Detail: drupal_render() is called on children either if #render_children is set or there wasn't a #theme or theme() returned FALSE indicating there was no theme function/template:

 if ((!$theme_is_implemented || isset($elements['#render_children'])) && empty($elements['#children'])) {

I also think I would mention that #children could have been set by pre-render or theme() at this point.

f) Typo in the #markup bullet point "if #theme is not an implemented" (remove "an").

g) In post_render, you might mention that #children is passed in, as opposed to many of the other steps, when $element is passed in as a whole.

h) At the end you might mention that #printed is set and that the result is cached if #cache is set.

I'm liking the way this is heading :)

- Any additional JavaScript, CSS or custom data is added to this elemnet.

Typo on element.

@thedavidmeister, your last paragraph in #16 might be a good candidate for a docs addition as well!

I think the documentation should not start out by referring to "each element" though. drupal_render renders one single $elements array (recursively, but still each time it is called, it is only dealing with one element really). When you say "each element", it sounds to me like a for loop.

I guess this is a problem with the existing drupal_render documentation...

Let's see.

What if the documentation read:

First line:
Renders a structured renderable array into HTML.

Then skip the next line in the current doc... and continue with this paragraph, which I think we still need:

 * Renderable arrays have two kinds of key/value pairs: properties and
 * children. Properties have keys starting with '#' and their values influence
 * how the array will be rendered. Children are all elements whose keys do not
 * start with a '#'. Their values should be renderable arrays themselves,
 * which will be rendered during the rendering of the parent array. The markup
 * provided by the children is typically inserted into the markup generated by
 * the parent array.

And then skip all the rest of what's there (up to the param/return section) and replace with:

The process of rendering an element is recursive. During each call to drupal_render(), the outermost renderable array (also known as an "element") is processed using the following steps:
[your list from #16]

I think the list in #16 of steps is looking pretty good. A few minor grammar/style/etc. cleanups to do:
- Typo mentioned in #17
- Don't say "FAPI" without defining what it is. Say "Form API" (3rd bullet point)
- Every list (or sub-list) needs to be preceded by a : -- so the 5th bullet point should end in "...element takes place:".
- i.e. and e.g. are almost always confused, almost always used wrong, and almost always punctuated wrong (as they are here). So I advise everyone to avoid them in drupal API docs... In the "special case" sub-list bullet point, can we say instead of "...even if #theme is an implemented theme hook, i.e. theme() will be bypassed." ==> "...implemented theme hook; that is, theme() will be bypassed."
- Some of the bullet points use grammatical structure like "If this element has an array of #post_render functions defined" or "If this element has #type defined ", whereas others have structure like "If #theme is defined". Can we make them all have the same grammatical structure? Pick one... I don't have a strong preference; both seem clear enough to me.

Wow, this is looking really good!

Just a couple of minor things I noticed:

a)

   - If this element has #theme defined and #theme is an implemented theme
      hook/suggestion then theme() is called and must render both the element
      and its children. If #render_children is set theme() will not be called.
    - If this element does not have a defined #theme or the defined #theme hook
      is not implemented and #children is empty then drupal_render() is called
      recursively on each of the child elements of this element and the result
      of each is concatenated onto #children.
    - If this element has #render_children set and #children is empty
      drupal_render() will recursively render child elements. In this case, even
      if #theme is an implemented theme hook, theme() will be bypassed.

This is still kind of hard to follow. The third bullet point here seems to be kind of redundant... Can we just say in the second bullet point perhaps:

   - If this element does not have a defined #theme, or the defined #theme hook
      is not implemented, or #render_children is set,  then drupal_render() is called
      recursively on each of the child elements of this element and the result
      of each is concatenated onto #children. This is skipped if #children is not empty at this point.

And leave out the third bullet?

b)

 - If this element has an array of #post_render functions defined, they are
    called sequentially to modify the rendered #children. Unlike #pre_render
    functions, #post_render functions are passed both the rendered #children
    attribute as a string and the render array.

At the very end I think we should say "element" instead of "render array"? The rest of the text refers to $elements as "the element".

Let's have a patch and get this in! Vast improvement over what was in drupal_render() previously.

Some minor readability points:

If #render_children is set theme() will not be called.

should have a comma after "set": "If #render_children is set, theme() will not be called."

If this element does not have a defined #theme, or the defined #theme hook is not implemented, or #render_children is set,  then drupal_render() is called recursively on each of the child elements of this element and the result of each is concatenated onto #children. This is skipped if #children is not empty at this point.

There's a double space after "set," and before "then drupal_render()...". Needs to be a single space.

If this element has an array of #theme_wrappers defined and #render_children is not set then #children is re-rendered by passing the element in its current state to theme() successively for each item in #theme_wrappers.

I'd rewrite this run-on sentence by replacing "then" with a comma: "If this element has an array of #theme_wrappers defined and #render_children is not set, #children is then re-rendered by passing the element in its current state to theme() successively for each item in #theme_wrappers."

If this element has #cache defined the rendered output of this element is saved to drupal_render()'s internal cache.

Same deal here, needs a comma after "defined".

I read through the entire patch, and I think this is in very good shape...

The only question I had was in this line near the bottom:

+ *   - Any additional JavaScript, CSS or custom data is added to this element.

Do we need to mention here what #properties are used to do this, in order to satisfy the current issue title's part "do not mention most of the base # attributes"? Or at least what function or functions are called to do this? Also, there should be a comma before "or" in this line.

then any required libraries,
+ *     JavaScript, CSS or other custom data

Any time there is a list with "and" or "or", our style standards require a serial comma before and/or.

In fact, I think you could also use commas in several other places:

+ *     - If this element does not have a defined #theme, or the defined #theme
+ *       hook is not implemented, or #render_children is set, then
+ *       drupal_render() is called recursively on each of the child elements of
+ *       this element and the result of each is concatenated onto #children.

(before the last "and"

+ *   - If this element has already been printed (#printed = TRUE) or the user
+ *     does not have access to it (#access = FALSE) then an empty string is
+ *     returned.

(before "then")

etc.

But if we're just quibbling over commas, this is pretty good... I think the whole thing overall reads very well and I'd be willing to commit it as-is, although I'd prefer a few more commas.

Great! Let's get this one in once the bot says "go". :)

Thanks for your hurculean effort on this, David!!!

Thank you again!!!!!!!!!!

I have committed this to 8.x. I think we should backport this change to 7.x. This is probably not just a straight reroll of the patch -- we need to read through the code to drupal_render() in 7.x and take out/alter any sections that do not apply to 7.x.

Actually I do not think the code is all that different. Just needs someone to read through this patched documentation vs. the D7 code and take out or modify the things that aren't correct.

Updated issue summary.

Back-port for D7.

Um... This patch doesn't look right to me. Why did you indent the cache section list? It was indented right before. And now the part about "If this element has an array of #pre_render functions defined..." is part of the caching list?

So this needs some work. The thing to do is probably to start over and go to Drupal 8 and copy the entire doc block for drupal_render(), and paste it into Drupal 7's doc block. Then remove or rewrite sections that do not apply to Drupal 7.

However, before we do that, I just noticed that the entire outer list in the Drupal 8 drupal_render() documentation is indented two spaces more than it should be:

 * The process of rendering an element is recursive unless the element defines
 * an implemented theme hook in #theme. During each call to drupal_render(), the
 * outermost renderable array (also known as an "element") is processed using
 * the following steps:
 *   - If this element has already been printed (#printed = TRUE) or the user
...

So can we have a patch that fixes that before we proceed to Drupal 7? Let's not change the wrapping, just indent that entire list (and sublists) back to the left by two spaces.

The drupal_render() is removed from 8.x core

It's been 7 years, I think we should spin off that formatting fixup into a separate issue. And either close this or backport to 7.x.

Yes, a followup is a good option. It is now created #3270081: Fix indentation in doc block \Drupal\Core\Render\RendererInterface::render.

This was committed to 8.x so changing the status to Fixed and restoring the version.

Thanks!