diff --git a/includes/cache.inc b/includes/cache.inc
index 1e70960..d60f49f 100644
--- a/includes/cache.inc
+++ b/includes/cache.inc
@@ -57,38 +57,51 @@ function cache_get($cid, $table = 'cache') {
 }
 
 /**
- * Store data in the persistent cache.
+ * Stores data in the persistent cache.
  *
- * The persistent cache is split up into four database
- * tables. Contributed modules can add additional tables.
+ * The persistent cache is split up into several cache bins. In the default
+ * cache implementation, each cache bin corresponds to a database table by the
+ * same name. Other implementations might want to store several bins in data
+ * structures that get flushed together. While it is not a problem for most
+ * cache bins if the entries in them are flushed before their expire time, some
+ * might break functionality or are extremely expensive to recalculate. The
+ * other bins are expired automatically by core. Contributed modules can add
+ * additional bins and get them expired automatically by implementing
+ * hook_flush_caches().
  *
- * 'cache_page': This table stores generated pages for anonymous
- * users. This is the only table affected by the page cache setting on
- * the administrator panel.
- *
- * 'cache_menu': Stores the cachable part of the users' menus.
- *
- * 'cache_filter': Stores filtered pieces of content. This table is
- * periodically cleared of stale entries by cron.
- *
- * 'cache': Generic cache storage table.
- *
- * The reasons for having several tables are as follows:
- *
- * - smaller tables allow for faster selects and inserts
- * - we try to put fast changing cache items and rather static
- *   ones into different tables. The effect is that only the fast
- *   changing tables will need a lot of writes to disk. The more
- *   static tables will also be better cachable with MySQL's query cache
+ * The reasons for having several bins are as follows:
+ * - Smaller bins mean smaller database tables and allow for faster selects and
+ *   inserts.
+ * - We try to put fast changing cache items and rather static ones into
+ *   different bins. The effect is that only the fast changing bins will need a
+ *   lot of writes to disk. The more static bins will also be better cacheable
+ *   with MySQL's query cache.
  *
  * @param $cid
  *   The cache ID of the data to store.
  * @param $data
- *   The data to store in the cache. Complex data types will be automatically serialized before insertion.
- *   Strings will be stored as plain text and not serialized.
- * @param $table
- *   The table $table to store the data in. Valid core values are 'cache_filter',
- *   'cache_menu', 'cache_page', or 'cache'.
+ *   The data to store in the cache. Complex data types will be automatically
+ *   serialized before insertion. Strings will be stored as plain text and are
+ *   not serialized.
+ * @param $bin
+ *   The cache bin to store the data in. Valid core values are:
+ *   - cache: (default) Generic cache storage bin (used for theme registry,
+ *     locale date, list of simpletest tests, etc.).
+ *   - cache_block: Stores the content of various blocks.
+ *   - cache_bootstrap: Stores the class registry, the system list of modules,
+ *     the list of which modules implement which hooks, and the Drupal variable
+ *     list.
+ *   - cache_field: Stores the field data belonging to a given object.
+ *   - cache_filter: Stores filtered pieces of content.
+ *   - cache_form: Stores multistep forms. Flushing this bin means that some
+ *     forms displayed to users lose their state and the data already submitted
+ *     to them. This bin should not be flushed before its expired time.
+ *   - cache_menu: Stores the structure of visible navigation menus per page.
+ *   - cache_page: Stores generated pages for anonymous users. It is flushed
+ *     very often, whenever a page changes, at least for every node and comment
+ *     submission. This is the only bin affected by the page cache setting on
+ *     the administrator panel.
+ *   - cache_path: Stores the system paths that have an alias.
  * @param $expire
  *   One of the following values:
  *   - CACHE_PERMANENT: Indicates that the item should never be removed unless
@@ -97,10 +110,9 @@ function cache_get($cid, $table = 'cache') {
  *     general cache wipe.
  *   - A Unix timestamp: Indicates that the item should be kept at least until
  *     the given time, after which it behaves like CACHE_TEMPORARY.
- * @param $headers
- *   A string containing HTTP header information for cached pages.
  *
- *   @see cache_get()
+ * @see _update_cache_set()
+ * @see cache_get()
  */
 function cache_set($cid, $data, $table = 'cache', $expire = CACHE_PERMANENT, $headers = NULL) {
   $serialized = 0;