#989366 by jhodgdon: Improved documentation of hook_date_formats()

includes/common.inc

@@ -1830,7 +1830,8 @@ function format_interval($timestamp, $granularity = 2, $langcode = NULL) {
  * @param $type
  *   (optional) The format to use, one of:
  *   - 'short', 'medium', or 'long' (the corresponding built-in date formats).
- *   - The name of a date type defined by a module in hook_date_format_types().
+ *   - The name of a date type defined by a module in hook_date_format_types(),
+ *     if it's been assigned a format.
  *   - The machine name of an administrator-defined date format.
  *   - 'custom', to use $format.
  *   Defaults to 'medium'.

modules/system/system.api.php

@@ -3718,8 +3718,14 @@ function hook_archiver_info_alter(&$info) {
  *
  * Next to the 'long', 'medium' and 'short' date types defined in core, any
  * module can define additional types that can be used when displaying dates. A
- * date type is a key which can be passed to format_date() to return a date in
- * the configured display format.
+ * date type is a key that can be passed to format_date() to return a date in
+ * the configured display format, once a format has been assigned to it. To
+ * assign a format to a date type, use
+ * @code variable_set('date_format_' . $type, $format); @endcode
+ * where $type is the machine-readable name defined here, and $format is a PHP
+ * date format string. This can also be done in the administrative interface,
+ * which allows date types defined here to be associated with date format
+ * strings defined in hook_date_formats().
  *
  * To avoid namespace collisions with date types defined by other modules, it is
  * recommended that each date type starts with the module name. A date type