diff --git a/tag/coursetags_add.php b/tag/coursetags_add.php
index e5c316a3f8c..969dda3e3ac 100644
--- a/tag/coursetags_add.php
+++ b/tag/coursetags_add.php
@@ -1,7 +1,27 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
 /**
  * coursetags_add.php
- * @author j.beedell@open.ac.uk June07
+ *
+ * @package    core_tag
+ * @category   tag
+ * @copyright  2007 j.beedell@open.ac.uk
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once('../config.php');
diff --git a/tag/coursetags_edit.php b/tag/coursetags_edit.php
index 18d40a45da8..8bb33b4a74f 100644
--- a/tag/coursetags_edit.php
+++ b/tag/coursetags_edit.php
@@ -1,9 +1,27 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 
 /**
- * coursetags_edit.php
- * displays personal tags for a course with some editing facilites
- * @author j.beedell@open.ac.uk June07
+ * Displays personal tags for a course with some editing facilites
+ *
+ * @package    core_tag
+ * @category   tag
+ * @copyright  2007 j.beedell@open.ac.uk
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once('../config.php');
diff --git a/tag/coursetags_more.php b/tag/coursetags_more.php
index ee7c75c454b..60b18207be1 100644
--- a/tag/coursetags_more.php
+++ b/tag/coursetags_more.php
@@ -1,8 +1,27 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
 /**
- * coursetags_more.php
- * a full display of tags allowing some filtering and reordering
- * @author j.beedell@open.ac.uk June07
+ * A full display of tags allowing some filtering and reordering
+ *
+ * @package    core_tag
+ * @category   tag
+ * @copyright  2007 j.beedell@open.ac.uk
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once('../config.php');
diff --git a/tag/coursetagslib.php b/tag/coursetagslib.php
index f022dfc5f77..c83b9543084 100644
--- a/tag/coursetagslib.php
+++ b/tag/coursetagslib.php
@@ -1,7 +1,26 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
 /**
  * coursetagslib.php
- * @author j.beedell@open.ac.uk July07
+ *
+ * @package    core_tag
+ * @copyright  2007 j.beedell@open.ac.uk
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once $CFG->dirroot.'/tag/lib.php';
@@ -10,13 +29,15 @@ require_once $CFG->dirroot.'/tag/lib.php';
  * Returns an ordered array of tags associated with visible courses
  * (boosted replacement of get_all_tags() allowing association with user and tagtype).
  *
- * @uses $CFG
- * @param int $courseid, a 0 will return all distinct tags for visible courses
- * @param int $userid optional the user id, a default of 0 will return all users tags for the course
- * @param string $tagtype optional 'official' or 'default', empty returns both tag types
- * @param int $numtags optional number of tags to display, default of 80 is set in the block, 0 returns all
- * @param string $sort optional selected sorting, default is alpha sort (name) also timemodified or popularity
- * @return array
+ * @package  core_tag
+ * @category tag
+ * @param    int      $courseid A course id. Passing 0 will return all distinct tags for all visible courses
+ * @param    int      $userid   (optional) the user id, a default of 0 will return all users tags for the course
+ * @param    string   $tagtype  (optional) The type of tag, empty string returns all types. Currently (Moodle 2.2) there are two
+ *                              types of tags which are used within Moodle, they are 'official' and 'default'.
+ * @param    int      $numtags  (optional) number of tags to display, default of 80 is set in the block, 0 returns all
+ * @param    string   $sort     (optional) selected sorting, default is alpha sort (name) also timemodified or popularity
+ * @return   array
  */
 function coursetag_get_tags($courseid, $userid=0, $tagtype='', $numtags=0, $sort='name') {
 
@@ -93,10 +114,11 @@ function coursetag_get_tags($courseid, $userid=0, $tagtype='', $numtags=0, $sort
  * Returns an ordered array of tags
  * (replaces popular_tags_count() allowing sorting).
  *
- * @uses $CFG
- * @param string $sort optional selected sorting, default is alpha sort (name) also timemodified or popularity
- * @param int $numtags optional number of tags to display, default of 20 is set in the block, 0 returns all
- * @return array
+ * @package  core_tag
+ * @category tag
+ * @param    string $sort    (optional) selected sorting, default is alpha sort (name) also timemodified or popularity
+ * @param    int    $numtags (optional) number of tags to display, default of 20 is set in the block, 0 returns all
+ * @return   array
  */
 function coursetag_get_all_tags($sort='name', $numtags=0) {
 
@@ -135,8 +157,21 @@ function coursetag_get_all_tags($sort='name', $numtags=0) {
 }
 
 /**
- * Callback function for coursetag_get_tags() and coursetag_get_all_tags() only
- * @uses $CFG
+ * Sorting callback function for coursetag_get_tags() and coursetag_get_all_tags() only
+ *
+ * This function does a comparision on a field withing two variables, $a and $b. The field used is specified by
+ * $CFG->tagsort or we just use the 'name' field if $CFG->tagsort is empty. The comparison works as follows:
+ * If $a->$tagsort is greater than $b->$tagsort, 1 is returned.
+ * If $a->$tagsort is equal to $b->$tagsort, 0 is returned.
+ * If $a->$tagsort is less than $b->$tagsort, -1 is returned.
+ *
+ * Also if $a->$tagsort is not numeric or a string, 0 is returned.
+ *
+ * @package core_tag
+ * @access  private
+ * @param   int|string|mixed $a Variable to compare against $b
+ * @param   int|string|mixed $b Variable to compare against $a
+ * @return  int                 The result of the comparison/validation 1, 0 or -1
  */
 function coursetag_sort($a, $b) {
     // originally from block_blog_tags
@@ -161,10 +196,12 @@ function coursetag_sort($a, $b) {
 /**
  * Prints a tag cloud
  *
- * @param array $tagcloud array of tag objects (fields: id, name, rawname, count and flag)
- * @param int $max_size maximum text size, in percentage
- * @param int $min_size minimum text size, in percentage
- * @param $return if true return html string
+ * @package  core_tag
+ * @category tag
+ * @param    array $tagcloud array of tag objects (fields: id, name, rawname, count and flag)
+ * @param    mixed $return   if true return html string
+ * @param    int   $max_size maximum text size, in percentage
+ * @param    int   $min_size minimum text size, in percentage
  */
 function coursetag_print_cloud($tagcloud, $return=false, $max_size=180, $min_size=80) {
 
@@ -237,8 +274,11 @@ function coursetag_print_cloud($tagcloud, $return=false, $max_size=180, $min_siz
 
 /**
  * Returns javascript for use in tags block and supporting pages
- * @param string $coursetagdivs comma separated divs ids
- * @uses $CFG
+ *
+ * @package  core_tag
+ * @category tag
+ * @param    string   $coursetagdivs comma separated divs ids
+ * @return   null
  */
 function coursetag_get_jscript($coursetagdivs = '') {
     global $CFG, $DB, $PAGE;
@@ -263,6 +303,12 @@ function coursetag_get_jscript($coursetagdivs = '') {
 
 /**
  * Returns javascript to create the links in the tag block footer.
+ *
+ * @package  core_tag
+ * @category tag
+ * @param    string   $elementid       the element to attach the footer to
+ * @param    array    $coursetagslinks links arrays each consisting of 'title', 'onclick' and 'text' elements
+ * @return   string   always returns a blank string
  */
 function coursetag_get_jscript_links($elementid, $coursetagslinks) {
     global $PAGE;
@@ -279,12 +325,12 @@ function coursetag_get_jscript_links($elementid, $coursetagslinks) {
 /**
  * Returns all tags created by a user for a course
  *
- * @uses $CFG
- * @param int $courseid
- * @param int $userid
+ * @package  core_tag
+ * @category tag
+ * @param    int      $courseid tags are returned for the course that has this courseid
+ * @param    int      $userid   return tags which were created by this user
  */
 function coursetag_get_records($courseid, $userid) {
-
     global $CFG, $DB;
 
     $sql = "SELECT t.id, name, rawname
@@ -300,12 +346,13 @@ function coursetag_get_records($courseid, $userid) {
 /**
  * Stores a tag for a course for a user
  *
- * @uses $CFG
- * @param array $tags simple array of keywords to be stored
- * @param integer $courseid
- * @param integer $userid
- * @param string $tagtype official or default only
- * @param string $myurl optional for logging creation of course tags
+ * @package  core_tag
+ * @category tag
+ * @param    array  $tags     simple array of keywords to be stored
+ * @param    int    $courseid the id of the course we wish to store a tag for
+ * @param    int    $userid   the id of the user we wish to store a tag for
+ * @param    string $tagtype  official or default only
+ * @param    string $myurl    (optional) for logging creation of course tags
  */
 function coursetag_store_keywords($tags, $courseid, $userid=0, $tagtype='official', $myurl='') {
 
@@ -348,11 +395,12 @@ function coursetag_store_keywords($tags, $courseid, $userid=0, $tagtype='officia
 /**
  * Deletes a personal tag for a user for a course.
  *
- * @uses $CFG
- * @param int $tagid
- * @param int $userid
- * @param int $courseid
-  */
+ * @package  core_tag
+ * @category tag
+ * @param    int      $tagid    the tag we wish to delete
+ * @param    int      $userid   the user that the tag is associated with
+ * @param    int      $courseid the course that the tag is associated with
+ */
 function coursetag_delete_keyword($tagid, $userid, $courseid) {
 
     global $CFG, $DB;
@@ -385,11 +433,12 @@ function coursetag_delete_keyword($tagid, $userid, $courseid) {
 /**
  * Get courses tagged with a tag
  *
+ * @package  core_tag
+ * @category tag
  * @param int $tagid
  * @return array of course objects
  */
 function coursetag_get_tagged_courses($tagid) {
-
     global $DB;
 
     $courses = array();
@@ -411,14 +460,13 @@ function coursetag_get_tagged_courses($tagid) {
 }
 
 /**
- * Course tagging function used only during the deletion of a
- * course (called by lib/moodlelib.php) to clean up associated tags
+ * Course tagging function used only during the deletion of a course (called by lib/moodlelib.php) to clean up associated tags
  *
- * @param int $courseid
- * @param bool $showfeedback
+ * @package core_tag
+ * @param   int      $courseid     the course we wish to delete tag instances from
+ * @param   bool     $showfeedback if we should output a notification of the delete to the end user
  */
 function coursetag_delete_course_tags($courseid, $showfeedback=false) {
-
     global $DB, $OUTPUT;
 
     if ($tags = $DB->get_records_select('tag_instance', "itemtype='course' AND itemid=:courseid", array('courseid'=>$courseid))) {
@@ -440,10 +488,9 @@ function coursetag_delete_course_tags($courseid, $showfeedback=false) {
     }
 }
 
-/**
+/*
  * Function called by cron to create/update users rss feeds
  *
- * @uses $CFG
  * @return true
  *
  * Function removed.
@@ -618,10 +665,10 @@ function coursetag_rss_feeds() {
 }
  */
 
-/**
+/*
  * Get official keywords for the <meta name="keywords"> in header.html
  * use: echo '<meta name="keywords" content="'.coursetag_get_official_keywords($COURSE->id).'"/>';
- * @uses $CFG
+ *
  * @param int $courseid
  * @return string
  *
diff --git a/tag/edit.php b/tag/edit.php
index 66fd0fbc366..b71c72f2be0 100644
--- a/tag/edit.php
+++ b/tag/edit.php
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -15,9 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+
 /**
- * @package    core
- * @subpackage tag
+ * @package    core_tag
+ * @category   tag
  * @copyright  2007 Luiz Cruz <luiz.laydner@gmail.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
diff --git a/tag/edit_form.php b/tag/edit_form.php
index f1e828620cc..972836755a7 100644
--- a/tag/edit_form.php
+++ b/tag/edit_form.php
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -15,9 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+
 /**
- * @package    core
- * @subpackage tag
+ * @package    core_tag
+ * @category   tag
  * @copyright  2007 Luiz Cruz <luiz.laydner@gmail.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -28,8 +28,20 @@ if (!defined('MOODLE_INTERNAL')) {
 
 require_once($CFG->dirroot.'/lib/formslib.php');
 
+/**
+ * Defines the form for editing tags
+ *
+ * @package    core_tag
+ * @category   tag
+ * @copyright  2007 Luiz Cruz <luiz.laydner@gmail.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class tag_edit_form extends moodleform {
 
+    /**
+     * Overrides the abstract moodleform::definition method for defining what the form that is to be
+     * presented to the user.
+     */
     function definition () {
 
         $mform =& $this->_form;
@@ -62,4 +74,4 @@ class tag_edit_form extends moodleform {
 
     }
 
-}
+}
\ No newline at end of file
diff --git a/tag/index.php b/tag/index.php
index 5525f0411c8..56e23726aa1 100644
--- a/tag/index.php
+++ b/tag/index.php
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -15,9 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+
 /**
- * @package    core
- * @subpackage tag
+ * @package    core_tag
+ * @category   tag
  * @copyright  2007 Luiz Cruz <luiz.laydner@gmail.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
diff --git a/tag/lib.php b/tag/lib.php
index 2284a41fb22..2859162b61d 100644
--- a/tag/lib.php
+++ b/tag/lib.php
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -15,24 +14,20 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+
 /**
  * Moodle tag library
  *
- * Tag strings : you can use any character in tags, except the comma (which is
- * the separator) and the '\' (backslash).  Note that many spaces (or other
- * blank characters) will get "compressed" into one. A tag string is always a
- * rawurlencode'd string. This is the same behavior as http://del.icio.us.
+ * Tag strings : you can use any character in tags, except the comma (which is the separator) and
+ * the '\' (backslash).  Note that many spaces (or other blank characters) will get "compressed"
+ * into one. A tag string is always a rawurlencode'd string. This is the same behavior as
+ * http://del.icio.us.
  *
- * A "record" is a php array (note that an object will work too) that contains
- * the following variables :
- *  - type: the table containing the record that we are tagging (eg: for a
- *    blog, this is table 'post', and for a user it is 'user')
- *  - id: the id of the record
- *
- * TODO: turn this into a full-fledged categorization system. This could start
- * by modifying (removing, probably) the 'tag type' to use another table
- * describing the relationship between tags (parents, sibling, etc.), which
- * could then be merged with the 'course categorization' system...
+ * A "record" is a php array (note that an object will work too) that contains the following
+ * variables :
+ *  - type: The database table containing the record that we are tagging (eg: for a blog, this is
+ *          the table named 'post', and for a user it is the table name 'user')
+ *  - id:   The id of the record
  *
  * BASIC INSTRUCTIONS :
  *  - to "tag a blog post" (for example):
@@ -43,23 +38,63 @@
  *
  * Tag set will create tags that need to be created.
  *
- * @package    core
- * @subpackage tag
- * @see http://www.php.net/manual/en/function.urlencode.php
+ * @package    core_tag
+ * @category   tag
+ * @todo       MDL-31090 turn this into a full-fledged categorization system. This could start by
+ *             modifying (removing, probably) the 'tag type' to use another table describing the
+ *             relationship between tags (parents, sibling, etc.), which could then be merged with
+ *             the 'course categorization' system.
+ * @see        http://www.php.net/manual/en/function.urlencode.php
  * @copyright  2007 Luiz Cruz <luiz.laydner@gmail.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+/**
+ * Used to require that the return value from a function is an array.
+ * @see tag_set()
+ */
 define('TAG_RETURN_ARRAY', 0);
+/**
+ * Used to require that the return value from a function is an object.
+ * @see tag_set()
+ */
 define('TAG_RETURN_OBJECT', 1);
+/**
+ * Use to specify that HTML free text is expected to be returned from a function.
+ * @see tag_display_name()
+ */
 define('TAG_RETURN_TEXT', 2);
+/**
+ * Use to specify that encoded HTML is expected to be returned from a function.
+ * @see tag_display_name()
+ */
 define('TAG_RETURN_HTML', 3);
 
+/**
+ * Used to specify that we wish a lowercased string to be returned
+ * @see tag_normal()
+ */
 define('TAG_CASE_LOWER', 0);
+/**
+ * Used to specify that we do not wish the case of the returned string to change
+ * @see tag_normal()
+ */
 define('TAG_CASE_ORIGINAL', 1);
 
+/**
+ * Used to specify that we want all related tags returned, no matter how they are related.
+ * @see tag_get_related_tags()
+ */
 define('TAG_RELATED_ALL', 0);
+/**
+ * Used to specify that we only want back tags that were manually related.
+ * @see tag_get_related_tags()
+ */
 define('TAG_RELATED_MANUAL', 1);
+/**
+ * Used to specify that we only want back tags where the relationship was automatically correlated.
+ * @see tag_get_related_tags()
+ */
 define('TAG_RELATED_CORRELATED', 2);
 
 ///////////////////////////////////////////////////////
@@ -70,15 +105,15 @@ define('TAG_RELATED_CORRELATED', 2);
 /**
  * Set the tags assigned to a record.  This overwrites the current tags.
  *
- * This function is meant to be fed the string coming up from the user
- * interface, which contains all tags assigned to a record.
+ * This function is meant to be fed the string coming up from the user interface, which contains all tags assigned to a record.
  *
- * @param string $record_type the type of record to tag ('post' for blogs,
- *     'user' for users, 'tag' for tags, etc.
- * @param int $record_id the id of the record to tag
- * @param array $tags the array of tags to set on the record. If
- *     given an empty array, all tags will be removed.
- * @return void
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    string    $record_type the type of record to tag ('post' for blogs, 'user' for users, 'tag' for tags, etc.)
+ * @param    int       $record_id   the id of the record to tag
+ * @param    array     $tags        the array of tags to set on the record. If given an empty array, all tags will be removed.
+ * @return   bool|null
  */
 function tag_set($record_type, $record_id, $tags) {
 
@@ -142,11 +177,12 @@ function tag_set($record_type, $record_id, $tags) {
 /**
  * Adds a tag to a record, without overwriting the current tags.
  *
- * @param string $record_type the type of record to tag ('post' for blogs,
- *     'user' for users, etc.
- * @param int $record_id the id of the record to tag
- * @param string $tag the tag to add
- * @return void
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    string   $record_type the type of record to tag ('post' for blogs, 'user' for users, etc.)
+ * @param    int      $record_id   the id of the record to tag
+ * @param    string   $tag         the tag to add
  */
 function tag_set_add($record_type, $record_id, $tag) {
 
@@ -162,11 +198,12 @@ function tag_set_add($record_type, $record_id, $tag) {
 /**
  * Removes a tag from a record, without overwriting other current tags.
  *
- * @param string $record_type the type of record to tag ('post' for blogs,
- *     'user' for users, etc.
- * @param int $record_id the id of the record to tag
- * @param string $tag the tag to delete
- * @return void
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    string   $record_type the type of record to tag ('post' for blogs, 'user' for users, etc.)
+ * @param    int      $record_id   the id of the record to tag
+ * @param    string   $tag         the tag to delete
  */
 function tag_set_delete($record_type, $record_id, $tag) {
 
@@ -181,13 +218,15 @@ function tag_set_delete($record_type, $record_id, $tag) {
 }
 
 /**
- * Set the type of a tag.  At this time (version 1.9) the possible values
- * are 'default' or 'official'.  Official tags will be displayed separately "at
- * tagging time" (while selecting the tags to apply to a record).
+ * Set the type of a tag.  At this time (version 2.2) the possible values are 'default' or 'official'.  Official tags will be
+ * displayed separately "at tagging time" (while selecting the tags to apply to a record).
  *
- * @param string $tagid tagid to modify
- * @param string $type either 'default' or 'official'
- * @return true on success, false otherwise
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    string   $tagid tagid to modify
+ * @param    string   $type either 'default' or 'official'
+ * @return   bool     true on success, false otherwise
  */
 function tag_type_set($tagid, $type) {
     global $DB;
@@ -200,14 +239,17 @@ function tag_type_set($tagid, $type) {
     return false;
 }
 
-
 /**
  * Set the description of a tag
  *
- * @param int $tagid the id of the tag
- * @param string $description the description
- * @param int $descriptionformat the moodle text format of the description
- * @return true on success, false otherwise
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    int      $tagid the id of the tag
+ * @param    string   $description the tag's description string to be set
+ * @param    int      $descriptionformat the moodle text format of the description
+ *                    {@link http://docs.moodle.org/dev/Text_formats_2.0#Database_structure}
+ * @return   bool     true on success, false otherwise
  */
 function tag_description_set($tagid, $description, $descriptionformat) {
     global $DB;
@@ -231,12 +273,15 @@ function tag_description_set($tagid, $description, $descriptionformat) {
 /**
  * Simple function to just return a single tag object when you know the name or something
  *
- * @param string $field which field do we use to identify the tag: id, name or rawname
- * @param string $value the required value of the aforementioned field
- * @param string $returnfields which fields do we want returned?
- * @return tag object
- *
- **/
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    string $field        which field do we use to identify the tag: id, name or rawname
+ * @param    string $value        the required value of the aforementioned field
+ * @param    string $returnfields which fields do we want returned. This is a comma seperated string containing any combination of
+ *                                'id', 'name', 'rawname' or '*' to include all fields.
+ * @return   mixed  tag object
+ */
 function tag_get($field, $value, $returnfields='id, name, rawname') {
     global $DB;
 
@@ -248,15 +293,17 @@ function tag_get($field, $value, $returnfields='id, name, rawname') {
 
 
 /**
- * Get the array of db record of tags associated to a record (instances).  Use
- * tag_get_tags_csv to get the same information in a comma-separated string.
- * This should really be called tag_get_tag_instances()
+ * Get the array of db record of tags associated to a record (instances).  Use {@see tag_get_tags_csv()} if you wish to get the same
+ * data in a comma-separated string, for instances such as needing to simply display a list of tags to the end user. This should
+ * really be called tag_get_tag_instances().
  *
+ * @package core_tag
+ * @category tag
+ * @access public
  * @param string $record_type the record type for which we want to get the tags
  * @param int $record_id the record id for which we want to get the tags
- * @param string $type the tag type (either 'default' or 'official'). By default,
- *     all tags are returned.
- * @param int $userid optional only required for course tagging
+ * @param string $type the tag type (either 'default' or 'official'). By default, all tags are returned.
+ * @param int $userid (optional) only required for course tagging
  * @return array the array of tags
  */
 function tag_get_tags($record_type, $record_id, $type=null, $userid=0) {
@@ -300,11 +347,13 @@ function tag_get_tags($record_type, $record_id, $type=null, $userid=0) {
 /**
  * Get the array of tags display names, indexed by id.
  *
- * @param string $record_type the record type for which we want to get the tags
- * @param int $record_id the record id for which we want to get the tags
- * @param string $type the tag type (either 'default' or 'official'). By default,
- *     all tags are returned.
- * @return array the array of tags (with the value returned by tag_display_name), indexed by id
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    string $record_type the record type for which we want to get the tags
+ * @param    int    $record_id   the record id for which we want to get the tags
+ * @param    string $type        the tag type (either 'default' or 'official'). By default, all tags are returned.
+ * @return   array  the array of tags (with the value returned by tag_display_name), indexed by id
  */
 function tag_get_tags_array($record_type, $record_id, $type=null) {
     $tags = array();
@@ -315,16 +364,16 @@ function tag_get_tags_array($record_type, $record_id, $type=null) {
 }
 
 /**
- * Get a comma-separated string of tags associated to a record.  Use tag_get_tags
- * to get the same information in an array.
+ * Get a comma-separated string of tags associated to a record.  Use {@see tag_get_tags()} to get the same information in an array.
  *
- * @param string $record_type the record type for which we want to get the tags
- * @param int $record_id the record id for which we want to get the tags
- * @param int $html either TAG_RETURN_HTML or TAG_RETURN_TEXT, depending
- *     on the type of output desired
- * @param string $type either 'official' or 'default', if null, all tags are
- *     returned
- * @return string the comma-separated list of tags.
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    string   $record_type the record type for which we want to get the tags
+ * @param    int      $record_id   the record id for which we want to get the tags
+ * @param    int      $html        either TAG_RETURN_HTML or TAG_RETURN_TEXT, depending on the type of output desired
+ * @param    string   $type        either 'official' or 'default', if null, all tags are returned
+ * @return   string   the comma-separated list of tags.
  */
 function tag_get_tags_csv($record_type, $record_id, $html=TAG_RETURN_HTML, $type=null) {
     global $CFG;
@@ -343,18 +392,21 @@ function tag_get_tags_csv($record_type, $record_id, $html=TAG_RETURN_HTML, $type
 /**
  * Get an array of tag ids associated to a record.
  *
- * @param string $record_type the record type for which we want to get the tags
- * @param int $record_id the record id for which we want to get the tags
- * @return array of tag ids, indexed and sorted by 'ordering'
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @todo     MDL-31150 Update ordering property
+ * @param    string    $record_type the record type for which we want to get the tags
+ * @param    int       $record_id the record id for which we want to get the tags
+ * @return   array     tag ids, indexed and sorted by 'ordering'
  */
 function tag_get_tags_ids($record_type, $record_id) {
-
     $tag_ids = array();
     foreach (tag_get_tags($record_type, $record_id) as $tag) {
         if ( array_key_exists($tag->ordering, $tag_ids) ) {
             // until we can add a unique constraint, in table tag_instance,
             // on (itemtype, itemid, ordering), this is needed to prevent a bug
-            // TODO : modify database in 2.0
+            // TODO MDL-31150 modify database in 2.0
             $tag->ordering++;
         }
         $tag_ids[$tag->ordering] = $tag->id;
@@ -366,14 +418,16 @@ function tag_get_tags_ids($record_type, $record_id) {
 /**
  * Returns the database ID of a set of tags.
  *
- * @param mixed $tags one tag, or array of tags, to look for.
- * @param bool $return_value specify the type of the returned value. Either
- *     TAG_RETURN_OBJECT, or TAG_RETURN_ARRAY (default). If TAG_RETURN_ARRAY
- *     is specified, an array will be returned even if only one tag was
- *     passed in $tags.
- * @return mixed tag-indexed array of ids (or objects, if second parameter is
- *     TAG_RETURN_OBJECT), or only an int, if only one tag is given *and* the
- *     second parameter is null. No value for a key means the tag wasn't found.
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @todo     MDL-31152 Test the commented MDL-31152 todo in this function to see if it helps performance
+ *                     without breaking anything.
+ * @param    mixed $tags one tag, or array of tags, to look for.
+ * @param    bool  $return_value specify the type of the returned value. Either TAG_RETURN_OBJECT, or TAG_RETURN_ARRAY (default).
+ *                               If TAG_RETURN_ARRAY is specified, an array will be returned even if only one tag was passed in $tags.
+ * @return   mixed tag-indexed array of ids (or objects, if second parameter is TAG_RETURN_OBJECT), or only an int, if only one tag
+ *                 is given *and* the second parameter is null. No value for a key means the tag wasn't found.
  */
 function tag_get_id($tags, $return_value=null) {
     global $CFG, $DB;
@@ -390,7 +444,7 @@ function tag_get_id($tags, $return_value=null) {
 
     $result = array();
 
-    //TODO: test this and see if it helps performance without breaking anything
+    //TODO MDL-31152 test this and see if it helps performance without breaking anything
     //foreach($tags as $key => $tag) {
     //    $clean_tag = moodle_strtolower($tag);
     //    if ( array_key_exists($clean_tag), $tag_id_cache) ) {
@@ -434,16 +488,16 @@ function tag_get_id($tags, $return_value=null) {
  *
  * Related tags of a tag come from two sources:
  *   - manually added related tags, which are tag_instance entries for that tag
- *   - correlated tags, which are a calculated
+ *   - correlated tags, which are calculated
  *
- * @param string $tag_name_or_id is a single **normalized** tag name or the id
- *     of a tag
- * @param int $type the function will return either manually
- *     (TAG_RELATED_MANUAL) related tags or correlated (TAG_RELATED_CORRELATED)
- *     tags. Default is TAG_RELATED_ALL, which returns everything.
- * @param int $limitnum return a subset comprising this many records (optional,
- *     default is 10)
- * @return array an array of tag objects
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    string   $tagid          is a single **normalized** tag name or the id of a tag
+ * @param    int      $type           the function will return either manually (TAG_RELATED_MANUAL) related tags or correlated
+ *                                    (TAG_RELATED_CORRELATED) tags. Default is TAG_RELATED_ALL, which returns everything.
+ * @param    int      $limitnum       (optional) return a subset comprising this many records, the default is 10
+ * @return   array    an array of tag objects
  */
 function tag_get_related_tags($tagid, $type=TAG_RELATED_ALL, $limitnum=10) {
 
@@ -468,9 +522,12 @@ function tag_get_related_tags($tagid, $type=TAG_RELATED_ALL, $limitnum=10) {
 /**
  * Get a comma-separated list of tags related to another tag.
  *
- * @param array $related_tags the array returned by tag_get_related_tags
- * @param int $html either TAG_RETURN_HTML (default) or TAG_RETURN_TEXT : return html links, or just text.
- * @return string comma-separated list
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    array    $related_tags the array returned by tag_get_related_tags
+ * @param    int      $html    either TAG_RETURN_HTML (default) or TAG_RETURN_TEXT : return html links, or just text.
+ * @return   string   comma-separated list
  */
 function tag_get_related_tags_csv($related_tags, $html=TAG_RETURN_HTML) {
     global $CFG;
@@ -491,9 +548,12 @@ function tag_get_related_tags_csv($related_tags, $html=TAG_RETURN_HTML) {
 /**
  * Change the "value" of a tag, and update the associated 'name'.
  *
- * @param int $tagid the id of the tag to modify
- * @param string $newtag the new rawname
- * @return bool true on success, false otherwise
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    int      $tagid  the id of the tag to modify
+ * @param    string   $newrawname the new rawname
+ * @return   bool     true on success, false otherwise
  */
 function tag_rename($tagid, $newrawname) {
     global $DB;
@@ -526,8 +586,11 @@ function tag_rename($tagid, $newrawname) {
 /**
  * Delete one or more tag, and all their instances if there are any left.
  *
- * @param mixed $tagids one tagid (int), or one array of tagids to delete
- * @return bool true on success, false otherwise
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    mixed    $tagids one tagid (int), or one array of tagids to delete
+ * @return   bool     true on success, false otherwise
  */
 function tag_delete($tagids) {
     global $DB;
@@ -560,13 +623,15 @@ function tag_delete($tagids) {
 }
 
 /**
- * Delete one instance of a tag.  If the last instance was deleted, it will
- * also delete the tag, unless its type is 'official'.
+ * Delete one instance of a tag.  If the last instance was deleted, it will also delete the tag, unless its type is 'official'.
  *
- * @param string $record_type the type of the record for which to remove the instance
- * @param int $record_id the id of the record for which to remove the instance
- * @param int $tagid the tagid that needs to be removed
- * @return bool true on success, false otherwise
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    string $record_type the type of the record for which to remove the instance
+ * @param    int    $record_id   the id of the record for which to remove the instance
+ * @param    int    $tagid       the tagid that needs to be removed
+ * @return   bool   true on success, false otherwise
  */
 function tag_delete_instance($record_type, $record_id, $tagid) {
     global $CFG, $DB;
@@ -592,12 +657,14 @@ function tag_delete_instance($record_type, $record_id, $tagid) {
 /**
  * Function that returns the name that should be displayed for a specific tag
  *
- * @param object $tag_object a line out of tag table, as returned by the adobd functions
- * @param int $html TAG_RETURN_HTML (default) will return htmlspecialchars encoded string, TAG_RETURN_TEXT will not encode.
- * @return string
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    object   $tagobject a line out of tag table, as returned by the adobd functions
+ * @param    int      $html TAG_RETURN_HTML (default) will return htmlspecialchars encoded string, TAG_RETURN_TEXT will not encode.
+ * @return   string
  */
 function tag_display_name($tagobject, $html=TAG_RETURN_HTML) {
-
     global $CFG;
 
     if (!isset($tagobject->name)) {
@@ -626,12 +693,14 @@ function tag_display_name($tagobject, $html=TAG_RETURN_HTML) {
 /**
  * Find all records tagged with a tag of a given type ('post', 'user', etc.)
  *
- * @param string $tag tag to look for
- * @param string $type type to restrict search to.  If null, every matching
- *     record will be returned
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
- * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
- * @return array of matching objects, indexed by record id, from the table containing the type requested
+ * @package  core_tag
+ * @category tag
+ * @access   public
+ * @param    string   $tag       tag to look for
+ * @param    string   $type      type to restrict search to.  If null, every matching record will be returned
+ * @param    int      $limitfrom (optional, required if $limitnum is set) return a subset of records, starting at this point.
+ * @param    int      $limitnum  (optional, required if $limitfrom is set) return a subset comprising this many records.
+ * @return   array of matching objects, indexed by record id, from the table containing the type requested
  */
 function tag_find_records($tag, $type, $limitfrom='', $limitnum='') {
     global $CFG, $DB;
@@ -657,15 +726,16 @@ function tag_find_records($tag, $type, $limitfrom='', $limitnum='') {
 /////////////////// PRIVATE TAG API ///////////////////
 
 /**
- * Adds one or more tag in the database.  This function should not be called
- * directly : you should use tag_set.
+ * Adds one or more tag in the database.  This function should not be called directly : you should
+ * use tag_set.
  *
- * @param mixed $tags one tag, or an array of tags, to be created
- * @param string $type type of tag to be created ("default" is the default
- *     value and "official" is the only other supported value at this time). An
- *     official tag is kept even if there are no records tagged with it.
- * @return an array of tags ids, indexed by their lowercase normalized names.
- *     Any boolean false in the array indicates an error while adding the tag.
+ * @package core_tag
+ * @access  private
+ * @param   mixed    $tags     one tag, or an array of tags, to be created
+ * @param   string   $type     type of tag to be created ("default" is the default value and "official" is the only other supported
+ *                             value at this time). An official tag is kept even if there are no records tagged with it.
+ * @return array     $tags ids indexed by their lowercase normalized names. Any boolean false in the array indicates an error while
+ *                             adding the tag.
  */
 function tag_add($tags, $type="default") {
     global $USER, $DB;
@@ -701,15 +771,16 @@ function tag_add($tags, $type="default") {
 }
 
 /**
- * Assigns a tag to a record: if the record already exists, the time and
- * ordering will be updated.
+ * Assigns a tag to a record; if the record already exists, the time and ordering will be updated.
  *
- * @param string $record_type the type of the record that will be tagged
- * @param int $record_id the id of the record that will be tagged
- * @param string $tagid the tag id to set on the record.
- * @param int $ordering the order of the instance for this record
- * @param int $userid optional only required for course tagging
- * @return bool true on success, false otherwise
+ * @package core_tag
+ * @access  private
+ * @param   string   $record_type the type of the record that will be tagged
+ * @param   int      $record_id   the id of the record that will be tagged
+ * @param   string   $tagid       the tag id to set on the record.
+ * @param   int      $ordering    the order of the instance for this record
+ * @param   int      $userid      (optional) only required for course tagging
+ * @return  bool     true on success, false otherwise
  */
 function tag_assign($record_type, $record_id, $tagid, $ordering, $userid = 0) {
     global $DB;
@@ -733,8 +804,10 @@ function tag_assign($record_type, $record_id, $tagid, $ordering, $userid = 0) {
 /**
  * Function that returns tags that start with some text, for use by the autocomplete feature
  *
- * @param string $text string that the tag names will be matched against
- * @return mixed an array of objects, or false if no records were found or an error occured.
+ * @package core_tag
+ * @access  private
+ * @param   string   $text string that the tag names will be matched against
+ * @return  mixed    an array of objects, or false if no records were found or an error occured.
  */
 function tag_autocomplete($text) {
     global $DB;
@@ -746,10 +819,13 @@ function tag_autocomplete($text) {
 /**
  * Clean up the tag tables, making sure all tagged object still exists.
  *
- * This should normally not be necessary, but in case related tags are not deleted
- * when the tagged record is removed, this should be done once in a while, perhaps on
- * an occasional cron run.  On a site with lots of tags, this could become an expensive
- * function to call: don't run at peak time.
+ * This should normally not be necessary, but in case related tags are not deleted when the tagged record is removed, this should be
+ * done once in a while, perhaps on an occasional cron run.  On a site with lots of tags, this could become an expensive function to
+ * call: don't run at peak time.
+ *
+ * @package core_tag
+ * @access  private
+ * @todo    MDL-31212 Update tag cleanup sql so that it supports multiple types of tags
  */
 function tag_cleanup() {
     global $DB;
@@ -784,7 +860,7 @@ function tag_cleanup() {
     }
     $instances->close();
 
-    // TODO: this will only clean tags of type 'default'.  This is good as
+    // TODO MDL-31212 this will only clean tags of type 'default'.  This is good as
     // it won't delete 'official' tags, but the day we get more than two
     // types, we need to fix this.
     $unused_tags = $DB->get_recordset_sql("SELECT tg.id
@@ -805,20 +881,16 @@ function tag_cleanup() {
 }
 
 /**
- * Calculates and stores the correlated tags of all tags.
- * The correlations are stored in the 'tag_correlation' table.
+ * Calculates and stores the correlated tags of all tags. The correlations are stored in the 'tag_correlation' table.
  *
- * Two tags are correlated if they appear together a lot.
- * Ex.: Users tagged with "computers" will probably also be tagged with "algorithms".
+ * Two tags are correlated if they appear together a lot. Ex.: Users tagged with "computers" will probably also be tagged with "algorithms".
  *
- * The rationale for the 'tag_correlation' table is performance.
- * It works as a cache for a potentially heavy load query done at the 'tag_instance' table.
- * So, the 'tag_correlation' table stores redundant information derived from the 'tag_instance' table.
+ * The rationale for the 'tag_correlation' table is performance. It works as a cache for a potentially heavy load query done at the
+ * 'tag_instance' table. So, the 'tag_correlation' table stores redundant information derived from the 'tag_instance' table.
  *
- * @global moodle_database $DB
- * @param int $mincorrelation Only tags with more than $mincorrelation correlations will
- *                             be identified.
- * @return void
+ * @package core_tag
+ * @access  private
+ * @param   int      $mincorrelation Only tags with more than $mincorrelation correlations will be identified.
  */
 function tag_compute_correlations($mincorrelation = 2) {
     global $DB;
@@ -896,14 +968,14 @@ function tag_compute_correlations($mincorrelation = 2) {
 }
 
 /**
- * This function processes a tag correlation and makes changes in the database
- * as required.
+ * This function processes a tag correlation and makes changes in the database as required.
  *
- * The tag correlation object needs have both a tagid property and a correlatedtags
- * property that is an array.
+ * The tag correlation object needs have both a tagid property and a correlatedtags property that is an array.
  *
- * @param stdClass $tagcorrelation
- * @return int The id of the tag correlation that was just processed.
+ * @package core_tag
+ * @access  private
+ * @param   stdClass $tagcorrelation
+ * @return  int/bool The id of the tag correlation that was just processed or false.
  */
 function tag_process_computed_correlation(stdClass $tagcorrelation) {
     global $DB;
@@ -926,6 +998,9 @@ function tag_process_computed_correlation(stdClass $tagcorrelation) {
 
 /**
  * Tasks that should be performed at cron time
+ *
+ * @package core_tag
+ * @access private
  */
 function tag_cron() {
     tag_compute_correlations();
@@ -935,11 +1010,13 @@ function tag_cron() {
 /**
  * Search for tags with names that match some text
  *
- * @param string $text escaped string that the tag names will be matched against
- * @param boolean $ordered If true, tags are ordered by their popularity. If false, no ordering.
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
- * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
- * @return mixed an array of objects, or false if no records were found or an error occured.
+ * @package core_tag
+ * @access  private
+ * @param   string        $text      escaped string that the tag names will be matched against
+ * @param   bool          $ordered   If true, tags are ordered by their popularity. If false, no ordering.
+ * @param   int/string    $limitfrom (optional, required if $limitnum is set) return a subset of records, starting at this point.
+ * @param   int/string    $limitnum  (optional, required if $limitfrom is set) return a subset comprising this many records.
+ * @return  array/boolean an array of objects, or false if no records were found or an error occured.
  */
 function tag_find_tags($text, $ordered=true, $limitfrom='', $limitnum='') {
     global $DB;
@@ -964,8 +1041,10 @@ function tag_find_tags($text, $ordered=true, $limitfrom='', $limitnum='') {
 /**
  * Get the name of a tag
  *
- * @param mixed $tagids the id of the tag, or an array of ids
- * @return mixed string name of one tag, or id-indexed array of strings
+ * @package core_tag
+ * @access  private
+ * @param   mixed    $tagids the id of the tag, or an array of ids
+ * @return  mixed    string name of one tag, or id-indexed array of strings
  */
 function tag_get_name($tagids) {
     global $DB;
@@ -986,12 +1065,14 @@ function tag_get_name($tagids) {
 }
 
 /**
- * Returns the correlated tags of a tag, retrieved from the tag_correlation
- * table.  Make sure cron runs, otherwise the table will be empty and this
- * function won't return anything.
+ * Returns the correlated tags of a tag, retrieved from the tag_correlation table. Make sure cron runs, otherwise the table will be
+ * empty and this function won't return anything.
  *
- * @param int $tag_id is a single tag id
- * @return array an array of tag objects, empty if no correlated tags are found
+ * @package core_tag
+ * @access  private
+ * @param   int      $tag_id   is a single tag id
+ * @param   int      $limitnum this parameter does not appear to have any function???
+ * @return  array    an array of tag objects or an empty if no correlated tags are found
  */
 function tag_get_correlated($tag_id, $limitnum=null) {
     global $DB;
@@ -1018,11 +1099,12 @@ function tag_get_correlated($tag_id, $limitnum=null) {
 /**
  * Function that normalizes a list of tag names.
  *
- * @param mixed $tags array of tags, or a single tag.
- * @param int $case case to use for returned value (default: lower case).
- *     Either TAG_CASE_LOWER (default) or TAG_CASE_ORIGINAL
- * @return array of lowercased normalized tags, indexed by the normalized tag,
- *     in the same order as the original array. (Eg: 'Banana' => 'banana').
+ * @package core_tag
+ * @access  private
+ * @param   array/string $rawtags array of tags, or a single tag.
+ * @param   int          $case    case to use for returned value (default: lower case). Either TAG_CASE_LOWER (default) or TAG_CASE_ORIGINAL
+ * @return  array        lowercased normalized tags, indexed by the normalized tag, in the same order as the original array.
+ *                       (Eg: 'Banana' => 'banana').
  */
 function tag_normalize($rawtags, $case = TAG_CASE_LOWER) {
 
@@ -1055,11 +1137,13 @@ function tag_normalize($rawtags, $case = TAG_CASE_LOWER) {
 }
 
 /**
- * Count how many records are tagged with a specific tag,
+ * Count how many records are tagged with a specific tag.
  *
- * @param string $record record to look for ('post', 'user', etc.)
- * @param int $tag is a single tag id
- * @return int number of mathing tags.
+ * @package core_tag
+ * @access  private
+ * @param   string   $record_type record to look for ('post', 'user', etc.)
+ * @param   int      $tagid       is a single tag id
+ * @return  int      number of mathing tags.
  */
 function tag_record_count($record_type, $tagid) {
     global $DB;
@@ -1069,10 +1153,12 @@ function tag_record_count($record_type, $tagid) {
 /**
  * Determine if a record is tagged with a specific tag
  *
- * @param string $record_type the record type to look for
- * @param int $record_id the record id to look for
- * @param string $tag a tag name
- * @return bool true if it is tagged, false otherwise
+ * @package core_tag
+ * @access  private
+ * @param   string   $record_type the record type to look for
+ * @param   int      $record_id   the record id to look for
+ * @param   string   $tag         a tag name
+ * @return  bool/int true if it is tagged, 0 (false) otherwise
  */
 function tag_record_tagged_with($record_type, $record_id, $tag) {
     global $DB;
@@ -1086,8 +1172,9 @@ function tag_record_tagged_with($record_type, $record_id, $tag) {
 /**
  * Flag a tag as inapropriate
  *
- * @param mixed $tagids one (int) tagid, or an array of tagids
- * @return void
+ * @package core_tag
+ * @access  private
+ * @param   int|array $tagids a single tagid, or an array of tagids
  */
 function tag_set_flag($tagids) {
     global $DB;
@@ -1104,8 +1191,10 @@ function tag_set_flag($tagids) {
 /**
  * Remove the inapropriate flag on a tag
  *
- * @param mixed $tagids one (int) tagid, or an array of tagids
- * @return bool true if function succeeds, false otherwise
+ * @package core_tag
+ * @access  private
+ * @param   int|array $tagids a single tagid, or an array of tagids
+ * @return  bool      true    if function succeeds, false otherwise
  */
 function tag_unset_flag($tagids) {
     global $DB;
@@ -1120,9 +1209,12 @@ function tag_unset_flag($tagids) {
 
 /**
  * Return a list of page types
- * @param string $pagetype current page type
- * @param stdClass $parentcontext Block's parent context
- * @param stdClass $currentcontext Current context of block
+ *
+ * @package core_tag
+ * @access  private
+ * @param   string   $pagetype       current page type
+ * @param   stdClass $parentcontext  Block's parent context
+ * @param   stdClass $currentcontext Current context of block
  */
 function tag_page_type_list($pagetype, $parentcontext, $currentcontext) {
     return array(
diff --git a/tag/locallib.php b/tag/locallib.php
index 7b7cd460185..6c750b069b6 100644
--- a/tag/locallib.php
+++ b/tag/locallib.php
@@ -1,21 +1,40 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Moodle tag local library - output functions
+ *
+ * @package    core_tag
+ * @copyright  2007 Luiz Cruz <luiz.laydner@gmail.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU Public License
+ */
 
 require_once($CFG->dirroot.'/tag/lib.php');
 require_once($CFG->libdir.'/filelib.php');
 
 /**
- * locallib.php - moodle tag local library - output functions
+ * Prints or returns a HTML tag cloud with varying classes styles depending on the popularity and type of each tag.
  *
- * @licence http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package moodlecore
- *
- */
-
-/**
- * Prints a tag cloud
- *
- * @param array $tagcloud array of tag objects (fields: id, name, rawname, count and flag)
- * @param $return if true return html string
+ * @package  core_tag
+ * @access   public
+ * @category tag
+ * @param    int       $nr_of_tags Limit for the number of tags to return/display
+ * @param    bool      $return     if true the function will return the generated tag cloud instead of displaying it.
+ * @return string|null a HTML string or null if this function does the output
  */
 function tag_print_cloud($nr_of_tags=150, $return=false) {
     global $CFG, $DB;
@@ -69,9 +88,14 @@ function tag_print_cloud($nr_of_tags=150, $return=false) {
 }
 
 /**
- * This function is used by print_tag_cloud, to usort() the tags in the cloud.
- * See php.net/usort for the parameters documentation. This was originally in
- * blocks/blog_tags/block_blog_tags.php, named blog_tags_sort().
+ * This function is used by print_tag_cloud, to usort() the tags in the cloud. See php.net/usort for the parameters documentation.
+ * This was originally in blocks/blog_tags/block_blog_tags.php, named blog_tags_sort().
+ *
+ * @package core_tag
+ * @access  private
+ * @param   string $a Tag name to compare against $b
+ * @param   string $b Tag name to compare against $a
+ * @return  int    The result of the comparison/validation 1, 0 or -1
  */
 function tag_cloud_sort($a, $b) {
     global $CFG;
@@ -94,14 +118,19 @@ function tag_cloud_sort($a, $b) {
 /**
  * Prints a box with the description of a tag and its related tags
  *
- * @param stdClass $tag_object
- * @param $return if true return html string
+ * @package core_tag
+ * @access  public
+ * @todo    MDL-31149 create a system setting for $max_tags_displayed, instead of using an in code literal
+ * @param   stdClass    $tag_object
+ * @param   bool        $return     if true the function will return the generated tag cloud instead of displaying it.
+ * @return  string/null a HTML box showing a description of the tag object and it's relationsips or null if output is done directly
+ *                      in the function.
  */
 function tag_print_description_box($tag_object, $return=false) {
 
     global $USER, $CFG, $OUTPUT;
 
-    $max_tags_displayed = 10; // todo: turn this into a system setting
+    $max_tags_displayed = 10;
 
     $tagname  = tag_display_name($tag_object);
     $related_tags = tag_get_related_tags($tag_object->id, TAG_RELATED_ALL, $max_tags_displayed+1); // this gets one more than we want
@@ -147,8 +176,10 @@ function tag_print_description_box($tag_object, $return=false) {
 /**
  * Prints a box that contains the management links of a tag
  *
- * @param $tagid
- * @param $return if true return html string
+ * @access public
+ * @param  stdClass    $tag_object
+ * @param  bool        $return     if true the function will return the generated tag cloud instead of displaying it.
+ * @return string|null a HTML string or null if this function does the output
  */
 function tag_print_management_box($tag_object, $return=false) {
 
@@ -192,7 +223,9 @@ function tag_print_management_box($tag_object, $return=false) {
 /**
  * Prints the tag search box
  *
- * @param bool $return if true return html string
+ * @access public
+ * @param  bool        $return if true return html string
+ * @return string|null a HTML string or null if this function does the output
  */
 function tag_print_search_box($return=false) {
     global $CFG, $OUTPUT;
@@ -217,10 +250,12 @@ function tag_print_search_box($return=false) {
 /**
  * Prints the tag search results
  *
- * @param string $query text that tag names will be matched against
- * @param int $page current page
- * @param int $perpage nr of users displayed per page
- * @param $return if true return html string
+ * @access public
+ * @param string       $query text that tag names will be matched against
+ * @param int          $page current page
+ * @param int          $perpage nr of users displayed per page
+ * @param bool         $return if true return html string
+ * @return string|null a HTML string or null if this function does the output
  */
 function tag_print_search_results($query,  $page, $perpage, $return=false) {
 
@@ -290,13 +325,13 @@ function tag_print_search_results($query,  $page, $perpage, $return=false) {
 /**
  * Prints a table of the users tagged with the tag passed as argument
  *
- * @param $tag_object
- * @param int $users_per_row number of users per row to display
- * @param int $limitfrom prints users starting at this point (optional, required if $limitnum is set).
- * @param int $limitnum prints this many users (optional, required if $limitfrom is set).
- * @param $return if true return html string
+ * @param  int         $tag_object the tag we wish to return data for
+ * @param  int         $limitfrom (optional, required if $limitnum is set) prints users starting at this point.
+ * @param  int         $limitnum (optional, required if $limitfrom is set) prints this many users.
+ * @param  bool        $return if true return html string
+ * @return string|null a HTML string or null if this function does the output
  */
-function tag_print_tagged_users_table($tag_object, $limitfrom='' , $limitnum='', $return=false) {
+function tag_print_tagged_users_table($tag_object, $limitfrom='', $limitnum='', $return=false) {
 
     //List of users with this tag
     $userlist = tag_find_records($tag_object->name, 'user', $limitfrom, $limitnum);
@@ -314,8 +349,9 @@ function tag_print_tagged_users_table($tag_object, $limitfrom='' , $limitnum='',
 /**
  * Prints an individual user box
  *
- * @param $user user object (contains the following fields: id, firstname, lastname and picture)
- * @param $return if true return html string
+ * @param user_object  $user  (contains the following fields: id, firstname, lastname and picture)
+ * @param bool         $return if true return html string
+ * @return string|null a HTML string or null if this function does the output
  */
 function tag_print_user_box($user, $return=false) {
     global $CFG, $OUTPUT;
@@ -359,11 +395,13 @@ function tag_print_user_box($user, $return=false) {
         echo $output;
     }
 }
+
 /**
  * Prints a list of users
  *
- * @param array $userlist an array of user objects
- * @param $return if true return html string
+ * @param  array       $userlist an array of user objects
+ * @param  bool        $return if true return html string, otherwise output the result
+ * @return string|null a HTML string or null if this function does the output
  */
 function tag_print_user_list($userlist, $return=false) {