Index: modules/user/user.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.api.php,v
retrieving revision 1.25
diff -u -p -r1.25 user.api.php
--- modules/user/user.api.php	23 Oct 2010 15:30:34 -0000	1.25
+++ modules/user/user.api.php	29 Nov 2010 18:59:20 -0000
@@ -38,6 +38,9 @@ function hook_user_load($users) {
  * removed from the user tables in the database, and before
  * field_attach_delete() is called.
  *
+ * Modules should additionally implement hook_user_cancel() to process stored
+ * user data for other account cancellation methods.
+ *
  * @param $account
  *   The account that is being deleted.
  *
@@ -52,11 +55,17 @@ function hook_user_delete($account) {
 /**
  * Act on user account cancellations.
  *
- * The user account is being canceled. Depending on the account cancellation
- * method, the module should either do nothing, unpublish content, or anonymize
- * content.
+ * This hook is invoked from user_cancel() before a user account is canceled.
+ * Depending on the account cancellation method, the module should either do
+ * nothing, unpublish content, or anonymize content. See user_cancel_methods()
+ * for the list of default account cancellation methods provided by User module.
+ * Modules may add further methods via hook_user_cancel_methods_alter().
+ *
+ * This hook is NOT invoked for the 'user_cancel_delete' account cancellation
+ * method. To react on this method, implement hook_user_delete() instead.
  *
- * Expensive operations should be added to the global batch with batch_set().
+ * Expensive operations should be added to the global account cancellation batch
+ * by using batch_set().
  *
  * @param $edit
  *   The array of form values submitted by the user.
@@ -67,7 +76,6 @@ function hook_user_delete($account) {
  *
  * @see user_cancel_methods()
  * @see hook_user_cancel_methods_alter()
- * @see user_cancel()
  */
 function hook_user_cancel($edit, $account, $method) {
   switch ($method) {
Index: modules/user/user.pages.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.pages.inc,v
retrieving revision 1.77
diff -u -p -r1.77 user.pages.inc
--- modules/user/user.pages.inc	24 Nov 2010 03:21:36 -0000	1.77
+++ modules/user/user.pages.inc	29 Nov 2010 18:44:52 -0000
@@ -453,7 +453,7 @@ function user_cancel_confirm_form_submit
 /**
  * Helper function to return available account cancellation methods.
  *
- * Please refer to the documentation of hook_user_cancel_methods_alter().
+ * See documentation of hook_user_cancel_methods_alter().
  *
  * @return
  *   An array containing all account cancellation methods as form elements.