Issue #1156576 by pixelite, Ryan Weal, jhodgdon, plach, Albert Volkman: Better documentation for language negotiation

1 files changed, 51 insertions, 35 deletions

diff --git a/modules/system/language.api.php b/modules/system/language.api.php
index 671479309..d868b6fef 100644
--- a/modules/system/language.api.php
+++ b/modules/system/language.api.php
@@ -62,16 +62,22 @@ function hook_language_switch_links_alter(array &$links, $type, $path) {
 }
 
 /**
- * Allow modules to define their own language types.
+ * Define language types.
  *
  * @return
- *   An array of language type definitions. Each language type has an identifier
- *   key. The language type definition is an associative array that may contain
- *   the following key-value pairs:
- *   - "name": The human-readable language type identifier.
- *   - "description": A description of the language type.
- *   - "fixed": An array of language provider identifiers. Defining this key
- *     makes the language type non-configurable.
+ *   An associative array of language type definitions. The keys are the
+ *   identifiers, which are also used as names for global variables representing
+ *   the types in the bootstrap phase. The values are associative arrays that
+ *   may contain the following elements:
+ *   - name: The human-readable language type identifier.
+ *   - description: A description of the language type.
+ *   - fixed: A fixed array of language negotiation provider identifiers to use
+ *     to initialize this language. Defining this key makes the language type
+ *     non-configurable, so it will always use the specified providers in the
+ *     given priority order. Omit to make the language type configurable.
+ *
+ * @see hook_language_types_info_alter()
+ * @ingroup language_negotiation
  */
 function hook_language_types_info() {
   return array(
@@ -90,6 +96,9 @@ function hook_language_types_info() {
  *
  * @param $language_types
  *   Array of language type definitions.
+ *
+ * @see hook_language_types_info()
+ * @ingroup language_negotiation
  */
 function hook_language_types_info_alter(array &$language_types) {
   if (isset($language_types['custom_language_type'])) {
@@ -98,31 +107,35 @@ function hook_language_types_info_alter(array &$language_types) {
 }
 
 /**
- * Allow modules to define their own language providers.
+ * Define language negotiation providers.
  *
  * @return
- *   An array of language provider definitions. Each language provider has an
- *   identifier key. The language provider definition is an associative array
- *   that may contain the following key-value pairs:
- *   - "types": An array of allowed language types. If a language provider does
- *     not specify which language types it should be used with, it will be
- *     available for all the configurable language types.
- *   - "callbacks": An array of functions that will be called to perform various
- *     tasks. Possible key-value pairs are:
- *     - "language": Required. The callback that will determine the language
- *       value.
- *     - "switcher": The callback that will determine the language switch links
- *       associated to the current language provider.
- *     - "url_rewrite": The callback that will provide URL rewriting.
- *   - "file": A file that will be included before the callback is invoked; this
- *     allows callback functions to be in separate files.
- *   - "weight": The default weight the language provider has.
- *   - "name": A human-readable identifier.
- *   - "description": A description of the language provider.
- *   - "config": An internal path pointing to the language provider
- *     configuration page.
- *   - "cache": The value Drupal's page cache should be set to for the current
- *     language provider to be invoked.
+ *   An associative array of language negotiation provider definitions. The keys
+ *   are provider identifiers, and the values are associative arrays definining
+ *   each provider, with the following elements:
+ *   - types: An array of allowed language types. If a language negotiation
+ *     provider does not specify which language types it should be used with, it
+ *     will be available for all the configurable language types.
+ *   - callbacks: An associative array of functions that will be called to
+ *     perform various tasks. Possible elements are:
+ *     - negotiation: (required) Name of the callback function that determines
+ *       the language value.
+ *     - language_switch: (optional) Name of the callback function that
+ *       determines links for a language switcher block associated with this
+ *       provider. See language_switcher_url() for an example.
+ *     - url_rewrite: (optional) Name of the callback function that provides URL
+ *       rewriting, if needed by this provider.
+ *   - file: The file where callback functions are defined (this file will be
+ *     included before the callbacks are invoked).
+ *   - weight: The default weight of the provider.
+ *   - name: The translated human-readable name for the provider.
+ *   - description: A translated longer description of the provider.
+ *   - config: An internal path pointing to the provider's configuration page.
+ *   - cache: The value Drupal's page cache should be set to for the current
+ *     provider to be invoked.
+ *
+ * @see hook_language_negotiation_info_alter()
+ * @ingroup language_negotiation
  */
 function hook_language_negotiation_info() {
   return array(
@@ -135,18 +148,21 @@ function hook_language_negotiation_info() {
       'file' => drupal_get_path('module', 'custom') . '/custom.module',
       'weight' => -4,
       'types' => array('custom_language_type'),
-      'name' => t('Custom language provider'),
-      'description' => t('This is a custom language provider.'),
+      'name' => t('Custom language negotiation provider'),
+      'description' => t('This is a custom language negotiation provider.'),
       'cache' => 0,
     ),
   );
 }
 
 /**
- * Perform alterations on language providers.
+ * Perform alterations on language negoiation providers.
  *
  * @param $language_providers
- *   Array of language provider definitions.
+ *   Array of language negotiation provider definitions.
+ *
+ * @see hook_language_negotiation_info()
+ * @ingroup language_negotiation
  */
 function hook_language_negotiation_info_alter(array &$language_providers) {
   if (isset($language_providers['custom_language_provider'])) {