diff --git a/core/includes/update.inc b/core/includes/update.inc
index 5aff2bc..cf6e99c 100644
--- a/core/includes/update.inc
+++ b/core/includes/update.inc
@@ -1028,11 +1028,98 @@ 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 invoke 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 the schema of any module could be out of date. For
+ * this reason, caution is needed when using any API function within an update
+ * hook - particularly CRUD functions, functions that depend on the schema (for
+ * example by using drupal_write_record()), and any 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 function. The new utility function should be named
+ * _update_N_my_function() where N is the schema version the function acts on
+ * (the schema version is the number N from the hook_update_N() where this
+ * schema was introduced, or a number following the same numbering scheme), and
+ * my_function is the name of the original API function. The utility function
+ * should not invoke any hooks, and should perform database operations using
+ * functions from the @link database Database abstraction layer, @endlink like
+ * db_insert(), db_update(), db_delete(), db_query() and so on.
+ *
+ * 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.
+ *
+ * foo.install:
+ * @code
+ *   function foo_update_dependencies() {
+ *     // foo_update_8010() needs to run after bar_update_8000().
+ *     $dependencies['foo'][8010] = array(
+ *       'bar' => 8000,
+ *     );
+ *
+ *     // foo_update_8036() needs to run after bar_update_8001().
+ *     $dependencies['foo'][8036] = array(
+ *       'bar' => 8001,
+ *     );
+ *
+ *     return $dependencies;
+ *   }
+ *
+ *   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 foo_update_8010() {
+ *      // Since foo_update_8010() is going to run after bar_update_8000(), 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 foo_update_8036() {
+ *     // This update will run after bar_update_8001().
+ *     foreach (_update_8001_bar_get_types() as $type) {
+ *     }
+ *   }
+ * @endcode
+ *
+ * bar.install:
+ * @code
+ *   function bar_update_8000() {
+ *     // Type and bundle are confusing, so we renamed the table.
+ *     db_rename_table('bar_types', 'bar_bundles');
+ *   }
+ *
+ *   function bar_update_8001() {
+ *     // Whoops, db tables are singular when possible.
+ *     db_rename_table('bar_bundles', 'bar_bundle');
+ *   }
+ *
+ *   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()
+ * @see hook_update_dependencies()
  */
 
 /**
diff --git a/core/modules/system/system.api.php b/core/modules/system/system.api.php
index 3d2cae0..6f978ff 100644
--- a/core/modules/system/system.api.php
+++ b/core/modules/system/system.api.php
@@ -2897,6 +2897,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()
  */