- Patch #1337124 by xjm: improve API documentation for taxonomy_autoc…

…omplete().

modules/taxonomy/taxonomy.pages.inc

@@ -77,7 +77,35 @@ function taxonomy_term_feed($term) {
 }
 
 /**
- * Helper function for autocompletion
+ * Page callback: Outputs JSON for taxonomy autocomplete suggestions.
+ *
+ * Path: taxonomy/autocomplete
+ *
+ * This callback outputs term name suggestions in response to Ajax requests
+ * made by the taxonomy autocomplete widget for taxonomy term reference
+ * fields. The output is a JSON object of plain-text term suggestions, keyed by
+ * the user-entered value with the completed term name appended.  Term names
+ * containing commas are wrapped in quotes.
+ *
+ * For example, suppose the user has entered the string 'red fish, blue' in the
+ * field, and there are two taxonomy terms, 'blue fish' and 'blue moon'. The
+ * JSON output would have the following structure:
+ * @code
+ *   {
+ *     "red fish, blue fish": "blue fish",
+ *     "red fish, blue moon": "blue moon",
+ *   };
+ * @endcode
+ *
+ * @param $field_name
+ *   The name of the term reference field.
+ * @param $tags_typed
+ *   (optional) A comma-separated list of term names entered in the
+ *   autocomplete form element. Only the last term is used for autocompletion.
+ *   Defaults to '' (an empty string).
+ *
+ * @see taxonomy_menu()
+ * @see taxonomy_field_widget_info()
  */
 function taxonomy_autocomplete($field_name, $tags_typed = '') {
   $field = field_info_field($field_name);