diff --git a/core/includes/update.inc b/core/includes/update.inc
index f5e7a5e..b8e00af 100644
--- a/core/includes/update.inc
+++ b/core/includes/update.inc
@@ -986,11 +986,76 @@ function update_variables_to_config($config_name, array $variable_map) {
 /**
  * @defgroup update-api-7.x-to-8.x Update versions of API functions
  * @{
- * Functions similar to normal API function but not firing hooks.
+ * Functions that are similar to normal API functions, but do not fire hooks.
  *
- * During update, it is impossible to judge the consequences of firing a hook
- * as it might hit a module not yet updated. So simplified versions of some
- * core APIs are provided.
+ * These simplified versions of core API functions are provided for use by
+ * update hooks (hook_update_N()).
+ *
+ * During database updates, it is impossible to judge the consequences of
+ * firing a hook, because the schema of any given module could be out of date.
+ * For this reason, caution is needed when using any API function within an
+ * update hook - particularly CRUD functions and functions that invoke hooks.
+ * Instead, a simplified utility function should be used. If a utility version
+ * of the API function you require does not already exist, then you should
+ * create a new utility function named _update_N_my_function() where N is the
+ * schema version the function acts on, and my_function is the name of the
+ * original API function. The utility function should not fire any hooks.
+ *
+ * The names of these utility functions are based on the schema version of the
+ * module. If a change to the schema necessitates a change to the utility
+ * function, a new function should be created with a name based on the version
+ * of the schema it acts on. See update_8000_bar_get_types() and
+ * update_8001_bar_get_types() in the code example.
+ *
+ * Example:
+ * @code
+ *   function foo_update_8000() {
+ *     // No updates have been run on the {bar_types} table yet, so this needs
+ *     // to work with the 7.x schema.
+ *     foreach (update_7000_bar_get_types() as $type) {
+ *       // Rename a variable.
+ *     }
+ *   }
+ *
+ *   function bar_update_8000() {
+ *     // Type and bundle are confusing, so we renamed the table.
+ *     db_rename_table('bar_types', 'bar_bundles');
+ *   }
+ *
+ *   function foo_update_8010() {
+ *      // Since foo_update_8010() is going to run after bar_update_8000()
+ *      // (for whatever reason), it needs to operate on the new schema, not the
+ *      // old one.
+ *      foreach (update_8000_bar_get_types() as $type) {
+ *         // Rename a different variable.
+ *      }
+ *   }
+ *
+ *   function bar_update_8001() {
+ *     // Whoops, db tables are singular when possible.
+ *     db_rename_table('bar_bundles', 'bar_bundle');
+ *   }
+ *
+ *   function foo_update_8036() {
+ *     // This update will run after bar_update_8001().
+ *     foreach (update_8001_bar_get_types() as $type) {
+ *     }
+ *   }
+ *
+ *   function update_7000_bar_get_types() {
+ *     db_query('SELECT * FROM {bar_types}')->fetchAll();
+ *   }
+ *
+ *   function update_8000_bar_get_types() {
+ *     db_query('SELECT * FROM {bar_bundles'})->fetchAll();
+ *   }
+ *
+ *   function update_8001_bar_get_types() {
+ *     db_query('SELECT * FROM {bar_bundle}')->fetchAll();
+ *   }
+ * @endcode
+ *
+ * @see hook_update_N()
  */
 
 /**
diff --git a/core/modules/system/system.api.php b/core/modules/system/system.api.php
index 2223dec..a9fd54e 100644
--- a/core/modules/system/system.api.php
+++ b/core/modules/system/system.api.php
@@ -2899,6 +2899,7 @@ function hook_install() {
  *
  * @see batch
  * @see schemaapi
+ * @see update-api-7.x-to-8.x
  * @see hook_update_last_removed()
  * @see update_get_update_list()
  */