Update API documentation for _theme() to clearly indicate that it is for internal use only

Tagging for rocketship. Thanks @xjm!

Patch attached which melds the existing relevant paragraph with additional details provided in issue summary.

This looks pretty good. The only thing I was not sure about was the first sentence:

+ * Avoid calling this function directly as it raises several issues:

This doesn't seem quite strong enough. I think rather than "avoid calling" we should say "Don't call", and rather than "raises several issues" we need to get across the concept of "doesn't work" explicitly?

I also wonder if at the end we should mention just returning a renderable array wherever possible rather than even having to call drupal_render() explicitly?

I reworded the paragraph to be even stronger.

Oops, it's a function, not a method.

I've adapted patch from #8 with some changes.

• I find the itemised list more readable, rather than a run-on sentence.
• A problem was omitted from the list - "Circumvents defaults of types provided by hook_element_info(), including attached assets."

The other documentation on theme() or _theme() is a description of all of the hooks that are called during theming/rendering. It seems like a logical place to move this might be to drupal_render(), or else to a @defgroup/topic might be even better?

We do not currently have a topic for the theme or render system, but on #2148255: [meta] Make better D8 api.d.o landing page, linked to high-level overview topics, and put it in Core api.php files a skeleton topic is proposed. That would be a good place to put this information (and, hint hint, that patch needs a review!).

For the purposes of this particular issue, the changes in #9 should be satisfactory. The change clearly states that _theme() should not be called directly and then explains the consequences of calling it directly.

I agree with jhodgdon in #12 that a good hunk of the _theme() docblock is poorly located. We shouldn't have usage information associated with the function that we recommend not be called directly. The docs are accurate, just poorly placed. But the poor placement should not be considered a beta blocker. Moving the doc is just a normal task. I've created that issue to address it:

#2215587: _theme() is now an internal function; Move the Theming documentation to a better-suited page in the documentation

The attached patch addresses xjm's comment in #10 about the lingering "however" in the docblock.

So, changing the bit of text mentioned in #15 was quite the thread in a sweater or, the veritable giving a mouse a cookie. I ended up having to move _theme() function doc block over to theme.api.php in order to have the text make any sense. Which means we can effectively close #2215587: _theme() is now an internal function; Move the Theming documentation to a better-suited page in the documentation.

Yes, that's much more direct.

Since _theme() is for internal use, do you think it would make sense to change its first-line summary from "Generates themed output." to something like "Generates themed output (internal use only)."? I'm OK either way, but if you are striving for clarity on this point...

Another thing to fix: In the theme.api.php section of the patch, you're patching the topic for @defgroup themeable.

So ... a ways down, it says:

+ * @section sec_theme_hooks Theme Hooks
+ * Most commonly, the first argument to this function is the name of the theme
+ * hook. For instance, to theme a taxonomy term, the theme hook name is
...

That was taken from the old theme() docs, where it made sense, but here it doesn't, because we're not using a call to theme(), we're using a #theme element in a render array.

There are probably some more things that need fixing... I need to run off but I don't think we want to just blindly copy/paste this text from theme() into this new location. Sigh.

Oh, one more thing that we can't commit this with: in the _theme() docs, it says:

+ * All requests for themed output must go through this function, which is
+ * invoked as part of the @link theme_render drupal_render() process @endlink.

I do not think this topic "theme_render" exists anywhere in core. Were you going to create it (at least as a stub)?

I pulled theme_render from #2148255: [meta] Make better D8 api.d.o landing page, linked to high-level overview topics, and put it in Core api.php files, which is now RTBC.

Since _theme() is for internal use, do you think it would make sense to change its first-line summary from "Generates themed output." to something like "Generates themed output (internal use only)."?

Yes, I support completely any language that discourages use of _theme() in modules or themes. When I started using Drupal, I was very confused about whether I should use drupal_render() or theme(). We need very clear documentation about _theme() -- that it should not be used by contrib developers.

The changes in this patch should hopefully discourage the direct use of _theme() while explaining the concepts of theme hooks, templates and overrides.

I think this looks really good. There's a small wrapping issue in the theme.api.php segment of the patch:

+ * To invoke a theme implementation on a renderable array, define a key named
+ * '#theme' and assign it a string value that is the name of a
+ * theme hook. Any variables that the theme hook requires
+ * may be supplied as additional keys -- prepended with a '#' character -- in
+ * the renderable array.

(should be wrapped closer to 80 characters) but I would be OK with this going in without fixing this if we need to get this critical in.

Easy enough to fix right now :)

Thanks! Let's get this in then.

Excellent work. Another beta blocker bites the dust, and docs are improved along the way!

Committed and pushed to 8.x. Thanks!