diff -u b/core/modules/system/system.api.php b/core/modules/system/system.api.php
--- b/core/modules/system/system.api.php
+++ b/core/modules/system/system.api.php
@@ -1230,13 +1230,13 @@
 }
 
 /**
- * Declare a template file extension to be used with a theme engine
+ * Declares a template file extension to be used with a theme engine.
  *
  * This hook is used in a theme engine implementation in the format of
- * ENGINE_extension()
+ * ENGINE_extension().
  *
  * @return string
- *  The file extension the theme engine will recognize
+ *   The file extension the theme engine will recognize.
  */
 function hook_extension() {
   // Extension for template base names in Twig
@@ -1247,18 +1247,22 @@
  * Renders a template using the theme engine.
  *
  * This hook is used in a theme engine implementation in the format of
- * ENGINE_render_template()
- * Here the theme engine takes care of rendering the contents of a template with the
- * provided variables.
- *
- * @param $template_file
- *   The file name of the template to render.
- * @param $variables
- *   A keyed array of variables that will appear in the output.
+ * ENGINE_render_template(). It gets passed a template name and an array of
+ * variables and returns a string containing the rendered template.
+ *
+ * @param string template_file
+ *   The relative path to the template to be rendered including its extension in
+ *   the format 'path/to/TEMPLATE_NAME.EXT'. The path should be relative to the
+ *   drupal root directory.
+ * @param array $variables
+ *   A keyed array of variables that are available for composing the output. The
+ *   theme engine is responsible for passing all the variables to the template.
+ *   If all or just a subset of those variables are used in the template may
+ *   vary depending on the code in the template.
  *
  * @return string
- *   The output generated by the template. In most cases this will be a string
- *   containing HTML markup
+ *   The output generated from the template. In most cases this will be a string
+ *   containing HTML markup.
  */
 function hook_render_template($template_file, $variables) {
   $twig_service = \Drupal::service('twig');