diff --git a/core/includes/update.inc b/core/includes/update.inc
index 762e1ae..ca599b8 100644
--- a/core/includes/update.inc
+++ b/core/includes/update.inc
@@ -1033,23 +1033,26 @@ function update_variables_to_config($config_name, array $variable_map) {
  * 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
- * invoking 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.
+ * 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 utility function 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.
+ * 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.
  *
- * 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.
+ * 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
@@ -1076,9 +1079,8 @@ function update_variables_to_config($config_name, array $variable_map) {
  *   }
  *
  *   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.
+ *      // 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.
  *      }
@@ -1117,6 +1119,7 @@ function update_variables_to_config($config_name, array $variable_map) {
  * @endcode
  *
  * @see hook_update_N()
+ * @see hook_update_dependencies()
  */
 
 /**