diff --git drush.api.php drush.api.php
index 56c2091..8a92c76 100644
--- drush.api.php
+++ drush.api.php
@@ -3,7 +3,41 @@
 
 /**
  * @file
- * Documentation for Drush.
+ * Documentation of the Drush API.
+ *
+ * All drush commands are invoked in a specific order, using
+ * drush-made hooks, very similar to the Drupal hook system.
+ *
+ * For any command named "hook", the following hooks are called, in
+ * order:
+ *
+ * 1. drush_module_hook_validate()
+ * 2. drush_module_pre_hook()
+ * 3. drush_module_hook()
+ * 4. drush_module_post_hook()
+ *
+ * If any of those fails, the rollback mechanism is called. It will
+ * call, in reverse, all _rollback hooks. So if, for example, the
+ * drush_post_hook() call fails, the following hooks will be called:
+ *
+ * 1. drush_module_post_hook_rollback()
+ * 2. drush_module_hook_rollback()
+ * 3. drush_module_pre_hook_rollback()
+ * 4. drush_module_hook_validate_rollback()
+ *
+ * Before any command is called, drush_hook_init() is also called.
+ *
+ * @see includes/command.inc
+ *
+ * @see drush_hook_init()
+ * @see drush_hook_validate()
+ * @see drush_pre_hook()
+ * @see drush_hook()
+ * @see drush_post_hook()
+ * @see drush_post_hook_rollback()
+ * @see drush_hook_rollback()
+ * @see drush_pre_hook_rollback()
+ * @see drush_hook_validate_rollback()
  */
 
 /**
@@ -22,9 +56,11 @@ function hook_drush_init() {
  * Run before a specific command executes. 
  * 
  * Logging an error stops command execution, and the rollback function (if any)
- * for each hook implementation is invoked - hook_COMMAND_validate_rollback().
+ * for each hook implementation is invoked
+ *
+ * @see drush_hook_command_validate_rollback()
  */
-function hook_COMMAND_validate() {
+function drush_hook_command_validate() {
 
 }
 
@@ -32,9 +68,30 @@ function hook_COMMAND_validate() {
  * Run before a specific command executes. Logging an error stops command execution.
  *
  * Logging an error stops command execution, and the rollback function (if any)
- * for each hook implementation is invoked - hook_pre_COMMAND_rollback().
+ * for each hook implementation is invoked, in addition to the
+ * validate rollback
+ *
+ * @see drush_hook_pre_command_rollback()
+ * @see drush_hook_command_validate_rollback()
+ */
+function drush_hook_pre_command() {
+
+}
+
+/**
+ * Implementation of the actual drush command
+ *
+ * This is where most of the stuff should happen
+ *
+ * Logging an error stops command execution, and the rollback function (if any)
+ * for each hook implementation is invoked, in addition to pre and
+ * validate rollbacks.
+ *
+ * @see drush_hook_command_rollback()
+ * @see drush_hook_pre_command_rollback()
+ * @see drush_hook_command_validate_rollback()
  */
-function hook_pre_COMMAND() {
+function drush_hook_command() {
 
 }
 
@@ -42,9 +99,15 @@ function hook_pre_COMMAND() {
  * Run after a specific command executes. Logging an error stops command execution.
  * 
  * Logging an error stops command execution, and the rollback function (if any)
- * for each hook implementation is invoked - hook_post_COMMAND_rollback().
+ * for each hook implementation is invoked, in addition to pre, normal
+ * and validate rollbacks.
+ *
+ * @see drush_hook_post_command_rollback()
+ * @see drush_hook_command_rollback()
+ * @see drush_hook_pre_command_rollback()
+ * @see drush_hook_command_validate_rollback()
  */
-function hook_post_COMMAND() {
+function drush_hook_post_command() {
 
 }
 
@@ -69,10 +132,6 @@ function hook_pm_post_update($release_name, $release_candidate_version, $project
 
 }
 
-
-
-
-
 /**
  * @} End of "addtogroup hooks".
  */