Issue #1134088 by Cottser, catch: Properly document update-api functions

6 files changed, 129 insertions, 8 deletions

diff --git a/modules/field/field.install b/modules/field/field.install
index 5934a264c..34d28073d 100644
--- a/modules/field/field.install
+++ b/modules/field/field.install
@@ -172,7 +172,7 @@ function field_schema() {
  * This function can be used for databases whose schema is at field module
  * version 7000 or higher.
  *
- * @ingroup update-api-6.x-to-7.x
+ * @ingroup update_api
  */
 function _update_7000_field_create_field(&$field) {
   // Merge in default values.`
@@ -253,7 +253,7 @@ function _update_7000_field_create_field(&$field) {
  * @param $field_name
  *   The field name to delete.
  *
- * @ingroup update-api-6.x-to-7.x
+ * @ingroup update_api
  */
 function _update_7000_field_delete_field($field_name) {
   $table_name = 'field_data_' . $field_name;
@@ -284,7 +284,7 @@ function _update_7000_field_delete_field($field_name) {
  *
  * This function is valid for a database schema version 7000.
  *
- * @ingroup update-api-6.x-to-7.x
+ * @ingroup update_api
  */
 function _update_7000_field_delete_instance($field_name, $entity_type, $bundle) {
   // Delete field instance configuration data.
@@ -322,6 +322,8 @@ function _update_7000_field_delete_instance($field_name, $entity_type, $bundle)
  * @return
  *   An array of fields matching $conditions, keyed by the property specified
  *   by the $key parameter.
+ *
+ * @ingroup update_api
  */
 function _update_7000_field_read_fields(array $conditions = array(), $key = 'id') {
   $fields = array();
@@ -356,7 +358,7 @@ function _update_7000_field_read_fields(array $conditions = array(), $key = 'id'
  * This function can be used for databases whose schema is at field module
  * version 7000 or higher.
  *
- * @ingroup update-api-6.x-to-7.x
+ * @ingroup update_api
  */
 function _update_7000_field_create_instance($field, &$instance) {
   // Merge in defaults.
diff --git a/modules/field/modules/field_sql_storage/field_sql_storage.install b/modules/field/modules/field_sql_storage/field_sql_storage.install
index 78c520fcf..24973ab45 100644
--- a/modules/field/modules/field_sql_storage/field_sql_storage.install
+++ b/modules/field/modules/field_sql_storage/field_sql_storage.install
@@ -30,7 +30,7 @@ function field_sql_storage_schema() {
  * This function can be used for databases whose schema is at field module
  * version 7000 or higher.
  *
- * @ingroup update-api-6.x-to-7.x
+ * @ingroup update_api
  */
 function _update_7000_field_sql_storage_write($entity_type, $bundle, $entity_id, $revision_id, $field_name, $data) {
   $table_name = "field_data_{$field_name}";
diff --git a/modules/node/node.install b/modules/node/node.install
index 434410c8d..16d3dbaa0 100644
--- a/modules/node/node.install
+++ b/modules/node/node.install
@@ -474,7 +474,7 @@ function node_update_dependencies() {
  *
  * This function is valid for a database schema version 7000.
  *
- * @ingroup update-api-6.x-to-7.x
+ * @ingroup update_api
  */
 function _update_7000_node_get_types() {
   $node_types = db_query('SELECT * FROM {node_type}')->fetchAllAssoc('type', PDO::FETCH_OBJ);
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index fe087415a..6ed576696 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -3309,6 +3309,13 @@ function hook_install() {
  * In order to call a function from your mymodule.module or an include file,
  * you need to explicitly load that file first.
  *
+ * 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
+ * function - particularly CRUD functions, functions that depend on the schema
+ * (for example by using drupal_write_record()), and any functions that invoke
+ * hooks. See @link update_api Update versions of API functions @endlink for
+ * details.
+ *
  * If your update task is potentially time-consuming, you'll need to implement a
  * multipass update to avoid PHP timeouts. Multipass updates use the $sandbox
  * parameter provided by the batch API (normally, $context['sandbox']) to store
@@ -3333,6 +3340,7 @@ function hook_install() {
  *
  * @see batch
  * @see schemaapi
+ * @see update_api
  * @see hook_update_last_removed()
  * @see update_get_update_list()
  */
@@ -4656,3 +4664,114 @@ function hook_filetransfer_info_alter(&$filetransfer_info) {
 /**
  * @} End of "addtogroup hooks".
  */
+
+/**
+ * @defgroup update_api Update versions of API functions
+ * @{
+ * Functions that are similar to normal API functions, but do not invoke hooks.
+ *
+ * These simplified versions of core API functions are provided for use by
+ * update functions (hook_update_N() implementations).
+ *
+ * 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
+ * function - 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_mymodule_my_function(). N is the schema version the function acts
+ * on (the schema version is the number N from the hook_update_N()
+ * implementation where this schema was introduced, or a number following the
+ * same numbering scheme), and mymodule_my_function is the name of the original
+ * API function including the module's name.
+ *
+ * Examples:
+ * - _update_6000_mymodule_save(): This function performs a save operation
+ *   without invoking any hooks using the 6.x schema.
+ * - _update_7000_mymodule_save(): This function performs the same save
+ *   operation using the 7.x schema.
+ *
+ * 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_7000_bar_get_types() and _update_7001_bar_get_types()
+ * in the code examples that follow.
+ *
+ * For example, foo.install could contain:
+ * @code
+ * function foo_update_dependencies() {
+ *   // foo_update_7010() needs to run after bar_update_7000().
+ *   $dependencies['foo'][7010] = array(
+ *     'bar' => 7000,
+ *   );
+ *
+ *   // foo_update_7036() needs to run after bar_update_7001().
+ *   $dependencies['foo'][7036] = array(
+ *     'bar' => 7001,
+ *   );
+ *
+ *   return $dependencies;
+ * }
+ *
+ * function foo_update_7000() {
+ *   // No updates have been run on the {bar_types} table yet, so this needs
+ *   // to work with the 6.x schema.
+ *   foreach (_update_6000_bar_get_types() as $type) {
+ *     // Rename a variable.
+ *   }
+ * }
+ *
+ * function foo_update_7010() {
+ *    // Since foo_update_7010() is going to run after bar_update_7000(), it
+ *    // needs to operate on the new schema, not the old one.
+ *    foreach (_update_7000_bar_get_types() as $type) {
+ *      // Rename a different variable.
+ *    }
+ * }
+ *
+ * function foo_update_7036() {
+ *   // This update will run after bar_update_7001().
+ *   foreach (_update_7001_bar_get_types() as $type) {
+ *   }
+ * }
+ * @endcode
+ *
+ * And bar.install could contain:
+ * @code
+ * function bar_update_7000() {
+ *   // Type and bundle are confusing, so we renamed the table.
+ *   db_rename_table('bar_types', 'bar_bundles');
+ * }
+ *
+ * function bar_update_7001() {
+ *   // Database table names should be singular when possible.
+ *   db_rename_table('bar_bundles', 'bar_bundle');
+ * }
+ *
+ * function _update_6000_bar_get_types() {
+ *   db_query('SELECT * FROM {bar_types}')->fetchAll();
+ * }
+ *
+ * function _update_7000_bar_get_types() {
+ *   db_query('SELECT * FROM {bar_bundles'})->fetchAll();
+ * }
+ *
+ * function _update_7001_bar_get_types() {
+ *   db_query('SELECT * FROM {bar_bundle}')->fetchAll();
+ * }
+ * @endcode
+ *
+ * @see hook_update_N()
+ * @see hook_update_dependencies()
+ */
+
+/**
+ * @} End of "defgroup update_api".
+ */
diff --git a/modules/taxonomy/taxonomy.install b/modules/taxonomy/taxonomy.install
index 711a0f983..c353c9c8c 100644
--- a/modules/taxonomy/taxonomy.install
+++ b/modules/taxonomy/taxonomy.install
@@ -266,7 +266,7 @@ function taxonomy_update_dependencies() {
  *
  * This function is valid for a database schema version 7002.
  *
- * @ingroup update-api-6.x-to-7.x
+ * @ingroup update_api
  */
 function _update_7002_taxonomy_get_vocabularies() {
   return db_query('SELECT v.* FROM {taxonomy_vocabulary} v ORDER BY v.weight, v.name')->fetchAllAssoc('vid', PDO::FETCH_OBJ);
diff --git a/modules/user/user.install b/modules/user/user.install
index 217577de7..cff873a45 100644
--- a/modules/user/user.install
+++ b/modules/user/user.install
@@ -384,7 +384,7 @@ function user_update_dependencies() {
  *   An array of permissions names.
  * @param $module
  *   The name of the module defining the permissions.
- * @ingroup update-api-6.x-to-7.x
+ * @ingroup update_api
  */
 function _update_7000_user_role_grant_permissions($rid, array $permissions, $module) {
   // Grant new permissions for the role.