From 6439874457f95446bf1350030983b60be772040b Mon Sep 17 00:00:00 2001
From: Lars Toomre <ltoomre@23809.no-reply.drupal.org>
Date: Wed, 3 Oct 2012 15:08:20 -0400
Subject: [PATCH 1/2] Apply patch 1326644-8.

---
 core/modules/taxonomy/taxonomy-term.tpl.php |    2 +-
 core/modules/taxonomy/taxonomy.admin.inc    |    6 +++---
 core/modules/taxonomy/taxonomy.module       |   17 ++++++++++-------
 3 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/core/modules/taxonomy/taxonomy-term.tpl.php b/core/modules/taxonomy/taxonomy-term.tpl.php
index 712e83c..ae2fa55 100644
--- a/core/modules/taxonomy/taxonomy-term.tpl.php
+++ b/core/modules/taxonomy/taxonomy-term.tpl.php
@@ -16,7 +16,7 @@
  *    array and printed as a string.
  *    It includes the 'class' information, which includes:
  *   - taxonomy-term: The current template type, i.e., "theming hook".
- *   - vocabulary-[vocabulary-name]: The vocabulary to which the term belongs to.
+ *   - vocabulary-[vocabulary-name]: The vocabulary to which the term belongs.
  *     For example, if the term is a "Tag" it would result in "vocabulary-tag".
  *
  * Other variables:
diff --git a/core/modules/taxonomy/taxonomy.admin.inc b/core/modules/taxonomy/taxonomy.admin.inc
index ecef0b5..8accc47 100644
--- a/core/modules/taxonomy/taxonomy.admin.inc
+++ b/core/modules/taxonomy/taxonomy.admin.inc
@@ -518,7 +518,7 @@ function theme_taxonomy_overview_terms($variables) {
 }
 
 /**
- * Returns a rendered edit form to create a new term associated to the given vocabulary.
+ * Renders an edit form to create a new term in a given vocabulary.
  */
 function taxonomy_term_add($vocabulary) {
   $term = entity_create('taxonomy_term', array('vid' => $vocabulary->vid, 'vocabulary_machine_name' => $vocabulary->machine_name));
@@ -630,9 +630,9 @@ function taxonomy_vocabulary_confirm_reset_alphabetical($form, &$form_state, $vi
 }
 
 /**
- * Submit handler to reset a vocabulary to alphabetical order after confirmation.
+ * Form submission handler for taxonomy_vocabulary_confirm_reset_alphabetical().
  *
- * @see taxonomy_vocabulary_confirm_reset_alphabetical()
+ * Resets a vocabulary to alphabetical order after confirmation.
  */
 function taxonomy_vocabulary_confirm_reset_alphabetical_submit($form, &$form_state) {
   db_update('taxonomy_term_data')
diff --git a/core/modules/taxonomy/taxonomy.module b/core/modules/taxonomy/taxonomy.module
index c28cc7b..c03f498 100644
--- a/core/modules/taxonomy/taxonomy.module
+++ b/core/modules/taxonomy/taxonomy.module
@@ -574,6 +574,7 @@ function taxonomy_term_delete_multiple(array $tids) {
  *
  * @param Drupal\taxonomy\Term $term
  *   A taxonomy term object.
+ *
  * @return array
  *   A $page element suitable for use by drupal_page_render().
  */
@@ -884,7 +885,8 @@ function taxonomy_term_load_children($tid, $vid = 0) {
  *   The term ID under which to generate the tree. If 0, generate the tree
  *   for the entire vocabulary.
  * @param $max_depth
- *   The number of levels of the tree to return. Leave NULL to return all levels.
+ *   (optional) The number of levels of the tree to return. Leave NULL to
+ *   return all levels.
  * @param $load_entities
  *   If TRUE, a full entity load will occur on the term objects. Otherwise they
  *   are partial objects queried directly from the {taxonomy_term_data} table to
@@ -1029,15 +1031,15 @@ function taxonomy_term_load_multiple_by_name($name, $vocabulary = NULL) {
  * from the database. Terms are loaded into memory and will not require
  * database access if loaded again during the same page request.
  *
- * @see entity_load_multiple()
- * @see Drupal\Core\Entity\EntityFieldQuery
- *
  * @param array $tids
  *   (optional) An array of entity IDs. If omitted, all entities are loaded.
  *
  * @return array
  *   An array of taxonomy term entities, indexed by tid. When no results are
  *   found, an empty array is returned.
+ *
+ * @see entity_load_multiple()
+ * @see Drupal\Core\Entity\EntityFieldQuery
  */
 function taxonomy_term_load_multiple(array $tids = NULL) {
   return entity_load_multiple('taxonomy_term', $tids);
@@ -1050,13 +1052,13 @@ function taxonomy_term_load_multiple(array $tids = NULL) {
  * vocabulary from the database. Terms are loaded into memory and will not
  * require database access if loaded again during the same page request.
  *
- * @see entity_load_multiple()
- *
  * @param array $vids
  *   (optional) An array of entity IDs. If omitted, all entities are loaded.
  *
  * @return array
  *  An array of vocabulary objects, indexed by vid.
+ *
+ * @see entity_load_multiple()
  */
 function taxonomy_vocabulary_load_multiple(array $vids = NULL) {
   return entity_load_multiple('taxonomy_vocabulary', $vids);
@@ -1218,7 +1220,8 @@ function taxonomy_options_list($field, $instance, $entity_type, $entity) {
  * Confirm that terms entered as values meet at least one of these conditions.
  *
  * Possible error codes:
- * - 'taxonomy_term_illegal_value': The value is not part of the list of allowed values.
+ * - taxonomy_term_illegal_value: The value is not part of the list of allowed
+ *   values.
  */
 function taxonomy_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
   // Build an array of existing term IDs so they can be loaded with
-- 
1.7.6.msysgit.0


From 957f215ea35f3a706439ce04289650f24c075194 Mon Sep 17 00:00:00 2001
From: Lars Toomre <ltoomre@23809.no-reply.drupal.org>
Date: Wed, 3 Oct 2012 17:10:59 -0400
Subject: [PATCH 2/2] Many documenttaion improvements.

---
 core/modules/taxonomy/taxonomy.admin.inc  |  140 ++++++++++++++++--------
 core/modules/taxonomy/taxonomy.api.php    |   32 +++---
 core/modules/taxonomy/taxonomy.js         |    2 +-
 core/modules/taxonomy/taxonomy.module     |  171 ++++++++++++++++++-----------
 core/modules/taxonomy/taxonomy.pages.inc  |   33 ++++--
 core/modules/taxonomy/taxonomy.tokens.inc |    2 +-
 6 files changed, 238 insertions(+), 142 deletions(-)

diff --git a/core/modules/taxonomy/taxonomy.admin.inc b/core/modules/taxonomy/taxonomy.admin.inc
index 8accc47..0822287 100644
--- a/core/modules/taxonomy/taxonomy.admin.inc
+++ b/core/modules/taxonomy/taxonomy.admin.inc
@@ -9,11 +9,19 @@ use Drupal\taxonomy\Term;
 use Drupal\taxonomy\Vocabulary;
 
 /**
- * Form builder to list and manage vocabularies.
+ * Menu callback: Form constructor to list and manage vocabularies.
  *
- * @ingroup forms
+ * @param array $form
+ *   A form array.
+ *
+ * @return array
+ *   A form array as expected by drupal_render().
+ *
+ * @see taxonomy_menu()
  * @see taxonomy_overview_vocabularies_submit()
  * @see theme_taxonomy_overview_vocabularies()
+ *
+ * @ingroup forms
  */
 function taxonomy_overview_vocabularies($form) {
   $vocabularies = taxonomy_vocabulary_load_multiple();
@@ -46,9 +54,9 @@ function taxonomy_overview_vocabularies($form) {
 }
 
 /**
- * Submit handler for vocabularies overview. Updates changed vocabulary weights.
+ * Form submission handler for taxonomy_overview_vocabularies().
  *
- * @see taxonomy_overview_vocabularies()
+ * This function updates changed vocabulary weights.
  */
 function taxonomy_overview_vocabularies_submit($form, &$form_state) {
   foreach ($form_state['values'] as $vid => $vocabulary) {
@@ -61,13 +69,14 @@ function taxonomy_overview_vocabularies_submit($form, &$form_state) {
 }
 
 /**
- * Returns HTML for the vocabulary overview form as a sortable list of vocabularies.
+ * Returns HTML for the vocabulary overview form as a sortable list.
  *
  * @param $variables
  *   An associative array containing:
  *   - form: A render element representing the form.
  *
  * @see taxonomy_overview_vocabularies()
+ *
  * @ingroup themeable
  */
 function theme_taxonomy_overview_vocabularies($variables) {
@@ -102,7 +111,14 @@ function theme_taxonomy_overview_vocabularies($variables) {
 }
 
 /**
- * Page callback: provides the vocabulary creation form.
+ * Page callback: Provides the vocabulary creation form.
+ *
+ * @return array
+ *   Returns the built and processed vocabulary form array.
+ *
+ * @see taxonomy_menu()
+ *
+ * @ingroup forms
  */
 function taxonomy_vocabulary_add() {
   $vocabulary = entity_create('taxonomy_vocabulary', array(
@@ -115,17 +131,19 @@ function taxonomy_vocabulary_add() {
 }
 
 /**
- * Form builder for the taxonomy terms overview.
+ * Form constructor for the taxonomy terms overview.
  *
- * Display a tree of all the terms in a vocabulary, with options to edit
- * each one. The form is made drag and drop by the theme function.
+ * Displays a tree of all the terms in a vocabulary, with options to edit each
+ * one. The form is made drag and drop by the theme function.
  *
  * @param Drupal\taxonomy\Vocabulary $vocabulary
  *   The taxonomy vocabulary entity to list terms for.
  *
- * @ingroup forms
+ * @see taxonomy_menu()
  * @see taxonomy_overview_terms_submit()
  * @see theme_taxonomy_overview_terms()
+ *
+ * @ingroup forms
  */
 function taxonomy_overview_terms($form, &$form_state, Vocabulary $vocabulary) {
   global $pager_page_array, $pager_total, $pager_total_items;
@@ -140,11 +158,16 @@ function taxonomy_overview_terms($form, &$form_state, Vocabulary $vocabulary) {
   $form['#parent_fields'] = FALSE;
 
   $page            = isset($_GET['page']) ? $_GET['page'] : 0;
-  $page_increment  = variable_get('taxonomy_terms_per_page_admin', 100);  // Number of terms per page.
-  $page_entries    = 0;   // Elements shown on this page.
-  $before_entries  = 0;   // Elements at the root level before this page.
-  $after_entries   = 0;   // Elements at the root level after this page.
-  $root_entries    = 0;   // Elements at the root level on this page.
+  // Number of terms per page.
+  $page_increment  = variable_get('taxonomy_terms_per_page_admin', 100);
+  // Elements shown on this page.
+  $page_entries    = 0;
+  // Elements at the root level before this page.
+  $before_entries  = 0;
+  // Elements at the root level after this page.
+  $after_entries   = 0;
+  // Elements at the root level on this page.
+  $root_entries    = 0;
 
   // Terms from previous and next pages are shown if the term tree would have
   // been cut in the middle. Keep track of how many extra terms we show on each
@@ -184,7 +207,8 @@ function taxonomy_overview_terms($form, &$form_state, Vocabulary $vocabulary) {
         $back_step++;
         if ($pterm->depth == 0) {
           prev($tree);
-          continue 2; // Jump back to the start of the root level parent.
+          // Jump back to the start of the root level parent.
+          continue 2;
        }
       }
     }
@@ -217,19 +241,22 @@ function taxonomy_overview_terms($form, &$form_state, Vocabulary $vocabulary) {
     $current_page[$key] = $term;
   } while ($term = next($tree));
 
-  // Because we didn't use a pager query, set the necessary pager variables.
+  // Because we did not use a pager query, set the necessary pager variables.
   $total_entries = $before_entries + $page_entries + $after_entries;
   $pager_total_items[0] = $total_entries;
   $pager_page_array[0] = $page;
   $pager_total[0] = ceil($total_entries / $page_increment);
 
-  // If this form was already submitted once, it's probably hit a validation
+  // If this form was already submitted once, it has probably hit a validation
   // error. Ensure the form is rebuilt in the same order as the user submitted.
   if (!empty($form_state['input'])) {
-    $order = array_flip(array_keys($form_state['input'])); // Get the $_POST order.
-    $current_page = array_merge($order, $current_page); // Update our form with the new order.
+     // Get the $_POST order.
+    $order = array_flip(array_keys($form_state['input']));
+    // Update our form with the new order.
+    $current_page = array_merge($order, $current_page);
     foreach ($current_page as $key => $term) {
-      // Verify this is a term for the current page and set at the current depth.
+      // Verify this is a term for the current page and set at the current
+      // depth.
       if (is_array($form_state['input'][$key]) && is_numeric($form_state['input'][$key]['tid'])) {
         $current_page[$key]->depth = $form_state['input'][$key]['depth'];
       }
@@ -241,7 +268,8 @@ function taxonomy_overview_terms($form, &$form_state, Vocabulary $vocabulary) {
 
   // Build the actual form.
   foreach ($current_page as $key => $term) {
-    // Save the term for the current page so we don't have to load it a second time.
+    // Save the term for the current page so we don't have to load it a second
+    // time.
     $form[$key]['#term'] = (array) $term;
     if (isset($term->parents)) {
       $form[$key]['#term']['parent'] = $term->parent = $term->parents[0];
@@ -257,12 +285,14 @@ function taxonomy_overview_terms($form, &$form_state, Vocabulary $vocabulary) {
       );
       $form[$key]['parent'] = array(
         '#type' => 'hidden',
-        // Yes, default_value on a hidden. It needs to be changeable by the javascript.
+        // Yes, default_value on a hidden. It needs to be changeable by the
+        // javascript.
         '#default_value' => $term->parent,
       );
       $form[$key]['depth'] = array(
         '#type' => 'hidden',
-        // Same as above, the depth is modified by javascript, so it's a default_value.
+        // Same as above, the depth is modified by javascript, so it has a
+        // default_value.
         '#default_value' => $term->depth,
       );
       $form[$key]['weight'] = array(
@@ -308,7 +338,7 @@ function taxonomy_overview_terms($form, &$form_state, Vocabulary $vocabulary) {
 }
 
 /**
- * Submit handler for terms overview form.
+ * Form submission handler for taxonomy_overview_terms().
  *
  * Rather than using a textfield or weight field, this form depends entirely
  * upon the order of form elements on the page to determine new weights.
@@ -319,8 +349,6 @@ function taxonomy_overview_terms($form, &$form_state, Vocabulary $vocabulary) {
  * lowest to highest, but are not necessarily sequential. Numbers may be skipped
  * when a term has children so that reordering is minimal when a child is
  * added or removed from a term.
- *
- * @see taxonomy_overview_terms()
  */
 function taxonomy_overview_terms_submit($form, &$form_state) {
   if ($form_state['triggering_element']['#value'] == t('Reset to alphabetical')) {
@@ -433,6 +461,7 @@ function taxonomy_overview_terms_submit($form, &$form_state) {
  *   - form: A render element representing the form.
  *
  * @see taxonomy_overview_terms()
+ *
  * @ingroup themeable
  */
 function theme_taxonomy_overview_terms($variables) {
@@ -518,7 +547,17 @@ function theme_taxonomy_overview_terms($variables) {
 }
 
 /**
- * Renders an edit form to create a new term in a given vocabulary.
+ * Form constructor to create a new term in a given vocabulary.
+ *
+ * @param object $vocabulary
+ *   An vocabulary object that has properties 'vid' and 'machine_name'.
+ *
+ * @return array
+ *   Returns the built and processed term form array.
+ *
+ * @see taxonomy_menu()
+ *
+ * @ingroup forms
  */
 function taxonomy_term_add($vocabulary) {
   $term = entity_create('taxonomy_term', array('vid' => $vocabulary->vid, 'vocabulary_machine_name' => $vocabulary->machine_name));
@@ -526,10 +565,15 @@ function taxonomy_term_add($vocabulary) {
 }
 
 /**
- * Form builder for the term delete form.
+ * Form constructor for the term delete form.
  *
- * @ingroup forms
+ * @param Drupal\taxonomy\Term $term
+ *   The taxonomy term to delete.
+ *
+ * @see taxonomy_menu()
  * @see taxonomy_term_confirm_delete_submit()
+ *
+ * @ingroup forms
  */
 function taxonomy_term_confirm_delete($form, &$form_state, Term $term) {
   // Always provide entity id in the same form key as in the entity edit form.
@@ -550,9 +594,7 @@ function taxonomy_term_confirm_delete($form, &$form_state, Term $term) {
 }
 
 /**
- * Submit handler to delete a term after confirmation.
- *
- * @see taxonomy_term_confirm_delete()
+ * Form submission handler for taxonomy_term_confirm_delete().
  */
 function taxonomy_term_confirm_delete_submit($form, &$form_state) {
   taxonomy_term_delete($form_state['values']['tid']);
@@ -567,10 +609,14 @@ function taxonomy_term_confirm_delete_submit($form, &$form_state) {
 }
 
 /**
- * Form builder for the vocabulary delete confirmation form.
+ * Form constructor for the vocabulary delete confirmation form.
+ *
+ * @param $vid
+ *   The vocabulary ID.
  *
- * @ingroup forms
  * @see taxonomy_vocabulary_confirm_delete_submit()
+ *
+ * @ingroup forms
  */
 function taxonomy_vocabulary_confirm_delete($form, &$form_state, $vid) {
   $vocabulary = taxonomy_vocabulary_load($vid);
@@ -593,9 +639,7 @@ function taxonomy_vocabulary_confirm_delete($form, &$form_state, $vid) {
 }
 
 /**
- * Submit handler to delete a vocabulary after confirmation.
- *
- * @see taxonomy_vocabulary_confirm_delete()
+ * Form submission handler for taxonomy_vocabulary_confirm_delete().
  */
 function taxonomy_vocabulary_confirm_delete_submit($form, &$form_state) {
   $status = taxonomy_vocabulary_delete($form_state['values']['vid']);
@@ -607,10 +651,14 @@ function taxonomy_vocabulary_confirm_delete_submit($form, &$form_state) {
 }
 
 /**
- * Form builder to confirm resetting a vocabulary to alphabetical order.
+ * Form constructor to confirm resetting a vocabulary to alphabetical order.
+ *
+ * @param $vid
+ *   The vocabulary ID.
  *
- * @ingroup forms
  * @see taxonomy_vocabulary_confirm_reset_alphabetical_submit()
+ *
+ * @ingroup forms
  */
 function taxonomy_vocabulary_confirm_reset_alphabetical($form, &$form_state, $vid) {
   $vocabulary = taxonomy_vocabulary_load($vid);
@@ -621,12 +669,12 @@ function taxonomy_vocabulary_confirm_reset_alphabetical($form, &$form_state, $vi
   $form['name'] = array('#type' => 'value', '#value' => $vocabulary->name);
   $form['reset_alphabetical'] = array('#type' => 'value', '#value' => TRUE);
   return confirm_form($form,
-                  t('Are you sure you want to reset the vocabulary %title to alphabetical order?',
-                  array('%title' => $vocabulary->name)),
-                  'admin/structure/taxonomy/' . $vocabulary->machine_name,
-                  t('Resetting a vocabulary will discard all custom ordering and sort items alphabetically.'),
-                  t('Reset to alphabetical'),
-                  t('Cancel'));
+    t('Are you sure you want to reset the vocabulary %title to alphabetical order?',
+    array('%title' => $vocabulary->name)),
+    'admin/structure/taxonomy/' . $vocabulary->machine_name,
+    t('Resetting a vocabulary will discard all custom ordering and sort items alphabetically.'),
+    t('Reset to alphabetical'),
+    t('Cancel'));
 }
 
 /**
diff --git a/core/modules/taxonomy/taxonomy.api.php b/core/modules/taxonomy/taxonomy.api.php
index 78f03e6..b9be0bc 100644
--- a/core/modules/taxonomy/taxonomy.api.php
+++ b/core/modules/taxonomy/taxonomy.api.php
@@ -1,25 +1,25 @@
 <?php
 
-use Drupal\Core\Entity\EntityInterface;
-
 /**
  * @file
  * Hooks provided by the Taxonomy module.
  */
 
+use Drupal\Core\Entity\EntityInterface;
+
 /**
  * @addtogroup hooks
  * @{
  */
 
 /**
- * Act on taxonomy vocabularies when loaded.
+ * Acts on taxonomy vocabularies when loaded.
  *
  * Modules implementing this hook can act on the vocabulary objects before they
  * are returned by taxonomy_vocabulary_load_multiple().
  *
  * @param array $vocabularies
- *   An array of taxonomy vocabulary entities.
+ *   An array of Drupal\taxonomy\Vocabulary entities.
  */
 function hook_taxonomy_vocabulary_load(array $vocabularies) {
   foreach ($vocabularies as $vocabulary) {
@@ -29,7 +29,7 @@ function hook_taxonomy_vocabulary_load(array $vocabularies) {
 
 
 /**
- * Act on taxonomy vocabularies before they are saved.
+ * Acts on taxonomy vocabularies before they are saved.
  *
  * Modules implementing this hook can act on the vocabulary object before it is
  * inserted or updated.
@@ -42,7 +42,7 @@ function hook_taxonomy_vocabulary_presave(Drupal\taxonomy\Vocabulary $vocabulary
 }
 
 /**
- * Act on taxonomy vocabularies when inserted.
+ * Acts on taxonomy vocabularies when inserted.
  *
  * Modules implementing this hook can act on the vocabulary object when saved
  * to the database.
@@ -57,7 +57,7 @@ function hook_taxonomy_vocabulary_insert(Drupal\taxonomy\Vocabulary $vocabulary)
 }
 
 /**
- * Act on taxonomy vocabularies when updated.
+ * Acts on taxonomy vocabularies when updated.
  *
  * Modules implementing this hook can act on the vocabulary object when updated.
  *
@@ -72,7 +72,7 @@ function hook_taxonomy_vocabulary_update(Drupal\taxonomy\Vocabulary $vocabulary)
 }
 
 /**
- * Act before taxonomy vocabulary deletion.
+ * Acts before taxonomy vocabulary deletion.
  *
  * This hook is invoked from taxonomy_vocabulary_delete() before
  * field_attach_delete_bundle() is called and before the vocabulary is actually
@@ -91,7 +91,7 @@ function hook_taxonomy_vocabulary_predelete(Drupal\taxonomy\Vocabulary $vocabula
 }
 
 /**
- * Respond to taxonomy vocabulary deletion.
+ * Responds to taxonomy vocabulary deletion.
  *
  * This hook is invoked from taxonomy_vocabulary_delete() after
  * field_attach_delete_bundle() has been called and after the vocabulary has
@@ -110,7 +110,7 @@ function hook_taxonomy_vocabulary_delete(Drupal\taxonomy\Vocabulary $vocabulary)
 }
 
 /**
- * Act on taxonomy terms when loaded.
+ * Acts on taxonomy terms when loaded.
  *
  * Modules implementing this hook can act on the term objects returned by
  * taxonomy_term_load_multiple().
@@ -133,7 +133,7 @@ function hook_taxonomy_term_load(array $terms) {
 }
 
 /**
- * Act on taxonomy terms before they are saved.
+ * Acts on taxonomy terms before they are saved.
  *
  * Modules implementing this hook can act on the term object before it is
  * inserted or updated.
@@ -146,7 +146,7 @@ function hook_taxonomy_term_presave(Drupal\taxonomy\Term $term) {
 }
 
 /**
- * Act on taxonomy terms when inserted.
+ * Acts on taxonomy terms when inserted.
  *
  * Modules implementing this hook can act on the term object when saved to
  * the database.
@@ -170,7 +170,7 @@ function hook_taxonomy_term_insert(Drupal\taxonomy\Term $term) {
 }
 
 /**
- * Act on taxonomy terms when updated.
+ * Acts on taxonomy terms when updated.
  *
  * Modules implementing this hook can act on the term object when updated.
  *
@@ -194,7 +194,7 @@ function hook_taxonomy_term_update(Drupal\taxonomy\Term $term) {
 }
 
 /**
- * Act before taxonomy term deletion.
+ * Acts before taxonomy term deletion.
  *
  * This hook is invoked from taxonomy_term_delete() before
  * field_attach_delete() is called and before the term is actually removed from
@@ -210,7 +210,7 @@ function hook_taxonomy_term_predelete(Drupal\taxonomy\Term $term) {
 }
 
 /**
- * Respond to taxonomy term deletion.
+ * Responds to a taxonomy term deletion.
  *
  * This hook is invoked from taxonomy_term_delete() after field_attach_delete()
  * has been called and after the term has been removed from the database.
@@ -225,7 +225,7 @@ function hook_taxonomy_term_delete(Drupal\taxonomy\Term $term) {
 }
 
 /**
- * Alter the results of taxonomy_term_view().
+ * Alters the results of taxonomy_term_view().
  *
  * This hook is called after the content has been assembled in a structured
  * array and may be used for doing processing which requires that the complete
diff --git a/core/modules/taxonomy/taxonomy.js b/core/modules/taxonomy/taxonomy.js
index 19d42df..731e26d 100644
--- a/core/modules/taxonomy/taxonomy.js
+++ b/core/modules/taxonomy/taxonomy.js
@@ -3,7 +3,7 @@
 "use strict";
 
 /**
- * Move a block in the blocks table from one region to another via select list.
+ * Moves a block in the blocks table from one region to another via select list.
  *
  * This behavior is dependent on the tableDrag behavior, since it uses the
  * objects initialized in that behavior to update the row.
diff --git a/core/modules/taxonomy/taxonomy.module b/core/modules/taxonomy/taxonomy.module
index c03f498..f941831 100644
--- a/core/modules/taxonomy/taxonomy.module
+++ b/core/modules/taxonomy/taxonomy.module
@@ -5,10 +5,10 @@
  * Enables the organization of content into categories.
  */
 
+use Drupal\Core\Entity\EntityInterface;
 use Drupal\node\Node;
 use Drupal\taxonomy\Term;
 use Drupal\taxonomy\Vocabulary;
-use Drupal\Core\Entity\EntityInterface;
 
 /**
  * Denotes that no term in the vocabulary has a parent.
@@ -26,11 +26,11 @@ const TAXONOMY_HIERARCHY_SINGLE = 1;
 const TAXONOMY_HIERARCHY_MULTIPLE = 2;
 
 /**
- * Users can create new terms in a free-tagging vocabulary when
- * submitting a taxonomy_autocomplete_widget. We store a term object
- * whose tid is 'autocreate' as a field data item during widget
- * validation and then actually create the term if/when that field
- * data item makes it to taxonomy_field_insert/update().
+ * Users can create new terms in a free-tagging vocabulary when submitting a
+ * taxonomy_autocomplete_widget. We store a term object whose tid is
+ * 'autocreate' as a field data item during widget validation and then actually
+ * create the term if/when that field data item makes it to
+ * taxonomy_field_insert/update().
  */
 
 /**
@@ -170,6 +170,12 @@ function taxonomy_entity_info() {
 
 /**
  * Entity URI callback.
+ *
+ * @param object $term
+ *   A taxonomy term object with 'tid' property.
+ *
+ * @return array
+ *   An array with 'path' as key and appropriate menu path as its value.
  */
 function taxonomy_term_uri($term) {
   return array(
@@ -211,19 +217,20 @@ function taxonomy_field_extra_fields() {
 }
 
 /**
- * Return nodes attached to a term across all field instances.
+ * Returns nodes attached to a term across all field instances.
  *
- * This function requires taxonomy module to be maintaining its own tables,
- * and will return an empty array if it is not. If using other field storage
- * methods alternatives methods for listing terms will need to be used.
+ * This function requires taxonomy module to be maintaining its own tables, and
+ * will return an empty array if it is not. If using other field storage methods
+ * alternatives methods for listing terms will need to be used.
  *
  * @param $tid
  *   The term ID.
  * @param $pager
- *   Boolean to indicate whether a pager should be used.
+ *   (optional) Boolean to indicate whether a pager should be used. Defaults to
+ *   TRUE.
  * @param $limit
- *   Integer. The maximum number of nodes to find.
- *   Set to FALSE for no limit.
+ *   (optional) An integer for the maximum number of nodes to find. Set to FALSE
+ *   for no limit. Defaults to FALSE.
  * @param $order
  *   An array of fields and directions.
  *
@@ -258,7 +265,7 @@ function taxonomy_select_nodes($tid, $pager = TRUE, $limit = FALSE, $order = arr
   foreach ($order as $field => $direction) {
     $query->orderBy($field, $direction);
     // ORDER BY fields need to be loaded too, assume they are in the form
-    // table_alias.name
+    // table_alias.name.
     list($table_alias, $name) = explode('.', $field);
     $query->addField($table_alias, $name);
   }
@@ -438,6 +445,11 @@ function taxonomy_term_access($op, $term) {
  *
  * @param Drupal\taxonomy\Vocabulary $vocabulary
  *   The taxonomy vocabulary entity to be saved.
+ *
+ * @return int
+ *   Status constant indicating whether vocabulary was inserted (SAVED_NEW) or
+ *   updated (SAVED_UPDATED). When inserting a new vocabulary, $vocabulary->vid
+ *   will contain the vocabulary ID of the newly created vocabulary.
  */
 function taxonomy_vocabulary_save(Vocabulary $vocabulary) {
   return $vocabulary->save();
@@ -493,8 +505,8 @@ function taxonomy_taxonomy_vocabulary_update(Vocabulary $vocabulary) {
  * Checks and updates the hierarchy flag of a vocabulary.
  *
  * Checks the current parents of all terms in a vocabulary and updates the
- * vocabulary's hierarchy setting to the lowest possible level. If no term
- * has parent terms then the vocabulary will be given a hierarchy of
+ * vocabulary's hierarchy setting to the lowest possible level. If no term has
+ * parent terms then the vocabulary will be given a hierarchy of
  * TAXONOMY_HIERARCHY_DISABLED. If any term has a single parent then the
  * vocabulary will be given a hierarchy of TAXONOMY_HIERARCHY_SINGLE. If any
  * term has multiple parents then the vocabulary will be given a hierarchy of
@@ -588,12 +600,13 @@ function taxonomy_term_show(Term $term) {
  * @param array $terms
  *   An array of taxonomy terms as returned by taxonomy_term_load_multiple().
  * @param string $view_mode
- *   View mode, e.g. 'full', 'teaser'...
+ *   (optional) View mode, e.g. 'full', 'teaser'. Defaults to 'teaser'.
  * @param int $weight
- *   An integer representing the weight of the first node in the list.
+ *   (optional) An integer representing the weight of the first node in the
+ *   list. Defaults to zero.
  * @param string $langcode
- *   (optional) A language code to use for rendering. Defaults to the global
- *   content language of the current request.
+ *   (optional) A language code to use for rendering. Defaults to NULL, the
+ *   global content language of the current request.
  *
  * @return array
  *   An array in the format expected by drupal_render().
@@ -626,10 +639,10 @@ function taxonomy_term_view_multiple(array $terms, $view_mode = 'teaser', $weigh
  * @param Drupal\taxonomy\Term $term
  *   A taxonomy term object.
  * @param string $view_mode
- *   View mode, e.g. 'full', 'teaser'...
+ *   (optional) View mode, e.g. 'full', 'teaser'. Defaults to 'full'.
  * @param string $langcode
- *   (optional) A language code to use for rendering. Defaults to the global
- *   content language of the current request.
+ *   (optional) A language code to use for rendering. Defaults to NULL, the
+ *   global content language of the current request.
  */
 function taxonomy_term_build_content(Term $term, $view_mode = 'full', $langcode = NULL) {
   if (!isset($langcode)) {
@@ -669,15 +682,15 @@ function taxonomy_term_build_content(Term $term, $view_mode = 'full', $langcode
 }
 
 /**
- * Generate an array for rendering the given term.
+ * Generates an array for rendering the given term.
  *
  * @param Drupal\taxonomy\Term $term
  *   A taxonomy term entity.
  * @param string $view_mode
- *   View mode, e.g. 'full', 'teaser'...
+ *   (optional) View mode, e.g. 'full', 'teaser'. Defaults to 'full'.
  * @param string $langcode
- *   (optional) A language code to use for rendering. Defaults to the global
- *   content language of the current request.
+ *   (optional) A language code to use for rendering. Defaults to NULL, the
+ *   global content language of the current request.
  *
  * @return
  *   An array as expected by drupal_render().
@@ -747,6 +760,9 @@ function template_preprocess_taxonomy_term(&$variables) {
  *
  * @param Drupal\taxonomy\Term $term
  *   A taxonomy term entity.
+ *
+ * @return bool
+ *   TRUE if the current page is for the passed in term ID; otherwise, FALSE.
  */
 function taxonomy_term_is_page(Term $term) {
   $page_term = menu_get_object('taxonomy_term', 2);
@@ -754,24 +770,25 @@ function taxonomy_term_is_page(Term $term) {
 }
 
 /**
- * Clear all static cache variables for terms.
+ * Clears all static cache variables for terms.
  */
 function taxonomy_terms_static_reset() {
   entity_get_controller('taxonomy_term')->resetCache();
 }
 
 /**
- * Clear all static cache variables for vocabularies.
+ * Clears all static cache variables for vocabularies.
  *
  * @param $ids
- *   An array of ids to reset in entity controller cache.
+ *   (optional) An array of ids to reset in entity controller cache. Defaults to
+ *   NULL.
  */
 function taxonomy_vocabulary_static_reset(array $ids = NULL) {
   entity_get_controller('taxonomy_vocabulary')->resetCache($ids);
 }
 
 /**
- * Get names for all taxonomy vocabularies.
+ * Gets names for all taxonomy vocabularies.
  *
  * @return
  *   An associative array of objects keyed by vocabulary machine name with
@@ -819,7 +836,13 @@ function taxonomy_term_load_parents($tid) {
 }
 
 /**
- * Find all ancestors of a given term ID.
+ * Finds all ancestors of a given term ID.
+ *
+ * @param int $tid
+ *   A taxonomy term ID.
+ *
+ * @return array
+ *   All ancestor terms, if any, for a given term ID.
  */
 function taxonomy_term_load_parents_all($tid) {
   $cache = &drupal_static(__FUNCTION__, array());
@@ -849,7 +872,7 @@ function taxonomy_term_load_parents_all($tid) {
  * @param $tid
  *   A taxonomy term ID.
  * @param $vid
- *   An optional vocabulary ID to restrict the child search.
+ *   (optional) An vocabulary ID to restrict the child search. Defaults to zero.
  *
  * @return
  *   An array of term objects that are the children of the term $tid, or an
@@ -877,25 +900,25 @@ function taxonomy_term_load_children($tid, $vid = 0) {
 }
 
 /**
- * Create a hierarchical representation of a vocabulary.
+ * Creates a hierarchical representation of a vocabulary.
  *
  * @param $vid
  *   Which vocabulary to generate the tree for.
  * @param $parent
- *   The term ID under which to generate the tree. If 0, generate the tree
- *   for the entire vocabulary.
+ *   (optional) The term ID under which to generate the tree. If zero, generate
+ *    the tree for the entire vocabulary. Defaults to zero.
  * @param $max_depth
  *   (optional) The number of levels of the tree to return. Leave NULL to
- *   return all levels.
+ *   return all levels. Defaults to NULL.
  * @param $load_entities
- *   If TRUE, a full entity load will occur on the term objects. Otherwise they
- *   are partial objects queried directly from the {taxonomy_term_data} table to
- *   save execution time and memory consumption when listing large numbers of
- *   terms. Defaults to FALSE.
+ *   (optional) If TRUE, a full entity load will occur on the term objects.
+ *   Otherwise, they are partial objects queried directly from the
+ *   {taxonomy_term_data} table to save execution time and memory consumption
+ *   when listing large numbers of terms. Defaults to FALSE.
  *
  * @return
- *   An array of all term objects in the tree. Each term object is extended
- *   to have "depth" and "parents" attributes in addition to its normal ones.
+ *   An array of all term objects in the tree. Each term object is extended to
+ *   have "depth" and "parents" attributes in addition to its normal ones.
  *   Results are statically cached. Term objects will be partial or complete
  *   depending on the $load_entities parameter.
  */
@@ -930,8 +953,8 @@ function taxonomy_get_tree($vid, $parent = 0, $max_depth = NULL, $load_entities
     }
   }
 
-  // Load full entities, if necessary. The entity controller statically
-  // caches the results.
+  // Load full entities, if necessary. The entity controller statically caches
+  // the results.
   if ($load_entities) {
     $term_entities = taxonomy_term_load_multiple(array_keys($terms[$vid]));
   }
@@ -939,13 +962,13 @@ function taxonomy_get_tree($vid, $parent = 0, $max_depth = NULL, $load_entities
   $max_depth = (!isset($max_depth)) ? count($children[$vid]) : $max_depth;
   $tree = array();
 
-  // Keeps track of the parents we have to process, the last entry is used
-  // for the next processing step.
+  // Keeps track of the parents we have to process, the last entry is used for
+  // the next processing step.
   $process_parents = array();
   $process_parents[] = $parent;
 
-  // Loops over the parent terms and adds its children to the tree array.
-  // Uses a loop instead of a recursion, because it's more efficient.
+  // Loops over the parent terms and adds its children to the tree array. Uses a
+  // loop instead of a recursion, because it is more efficient.
   while (count($process_parents)) {
     $parent = array_pop($process_parents);
     // The number of parents determines the current depth.
@@ -959,8 +982,8 @@ function taxonomy_get_tree($vid, $parent = 0, $max_depth = NULL, $load_entities
         }
         $term = $load_entities ? $term_entities[$child] : $terms[$vid][$child];
         if (isset($parents[$vid][$term->tid])) {
-          // Clone the term so that the depth attribute remains correct
-          // in the event of multiple parents.
+          // Clone the term so that the depth attribute remains correct in the
+          // event of multiple parents.
           $term = clone $term;
         }
         $term->depth = $depth;
@@ -985,8 +1008,8 @@ function taxonomy_get_tree($vid, $parent = 0, $max_depth = NULL, $load_entities
       } while ($child = next($children[$vid][$parent]));
 
       if (!$has_children) {
-        // We processed all terms in this hierarchy-level, reset pointer
-        // so that this function works the next time it gets called.
+        // We processed all terms in this hierarchy-level, reset pointer so that
+        // this function works the next time it gets called.
         reset($children[$vid][$parent]);
       }
     }
@@ -996,7 +1019,7 @@ function taxonomy_get_tree($vid, $parent = 0, $max_depth = NULL, $load_entities
 }
 
 /**
- * Try to map a string to an existing term, as for glossary use.
+ * Tries to map a string to an existing term, as for glossary use.
  *
  * Provides a case-insensitive and trimmed mapping, to maximize the
  * likelihood of a successful match.
@@ -1028,18 +1051,19 @@ function taxonomy_term_load_multiple_by_name($name, $vocabulary = NULL) {
  * Load multiple taxonomy terms based on certain conditions.
  *
  * This function should be used whenever you need to load more than one term
- * from the database. Terms are loaded into memory and will not require
- * database access if loaded again during the same page request.
+ * from the database. Terms are loaded into memory and will not require database
+ * access if loaded again during the same page request.
  *
  * @param array $tids
  *   (optional) An array of entity IDs. If omitted, all entities are loaded.
+ *   Defaults to NULL.
  *
  * @return array
  *   An array of taxonomy term entities, indexed by tid. When no results are
  *   found, an empty array is returned.
  *
- * @see entity_load_multiple()
  * @see Drupal\Core\Entity\EntityFieldQuery
+ * @see entity_load_multiple()
  */
 function taxonomy_term_load_multiple(array $tids = NULL) {
   return entity_load_multiple('taxonomy_term', $tids);
@@ -1054,6 +1078,7 @@ function taxonomy_term_load_multiple(array $tids = NULL) {
  *
  * @param array $vids
  *   (optional) An array of entity IDs. If omitted, all entities are loaded.
+ *   Defaults to NULL.
  *
  * @return array
  *  An array of vocabulary objects, indexed by vid.
@@ -1065,7 +1090,7 @@ function taxonomy_vocabulary_load_multiple(array $vids = NULL) {
 }
 
 /**
- * Return the taxonomy vocabulary entity matching a vocabulary ID.
+ * Returns the taxonomy vocabulary entity matching a vocabulary ID.
  *
  * @param int $vid
  *   The vocabulary's ID.
@@ -1081,7 +1106,7 @@ function taxonomy_vocabulary_load($vid) {
 }
 
 /**
- * Return the taxonomy vocabulary entity matching a vocabulary machine name.
+ * Returns the taxonomy vocabulary entity matching a vocabulary machine name.
  *
  * @param $name
  *   The vocabulary's machine name.
@@ -1098,10 +1123,10 @@ function taxonomy_vocabulary_machine_name_load($name) {
 }
 
 /**
- * Return the taxonomy term entity matching a term ID.
+ * Returns the taxonomy term entity matching a term ID.
  *
  * @param $tid
- *   A term's ID
+ *   A taxonomy term ID.
  *
  * @return Drupal\taxonomy\Term|false
  *   A taxonomy term entity, or FALSE if the term was not found. Results are
@@ -1116,6 +1141,12 @@ function taxonomy_term_load($tid) {
 
 /**
  * Helper function for array_map purposes.
+ *
+ * @param Drupal\taxonomy\Term $term
+ *   A taxonomy term object.
+ *
+ * @return int
+ *   The taxonomy term ID.
  */
 function _taxonomy_get_tid_from_term(Term $term) {
   return $term->tid;
@@ -1124,6 +1155,14 @@ function _taxonomy_get_tid_from_term(Term $term) {
 /**
  * Implodes a list of tags of a certain vocabulary into a string.
  *
+ * @param array $tags
+ *   An array of vocabulary term tags.
+ * @param int $vid
+ *   (optional) A vocabulary ID to constrain terms to. Defaults to NULL.
+ *
+ * @return string
+ *   A string with a comma-delimted imploded list of tags.
+ *
  * @see drupal_explode_tags()
  */
 function taxonomy_implode_tags($tags, $vid = NULL) {
@@ -1307,9 +1346,8 @@ function taxonomy_field_formatter_info() {
 function taxonomy_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
   $element = array();
 
-  // Terms whose tid is 'autocreate' do not exist
-  // yet and $item['taxonomy_term'] is not set. Theme such terms as
-  // just their name.
+  // Terms whose tid is 'autocreate' do not exist yet and $item['taxonomy_term']
+  // is not set. Theme such terms as just their name.
 
   switch ($display['type']) {
     case 'taxonomy_term_reference_link':
@@ -1410,7 +1448,8 @@ function taxonomy_field_formatter_prepare_view($entity_type, $entities, $field,
   if ($tids) {
     $terms = taxonomy_term_load_multiple($tids);
 
-    // Iterate through the fieldable entities again to attach the loaded term data.
+    // Iterate through the fieldable entities again to attach the loaded term
+    // data.
     foreach ($entities as $id => $entity) {
       $rekey = FALSE;
 
@@ -1474,7 +1513,7 @@ function taxonomy_field_widget_form(&$form, &$form_state, $field, $instance, $la
 }
 
 /**
- * Form element validate handler for taxonomy term autocomplete element.
+ * Form element validation handler for taxonomy_field_widget_form().
  */
 function taxonomy_autocomplete_validate($element, &$form_state) {
   // Autocomplete widgets do not send their tids in the form, so we must detect
diff --git a/core/modules/taxonomy/taxonomy.pages.inc b/core/modules/taxonomy/taxonomy.pages.inc
index 7c77716..21f6228 100644
--- a/core/modules/taxonomy/taxonomy.pages.inc
+++ b/core/modules/taxonomy/taxonomy.pages.inc
@@ -10,10 +10,15 @@ use Drupal\taxonomy\Vocabulary;
 use Symfony\Component\HttpFoundation\JsonResponse;
 
 /**
- * Menu callback; displays all nodes associated with a term.
+ * Menu callback: Displays all nodes associated with a term.
  *
  * @param Drupal\taxonomy\Term $term
  *   The taxonomy term entity.
+ *
+ * @return array
+ *   A build array as expected by drupal_render().
+ *
+ * @see taxonomy_menu()
  */
 function taxonomy_term_page(Term $term) {
   // Assign the term name as the page title.
@@ -35,9 +40,9 @@ function taxonomy_term_page(Term $term) {
   drupal_set_breadcrumb($breadcrumb);
   drupal_add_feed('taxonomy/term/' . $term->tid . '/feed', 'RSS - ' . $term->label());
 
-  // If there is a menu link to this term, the link becomes the last part
-  // of the active trail, and the link name becomes the page title.
-  // Thus, we must explicitly set the page title to be the node title.
+  // If there is a menu link to this term, the link becomes the last part of the
+  // active trail, and the link name becomes the page title. Thus, we must
+  // explicitly set the page title to be the node title.
   $uri = $term->uri();
 
   // Set the term path as the canonical URL to prevent duplicate content.
@@ -65,7 +70,7 @@ function taxonomy_term_page(Term $term) {
 }
 
 /**
- * Generate the content feed for a taxonomy term.
+ * Generates the content feed for a taxonomy term.
  *
  * @param Drupal\taxonomy\Term $term
  *   The taxonomy term entity.
@@ -73,8 +78,8 @@ function taxonomy_term_page(Term $term) {
 function taxonomy_term_feed(Term $term) {
   $channel['link'] = url('taxonomy/term/' . $term->tid, array('absolute' => TRUE));
   $channel['title'] = config('system.site')->get('name') . ' - ' . $term->label();
-  // Only display the description if we have a single term, to avoid clutter and confusion.
-  // HTML will be removed from feed description.
+  // Only display the description if we have a single term, to avoid clutter and
+  // confusion. HTML will be removed from feed description.
   $channel['description'] = check_markup($term->description, $term->format, '', TRUE);
   $nids = taxonomy_select_nodes($term->tid, FALSE, config('system.rss')->get('items.limit'));
 
@@ -103,12 +108,15 @@ function taxonomy_term_feed(Term $term) {
  * @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).
+ *   (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).
+ *
+ * @return Symfony\Component\HttpFoundation\JsonResponse
+ *   A JSON response object.
  *
- * @see taxonomy_menu()
  * @see taxonomy_field_widget_info()
+ * @see taxonomy_menu()
  */
 function taxonomy_autocomplete($field_name, $tags_typed = '') {
   // If the request has a '/' in the search text, then the menu system will have
@@ -126,7 +134,8 @@ function taxonomy_autocomplete($field_name, $tags_typed = '') {
     exit;
   }
 
-  // The user enters a comma-separated list of tags. We only autocomplete the last tag.
+  // The user enters a comma-separated list of tags. We only autocomplete the
+  // last tag.
   $tags_typed = drupal_explode_tags($tags_typed);
   $tag_last = drupal_strtolower(array_pop($tags_typed));
 
diff --git a/core/modules/taxonomy/taxonomy.tokens.inc b/core/modules/taxonomy/taxonomy.tokens.inc
index c7847b3..5c4ca9a 100644
--- a/core/modules/taxonomy/taxonomy.tokens.inc
+++ b/core/modules/taxonomy/taxonomy.tokens.inc
@@ -64,7 +64,7 @@ function taxonomy_token_info() {
     'description' => t("The number of terms belonging to the taxonomy vocabulary."),
   );
 
-  // Chained tokens for taxonomies
+  // Chained tokens for taxonomies.
   $term['vocabulary'] = array(
     'name' => t("Vocabulary"),
     'description' => t("The vocabulary the taxonomy term belongs to."),
-- 
1.7.6.msysgit.0