Index: modules/system/system.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.api.php,v
retrieving revision 1.187
diff -u -r1.187 system.api.php
--- modules/system/system.api.php	22 Aug 2010 13:55:53 -0000	1.187
+++ modules/system/system.api.php	31 Aug 2010 16:21:25 -0000
@@ -3642,26 +3642,35 @@
 /**
  * Provide replacement values for placeholder tokens.
  *
+ * This hook is invoked when someone calls token_replace(). That function first
+ * scans the text for [type:token] patterns, and splits the needed tokens into
+ * groups by type. Then hook_tokens() is invoked on each token-type group,
+ * allowing your module to respond by providing replacement text for any of
+ * the tokens in the group that your module knows how to process.
+ *
+ * A module implementing this hook should also implement hook_token_info() in
+ * order to list its available tokens on editing screens.
+ *
  * @param $type
- *   The type of token being replaced. 'node', 'user', and 'date' are common.
+ *   The machine-readable name of the type (group) of token being replaced, such
+ *   as 'node', 'user', or another type defined by a hook_token_info()
+ *   implementation.
  * @param $tokens
- *   An array of tokens to be replaced, keyed by the literal text of the token
- *   as it appeared in the source text.
+ *   An array of tokens to be replaced. The keys are the machine-readable token
+ *   names, and the values are the raw [type:token] strings that appeared in the
+ *   original text.
  * @param $data
- *   (optional) An associative array of objects to be used when generating replacement
- *   values.
+ *   (optional) An associative array of data objects to be used when generating
+ *   replacement values, as supplied in the $data parameter to token_replace().
  * @param $options
- *   (optional) A associative array of options to control the token
- *   replacement process. Common options are:
- *   - 'language' A language object to be used when generating locale-sensitive
- *     tokens.
- *   - 'sanitize' A boolean flag indicating that tokens should be sanitized for
- *     display to a web browser.
+ *   (optional) An associative array of options for token replacement; see
+ *   token_replace() for possible values.
  *
  * @return
- *   An associative array of replacement values, keyed by the original 'raw'
- *   tokens that were found in the source text. For example:
- *   $results['[node:title]'] = 'My new node';
+ *   An associative array of replacement values, keyed by the raw [type:token]
+ *   strings from the original text.
+ *
+ * @see hook_token_info()
  */
 function hook_tokens($type, $tokens, array $data = array(), array $options = array()) {
   $url_options = array('absolute' => TRUE);
@@ -3720,14 +3729,48 @@
 }
 
 /**
- * Provide metadata about available placeholder tokens and token types.
+ * Provide information about available placeholder tokens and token types.
+ *
+ * Tokens are placeholders that can be put into text by using the syntax
+ * [type:token], where type is the machine-readable name of a token type, and
+ * token is the machine-readable name of a token within this group. This hook
+ * provides a list of types and tokens to be displayed on text editing screens,
+ * so that people editing text can see what their token options are.
+ *
+ * The actual token replacement is done by token_replace(), which invokes
+ * hook_tokens(). Your module will need to implement that hook in order to
+ * generate token replacements from the tokens defined here.
  *
  * @return
- *   An associative array of available tokens and token types, each containing
- *   the raw name of the token or type, its user-friendly name, and a verbose
- *   description.
+ *   An associative array of available tokens and token types. The outer array
+ *   has two components:
+ *   - types: An associative array of token types (groups). Each token type is
+ *     an associative array with the following components:
+ *     - name: The translated human-readable short name of the token type.
+ *     - description: A translated longer description of the token type.
+ *     - needs-data: The type of data that must be provided to token_replace()
+ *       in the $data argument (i.e., the key name in $data) in order for tokens
+ *       of this type to be used in the $text being processed. For instance, if
+ *       the token needs a node object, 'needs-data' should be 'node', and to
+ *       use this token in token_replace(), the caller needs to supply a node
+ *       object as $data['node']. Some token data can also be supplied
+ *       indirectly; for instance, a node object in $data supplies a user object
+ *       (the author of the node), allowing user tokens to be used when only
+ *       a node data object is supplied.
+ *   - tokens: An associative array of tokens. The outer array is keyed by the
+ *     group name (the same key as in the types array). Within each group of
+ *     tokens, each token item is keyed by the machine name of the token, and
+ *     each token item has the following components:
+ *     - name: The translated human-readable short name of the token.
+ *     - description: A translated longer description of the token.
+ *     - type (optional): A 'needs-data' data type supplied by this token, which
+ *       should match a 'needs-data' value from another token type. For example,
+ *       the node author token provides a user object, which can then be used
+ *       for token replacement data in token_replace() without having to supply
+ *       a separate user object.
  *
  * @see hook_token_info_alter()
+ * @see hook_tokens()
  */
 function hook_token_info() {
   $type = array(