Index: includes/theme.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/theme.inc,v
retrieving revision 1.569
diff -u -p -r1.569 theme.inc
--- includes/theme.inc	13 Jan 2010 05:40:03 -0000	1.569
+++ includes/theme.inc	22 Jan 2010 16:15:50 -0000
@@ -1406,6 +1406,52 @@ function theme_link($variables) {
 /**
  * Return a themed set of links.
  *
+ * As with all theme functions, a theme can override this function to customize
+ * the markup for a set of links. In addition to overriding the output of all
+ * sets of links via a THEMENAME_links() function, a theme may override the
+ * output of a specific set of links with a more targeted function. The
+ * following functions may be used to customize sets of links generated by core
+ * Drupal modules:
+ * - THEMENAME_links__blog_node(): for the set of links added by the blog module
+ *   to nodes of the blog type.
+ * - THEMENAME_links__book_node(): for the set of links added by the book module
+ *   to nodes that are part of a book.
+ * - THEMENAME_links__comment(): for the set of links added to comments.
+ * - THEMENAME_links__comment_node(): for the set of links added by the comment
+ *   module to nodes which contain comments or for which comments can be added.
+ * - THEMENAME_links__contextual(): for the set of links added by the contextual
+ *   module to various elements (blocks, menus, nodes, and others) for
+ *   performing actions related to that element.
+ * - THEMENAME_links__locale_block(): for the set of links added by the locale
+ *   module to the language switcher block.
+ * - THEMENAME_links__node(): for the set of links added to nodes.
+ * - THEMENAME_links__node_operations(): for the set of links in each row of the
+ *   "Operations" column of the node administration table on the "admin/content"
+ *   page.
+ * - THEMENAME_links__poll_results(): for the set of links displayed by the poll
+ *   module when viewing a poll.
+ * - THEMENAME_links__statistics_node(): for the set of links added by the
+ *   statistics module to nodes.
+ * - THEMENAME_links__system_main_menu(): for the main menu displayed on a page.
+ * - THEMENAME_links__system_secondary_menu(): for the secondary menu displayed
+ *   on a page.
+ * - THEMENAME_links__toolbar_menu(): for the set of links in the left portion
+ *   of the toolbar (by default) for navigating to Drupal's main administrative
+ *   areas.
+ * - THEMENAME_links__toolbar_user(): for the set of links in the right portion
+ *   of the toolbar (by default) for performing user-related actions, such as
+ *   logging out.
+ * - THEMENAME_links__translation_node(): for the set of links added by the
+ *   translation module to nodes that are part of a translation set.
+ * - THEMENAME_links__update_version(): for the set of links for performing
+ *   actions related to a Drupal project version displayed by the update module
+ *   on the "admin/report/updates" page.
+ *
+ * Additional modules installed that are not part of core Drupal may support
+ * additional targeted overrides related to sets of links that they generate.
+ * These should follow the same convention as above: either 'links__MODULENAME'
+ * or 'links__MODULENAME_EXTRA_CONTEXT'.
+ *
  * @param $variables
  *   An associative array containing:
  *   - links: A keyed array of links to be themed. The key for each link is used