MDL-30991 - RSS - Doc-block clean up
authorJason Fowler <phalacee@gmail.com>
Wed, 11 Jan 2012 06:02:53 +0000 (14:02 +0800)
committerJason Fowler <phalacee@gmail.com>
Wed, 15 Feb 2012 07:19:59 +0000 (15:19 +0800)
blog/rsslib.php
lib/rsslib.php
mod/data/rsslib.php
mod/forum/rsslib.php
mod/glossary/rsslib.php
rss/file.php
rss/renderer.php

index 03c84ca..a851cbe 100644 (file)
@@ -1,8 +1,41 @@
 <?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/>.
+
+/**
+ * Blog RSS Management
+ *
+ * @package    core_blog
+ * @category   rss
+ * @copyright  2010 Andrew Davis
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 require_once($CFG->dirroot.'/lib/rsslib.php');
 require_once($CFG->dirroot .'/blog/lib.php');
 
+/**
+ * Build the URL for the RSS feed
+ *
+ * @param int    $contextid    The context under which the URL should be created
+ * @param int    $userid       The id of the user requesting the RSS Feed
+ * @param string $filtertype   The source of the RSS feed (site/course/group/user)
+ * @param int    $filterselect The id of the item defined by $filtertype
+ * @param int    $tagid        The id of the row in the tag table that identifies the RSS Feed
+ * @return string
+ */
 function blog_rss_get_url($contextid, $userid, $filtertype, $filterselect=0, $tagid=0) {
     $componentname = 'blog';
 
@@ -29,8 +62,15 @@ function blog_rss_get_url($contextid, $userid, $filtertype, $filterselect=0, $ta
     return rss_get_url($contextid, $userid, $componentname, $additionalargs);
 }
 
-// This function returns the icon (from theme) with the link to rss/file.php
-// needs some hacking to rss/file.php
+/**
+ * Print the link for the RSS feed with the correct RSS icon (Theme based)
+ *
+ * @param stdClass    $context      The context under which the URL should be created
+ * @param string      $filtertype   The source of the RSS feed (site/course/group/user)
+ * @param int         $filterselect The id of the item defined by $filtertype
+ * @param int         $tagid        The id of the row in the tag table that identifies the RSS Feed
+ * @param string      $tooltiptext  The tooltip to be displayed with the link
+ */
 function blog_rss_print_link($context, $filtertype, $filterselect=0, $tagid=0, $tooltiptext='') {
     global $CFG, $USER, $OUTPUT;
 
@@ -45,6 +85,15 @@ function blog_rss_print_link($context, $filtertype, $filterselect=0, $tagid=0, $
     print '<div class="mdl-right"><a href="'. $url .'"><img src="'. $rsspix .'" title="'. strip_tags($tooltiptext) .'" alt="'.get_string('rss').'" /></a></div>';
 }
 
+/**
+ * Build the URL for the RSS feed amd add it as a header
+ *
+ * @param stdClass    $context      The context under which the URL should be created
+ * @param string      $title        Name for the link to be added to the page header
+ * @param string      $filtertype   The source of the RSS feed (site/course/group/user)
+ * @param int         $filterselect The id of the item defined by $filtertype
+ * @param int         $tagid        The id of the row in the tag table that identifies the RSS Feed
+ */
 function blog_rss_add_http_header($context, $title, $filtertype, $filterselect=0, $tagid=0) {
     global $PAGE, $USER, $CFG;
 
@@ -63,8 +112,9 @@ function blog_rss_add_http_header($context, $title, $filtertype, $filterselect=0
 
 /**
  * Utility function to extract parameters needed to generate RSS URLs from the blog filters
- * @param <type> $filters
- * @return array array containing the id of the user/course/group, the relevant context and the filter type (site/user/course/group)
+ *
+ * @param  array $filters filters for the blog
+ * @return array array containing the id of the user/course/group, the relevant context and the filter type: site/user/course/group
  */
 function blog_rss_get_params($filters) {
     $thingid = $rsscontext = $filtertype = null;
@@ -99,8 +149,12 @@ function blog_rss_get_params($filters) {
     return array($thingid, $rsscontext, $filtertype);
 }
 
-
-// Generate any blog RSS feed via one function (called by ../rss/file.php)
+/**
+ * Generate any blog RSS feed via one function
+ *
+ * @param stdClass $context The context of the blog for which the feed it being generated
+ * @param array    $args    An array of arguements needed to build the feed (contextid, token, componentname, type, id, tagid)
+ */
 function blog_rss_get_feed($context, $args) {
     global $CFG, $SITE, $DB;
 
@@ -219,7 +273,14 @@ function blog_rss_get_feed($context, $args) {
     }
 }
 
-
+/**
+ * Retrieve the location and file name of a cached RSS feed
+ *
+ * @param string $type  The source of the RSS feed (site/course/group/user)
+ * @param int    $id    The id of the item defined by $type
+ * @param int    $tagid The id of the row in the tag table that identifies the RSS Feed
+ * @return string
+ */
 function blog_rss_file_name($type, $id, $tagid=0) {
     global $CFG;
 
@@ -230,7 +291,15 @@ function blog_rss_file_name($type, $id, $tagid=0) {
     }
 }
 
-//This function saves to file the rss feed specified in the parameters
+/**
+ * This function saves to file the rss feed specified in the parameters
+ *
+ * @param string $type     The source of the RSS feed (site/course/group/user)
+ * @param int    $id       The id of the item defined by $type
+ * @param int    $tagid    The id of the row in the tag table that identifies the RSS Feed
+ * @param string $contents The contents of the RSS Feed file
+ * @return bool whether the save was successful or not
+ */
 function blog_rss_save_file($type, $id, $tagid=0, $contents='') {
     global $CFG;
 
index 5cec604..01ac161 100644 (file)
 /**
  * This file contains all the common stuff to be used in RSS System
  *
- * @package    core
- * @subpackage rss
+ * @package    core_rss
+ * @category   rss
  * @copyright  1999 onwards Martin Dougiamas  {@link http://moodle.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
- function rss_add_http_header($context, $componentname, $componentinstance, $title) {
+/**
+ * Build the URL for the RSS feed and add it as a header
+ *
+ * @param stdClass    $context           The context under which the URL should be created
+ * @param string      $componentname     The name of the component for which the RSS feed exists
+ * @param stdClass    $componentinstance The instance of the component
+ * @param string      $title             Name for the link to be added to the page header
+ */
+function rss_add_http_header($context, $componentname, $componentinstance, $title) {
     global $PAGE, $USER;
 
     $componentid = null;
@@ -41,10 +49,14 @@ defined('MOODLE_INTERNAL') || die();
  }
 
 /**
- * This function returns the icon (from theme) with the link to rss/file.php
+ * Print the link for the RSS feed with the correct RSS icon
  *
- * @global object
- * @global object
+ * @param stdClass    $contextid     The id of the context under which the URL should be created
+ * @param int         $userid        The source of the RSS feed (site/course/group/user)
+ * @param string      $componentname The name of the component for which the feed exists
+ * @param string      $id            The name by which to call the RSS File
+ * @param string      $tooltiptext   The tooltip to be displayed with the link
+ * @return string HTML output for the RSS link
  */
 function rss_get_link($contextid, $userid, $componentname, $id, $tooltiptext='') {
     global $OUTPUT;
@@ -60,11 +72,11 @@ function rss_get_link($contextid, $userid, $componentname, $id, $tooltiptext='')
 /**
  * This function returns the URL for the RSS XML file.
  *
- * @global object
- * @param int contextid the course id
- * @param int userid the current user id
- * @param string modulename the name of the current module. For example "forum"
+ * @param int    $contextid      the course id
+ * @param int    $userid         the current user id
+ * @param string $componentname  the name of the current component. For example "forum"
  * @param string $additionalargs For modules, module instance id
+ * @return string the url of the RSS feed
  */
 function rss_get_url($contextid, $userid, $componentname, $additionalargs) {
     global $CFG;
@@ -74,7 +86,13 @@ function rss_get_url($contextid, $userid, $componentname, $additionalargs) {
 }
 
 /**
- * This function prints the icon (from theme) with the link to rss/file.php
+ * Print the link for the RSS feed with the correct RSS icon (Theme based)
+ *
+ * @param stdClass    $contextid     The id of the context under which the URL should be created
+ * @param int         $userid        The source of the RSS feed (site/course/group/user)
+ * @param string      $componentname The name of the component for which the feed exists
+ * @param string      $id            The name by which to call the RSS File
+ * @param string      $tooltiptext   The tooltip to be displayed with the link
  */
 function rss_print_link($contextid, $userid, $componentname, $id, $tooltiptext='') {
     print rss_get_link($contextid, $userid, $componentname, $id, $tooltiptext);
@@ -83,11 +101,9 @@ function rss_print_link($contextid, $userid, $componentname, $id, $tooltiptext='
 
 /**
  * Given an object, deletes all RSS files associated with it.
- * Relies on a naming convention. See rss_get_filename()
  *
- * @param string $componentname the name of the module ie 'forum'. Used to construct the cache path.
- * @param object $instance An object with an id member variable ie $forum, $glossary.
- * @return void
+ * @param string   $componentname the name of the module ie 'forum'. Used to construct the cache path.
+ * @param stdClass $instance      An object with an id member variable ie $forum, $glossary.
  */
 function rss_delete_file($componentname, $instance) {
     global $CFG;
@@ -107,9 +123,12 @@ function rss_delete_file($componentname, $instance) {
 
 /**
  * Are RSS feeds enabled for the supplied module instance?
- * @param object $instance An instance of an activity module ie $forum, $glossary.
- * @param boolean $hasrsstype Should there be a rsstype member variable?
- * @param boolean $hasrssarticles Should there be a rssarticles member variable?
+ *
+ * @param string   $modname        The name of the module to be checked
+ * @param stdClass $instance       An instance of an activity module ie $forum, $glossary.
+ * @param bool     $hasrsstype     Should there be a rsstype member variable?
+ * @param bool     $hasrssarticles Should there be a rssarticles member variable?
+ * @return bool whether or not RSS is enabled for the module
  */
 function rss_enabled_for_mod($modname, $instance=null, $hasrsstype=true, $hasrssarticles=true) {
     if ($hasrsstype) {
@@ -135,10 +154,11 @@ function rss_enabled_for_mod($modname, $instance=null, $hasrsstype=true, $hasrss
 /**
  * This function saves to file the rss feed specified in the parameters
  *
- * @global object
- * @param string $componentname the module name ie forum. Used to create a cache directory.
- * @param string $filename the name of the file to be created ie "1234"
- * @param string $contents the data to be written to the file
+ * @param string $componentname  the module name ie forum. Used to create a cache directory.
+ * @param string $filename       the name of the file to be created ie "rss.xml"
+ * @param string $contents       the data to be written to the file
+ * @param bool   $expandfilename whether or not the fullname of the RSS file should be used
+ * @return bool whether the save was successful or not
  */
 function rss_save_file($componentname, $filename, $contents, $expandfilename=true) {
     global $CFG;
@@ -167,12 +187,25 @@ function rss_save_file($componentname, $filename, $contents, $expandfilename=tru
     return $status;
 }
 
-
+/**
+ * Retrieve the location and file name of a cached RSS feed
+ *
+ * @param string $componentname the name of the component the RSS feed is being created for
+ * @param string $filename the name of the RSS FEED
+ * @return string The full name and path of the RSS file
+ */
 function rss_get_file_full_name($componentname, $filename) {
     global $CFG;
     return "$CFG->cachedir/rss/$componentname/$filename.xml";
 }
 
+/**
+ * Construct the file name of the RSS File
+ *
+ * @param stdClass $instance the instance of the source of the RSS feed
+ * @param string $sql the SQL used to produce the RSS feed
+ * @return string the name of the RSS file
+ */
 function rss_get_file_name($instance, $sql) {
     return $instance->id.'_'.md5($sql);
 }
@@ -180,8 +213,10 @@ function rss_get_file_name($instance, $sql) {
 /**
  * This function return all the common headers for every rss feed in the site
  *
- * @global object
- * @global object
+ * @param string $title       the title for the RSS Feed
+ * @param string $link        the link for the origin of the RSS feed
+ * @param string $description the description of the contents of the RSS feed
+ * @return bool|string the standard header for the RSS feed
  */
 function rss_standard_header($title = NULL, $link = NULL, $description = NULL) {
     global $CFG, $USER, $OUTPUT;
@@ -248,12 +283,19 @@ function rss_standard_header($title = NULL, $link = NULL, $description = NULL) {
     }
 }
 
-//This function returns the rss XML code for every item passed in the array
-//item->title: The title of the item
-//item->author: The author of the item. Optional !!
-//item->pubdate: The pubdate of the item
-//item->link: The link url of the item
-//item->description: The content of the item
+
+/**
+ * Generates the rss XML code for every item passed in the array
+ *
+ * item->title: The title of the item
+ * item->author: The author of the item. Optional !!
+ * item->pubdate: The pubdate of the item
+ * item->link: The link url of the item
+ * item->description: The content of the item
+ *
+ * @param array $items an array of item objects
+ * @return bool|string the rss XML code for every item passed in the array
+ */
 function rss_add_items($items) {
     global $CFG;
 
@@ -300,6 +342,12 @@ function rss_add_items($items) {
 
 /**
  * This function return all the common footers for every rss feed in the site
+ *
+ * @param string $title       Not used at all
+ * @param string $link        Not used at all
+ * @param string $description Not used at all
+ * @todo  MDL-31050 Fix/Remove this function
+ * @return string
  */
 function rss_standard_footer($title = NULL, $link = NULL, $description = NULL) {
     $status = true;
@@ -313,10 +361,12 @@ function rss_standard_footer($title = NULL, $link = NULL, $description = NULL) {
     return $result;
 }
 
+
 /**
- * This function return an error xml file (string)
- * to be sent when a rss is required (file.php)
- * and something goes wrong
+ * This function return an error xml file (string) to be sent when a rss is required (file.php) and something goes wrong
+ *
+ * @param string $errortype Type of error to send, default is rsserror
+ * @return stdClass returns a XML Feed with an error message in it
  */
 function rss_geterrorxmlfile($errortype = 'rsserror') {
     global $CFG;
@@ -344,6 +394,12 @@ function rss_geterrorxmlfile($errortype = 'rsserror') {
     return $return;
 }
 
+/**
+ * Get the ID of the user from a given RSS Token
+ *
+ * @param string $token the RSS token you would like to use to find the user id
+ * @return int The user id
+ */
 function rss_get_userid_from_token($token) {
     global $DB;
     $record = $DB->get_record('user_private_key', array('script'=>'rss','value' => $token), 'userid', IGNORE_MISSING);
@@ -353,21 +409,32 @@ function rss_get_userid_from_token($token) {
     return null;
 }
 
+/**
+ * Get the RSS Token from a given user id
+ *
+ * @param int $userid The user id
+ * @return string the RSS token for the user
+ */
 function rss_get_token($userid) {
     return get_user_key('rss', $userid);
 }
 
+/**
+ * Removes the token for the given user from the DB
+ * @param int $userid The user id for the token you wish to delete
+ */
 function rss_delete_token($userid) {
     delete_user_key('rss', $userid);
 }
 
-// ===== This function are used to write XML tags =========
-// [stronk7]: They are similar to the glossary export and backup generation
-// but I've replicated them here because they have some minor
-// diferences. Someday all they should go to a common place.
-
 /**
  * Return the xml start tag
+ *
+ * @param string $tag        the xml tag name
+ * @param int    $level      the indentation level
+ * @param bool   $endline    whether or not to start new tags on a new line
+ * @param array  $attributes the attributes of the xml tag
+ * @return string the xml start tag
  */
 function rss_start_tag($tag,$level=0,$endline=false,$attributes=null) {
     if ($endline) {
@@ -386,6 +453,10 @@ function rss_start_tag($tag,$level=0,$endline=false,$attributes=null) {
 
 /**
  * Return the xml end tag
+ * @param string $tag        the xml tag name
+ * @param int    $level      the indentation level
+ * @param bool   $endline    whether or not to start new tags on a new line
+ * @return string the xml end tag
  */
 function rss_end_tag($tag,$level=0,$endline=true) {
     if ($endline) {
@@ -397,7 +468,14 @@ function rss_end_tag($tag,$level=0,$endline=true) {
 }
 
 /**
- * Return the start tag, the contents and the end tag
+ * Return the while xml element, including content
+ *
+ * @param string $tag        the xml tag name
+ * @param int    $level      the indentation level
+ * @param bool   $endline    whether or not to start new tags on a new line
+ * @param string $content    the text to go inside the tag
+ * @param array  $attributes the attributes of the xml tag
+ * @return string the whole xml element
  */
 function rss_full_tag($tag,$level=0,$endline=true,$content,$attributes=null) {
     $st = rss_start_tag($tag,$level,$endline,$attributes);
@@ -411,19 +489,9 @@ function rss_full_tag($tag,$level=0,$endline=true,$content,$attributes=null) {
 /**
  * Adds RSS Media Enclosures for "podcasting" by including attachments that
  * are specified in the item->attachments field.
- * Note also that iTunes does some things very badly - one thing it does is
- * refuse to download ANY of your files if you're using "file.php?file=blah"
- * and can't use the more elegant "file.php/blah" slasharguments setting. It
- * stops after ".php" and assumes the files are not media files, despite what
- * is specified in the "type" attribute. Dodgy coding all round!
- *
- * Authors
- *     - Hannes Gassert <hannes@mediagonal.ch>
- *     - Dan Stowell
  *
- * @global object
- * @param    $item     object representing an RSS item
- * @return   string    RSS enclosure tags
+ * @param stdClass $item representing an RSS item
+ * @return string RSS enclosure tags
  */
 function rss_add_enclosures($item){
     global $CFG;
index 25791df..3db1c44 100644 (file)
@@ -1,8 +1,37 @@
 <?php
-    // This file adds support to rss feeds generation
 
-    // This function is the main entry point to database module
-    // rss feeds generation.
+// 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/>.
+
+
+/**
+ * This file contains all the common stuff to be used for RSS in the Database Module
+ *
+ * @package    mod_data
+ * @category   rss
+ * @copyright  1999 onwards Martin Dougiamas  {@link http://moodle.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Generates the Database modules RSS Feed
+ *
+ * @param strClass $context the context the feed should be created under
+ * @param array $args array of arguments to be used in the creation of the RSS Feed
+ * @return NULL|string NULL if there is nothing to return, or the file path of the cached file if there is
+ */
     function data_rss_get_feed($context, $args) {
         global $CFG, $DB;
 
@@ -52,7 +81,7 @@
             if (!$records = $DB->get_records_sql($sql, array(), 0, $data->rssarticles)) {
                 return null;
             }
-            
+
             $firstrecord = array_shift($records);  // Get the first and put it back
             array_unshift($records, $firstrecord);
 
 
         return $cachedfilepath;
     }
-
+/**
+ * Creates and returns a SQL query for the items that would be included in the RSS Feed
+ *
+ * @param stdClass $data database instance object
+ * @param int      $time epoch timestamp to compare time-modified to, 0 for all or a proper value
+ * @return string SQL query string to get the items for the databse RSS Feed
+ */
     function data_rss_get_sql($data, $time=0) {
         //do we only want new posts?
         if ($time) {
      * If there is new stuff in since $time this returns true
      * Otherwise it returns false.
      *
-     * @param object $data the data activity object
-     * @param int $time timestamp
-     * @return bool
+     * @param stdClass $data the data activity object
+     * @param int      $time timestamp
+     * @return bool true if there is new stuff for the RSS Feed
      */
     function data_rss_newstuff($data, $time) {
         global $DB;
index 7115fe7..e5b7809 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
-* This file adds support to rss feeds generation
-*
-* @package mod-forum
-* @copyright 2001 Eloy Lafuente (stronk7) http://contiento.com
-* @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
-*/
+ * This file adds support to rss feeds generation
+ *
+ * @package mod_forum
+ * @category rss
+ * @copyright 2001 Eloy Lafuente (stronk7) http://contiento.com
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 /**
  * Returns the path to the cached rss feed contents. Creates/updates the cache if necessary.
- * @global object $CFG
- * @global object $DB
- * @param object $context the context
- * @param int $forumid the ID of the forum
- * @param array $args the arguments received in the url
+ * @param stdClass $context the context
+ * @param array    $args    the arguments received in the url
  * @return string the full path to the cached RSS feed directory. Null if there is a problem.
  */
 function forum_rss_get_feed($context, $args) {
@@ -88,8 +86,7 @@ function forum_rss_get_feed($context, $args) {
 /**
  * Given a forum object, deletes all cached RSS files associated with it.
  *
- * @param object $forum
- * @return void
+ * @param stdClass $forum
  */
 function forum_rss_delete_file($forum) {
     rss_delete_file('mod_forum', $forum);
@@ -102,10 +99,10 @@ function forum_rss_delete_file($forum) {
  * If there is new stuff in the forum since $time this returns true
  * Otherwise it returns false.
  *
- * @param object $forum the forum object
- * @param object $cm
- * @param int $time timestamp
- * @return bool
+ * @param stdClass $forum the forum object
+ * @param stdClass $cm    Course Module object
+ * @param int      $time  check for items since this epoch timestamp
+ * @return bool True for new items
  */
 function forum_rss_newstuff($forum, $cm, $time) {
     global $DB;
@@ -116,6 +113,14 @@ function forum_rss_newstuff($forum, $cm, $time) {
     return ($recs && !empty($recs));
 }
 
+/**
+ * Determines which type of SQL query is required, one for posts or one for discussions, and returns the appropriate query
+ *
+ * @param stdClass $forum the forum object
+ * @param stdClass $cm    Course Module object
+ * @param int      $time  check for items since this epoch timestamp
+ * @return string the SQL query to be used to get the Discussion/Post details from the forum table of the database
+ */
 function forum_rss_get_sql($forum, $cm, $time=0) {
     $sql = null;
 
@@ -130,6 +135,14 @@ function forum_rss_get_sql($forum, $cm, $time=0) {
     return $sql;
 }
 
+/**
+ * Generates the SQL query used to get the Discussion details from the forum table of the database
+ *
+ * @param stdClass $forum     the forum object
+ * @param stdClass $cm        Course Module object
+ * @param int      $newsince  check for items since this epoch timestamp
+ * @return string the SQL query to be used to get the Discussion details from the forum table of the database
+ */
 function forum_rss_feed_discussions_sql($forum, $cm, $newsince=0) {
     global $CFG, $DB, $USER;
 
@@ -185,6 +198,14 @@ function forum_rss_feed_discussions_sql($forum, $cm, $newsince=0) {
     return $sql;
 }
 
+/**
+ * Generates the SQL query used to get the Post details from the forum table of the database
+ *
+ * @param stdClass $forum     the forum object
+ * @param stdClass $cm        Course Module object
+ * @param int      $newsince  check for items since this epoch timestamp
+ * @return string the SQL query to be used to get the Post details from the forum table of the database
+ */
 function forum_rss_feed_posts_sql($forum, $cm, $newsince=0) {
     $modcontext = get_context_instance(CONTEXT_MODULE, $cm->id);
 
@@ -228,6 +249,15 @@ function forum_rss_feed_posts_sql($forum, $cm, $newsince=0) {
     return $sql;
 }
 
+/**
+ * Retrieve the correct SQL snippet for group-only forums
+ *
+ * @param stdClass $cm           Course Module object
+ * @param int      $groupmode    the mode in which the forum's groups are operating
+ * @param bool     $currentgroup true if the user is from the a group enabled on the forum
+ * @param stdClass $modcontext   The context instance of the forum module
+ * @return string SQL Query for group details of the forum
+ */
 function forum_rss_get_group_sql($cm, $groupmode, $currentgroup, $modcontext=null) {
     $groupselect = '';
 
@@ -251,15 +281,15 @@ function forum_rss_get_group_sql($cm, $groupmode, $currentgroup, $modcontext=nul
     return $groupselect;
 }
 
-
-
-
 /**
  * This function return the XML rss contents about the forum
  * It returns false if something is wrong
  *
- * @param object $forum
- * @param bool
+ * @param stdClass $forum the forum object
+ * @param string   $sql   The SQL used to retrieve the contents from the database
+ * @return bool|string false if the contents is empty, otherwise the contents of the feed is returned
+ *
+ * @Todo MDL-31129 implement post attachment handling
  */
 function forum_rss_feed_contents($forum, $sql) {
     global $CFG, $DB;
@@ -302,7 +332,7 @@ function forum_rss_feed_contents($forum, $sql) {
             $formatoptions->trusted = $rec->posttrust;
             $item->description = format_text($rec->postmessage,$rec->postformat,$formatoptions,$forum->course);
 
-            //TODO: implement post attachment handling
+            //TODO: MDL-31129 implement post attachment handling
             /*if (!$isdiscussion) {
                 $post_file_area_name = str_replace('//', '/', "$forum->course/$CFG->moddata/forum/$forum->id/$rec->postid");
                 $post_files = get_directory_list("$CFG->dataroot/$post_file_area_name");
index 5134126..f4d5251 100644 (file)
@@ -1,8 +1,37 @@
 <?php
-    //This file adds support to rss feeds generation
 
-    //This function is the main entry point to glossary
-    //rss feeds generation.
+// 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/>.
+
+
+/**
+ * This file adds support to rss feeds generation
+ *
+ * @package mod_glossary
+ * @category rss
+ * @copyright  1999 onwards Martin Dougiamas  {@link http://moodle.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Returns the path to the cached rss feed contents. Creates/updates the cache if necessary.
+ *
+ * @param stdClass $context the context
+ * @param array    $args    the arguments received in the url
+ * @return string the full path to the cached RSS feed directory. Null if there is a problem.
+ */
     function glossary_rss_get_feed($context, $args) {
         global $CFG, $DB, $COURSE, $USER;
 
         return $cachedfilepath;
     }
 
+    /**
+     * The appropriate SQL query for the glossary items to go into the RSS feed
+     *
+     * @param stdClass $glossary the glossary object
+     * @param int      $time     check for items since this epoch timestamp
+     * @return string the SQL query to be used to get the entried from the glossary table of the database
+     */
     function glossary_rss_get_sql($glossary, $time=0) {
         //do we only want new items?
         if ($time) {
      * If there is new stuff in since $time this returns true
      * Otherwise it returns false.
      *
-     * @param object $glossary the glossary activity object
-     * @param int $time timestamp
-     * @return bool
+     * @param stdClass $glossary the glossary activity object
+     * @param int      $time     epoch timestamp to compare new items against, 0 for everyting
+     * @return bool true if there are new items
      */
     function glossary_rss_newstuff($glossary, $time) {
         global $DB;
index 2b9c990..16976c0 100644 (file)
  * then finds and calls a function in the relevant component to
  * actually check security and create the RSS stream
  *
- * @package   moodlecore
- * @copyright 1999 onwards Martin Dougiamas  http://moodle.com
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package    core_rss
+ * @category   rss
+ * @copyright  1999 onwards Martin Dougiamas {@link http://moodle.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 
-// Disable moodle specific debug messages and any errors in output
-define('NO_DEBUG_DISPLAY', true);//comment this out to see any error messages during RSS generation
+/** NO_DEBUG_DISPLAY - bool, Disable moodle specific debug messages and any errors in output. Set to false to see any error messages during RSS generation */
+define('NO_DEBUG_DISPLAY', true);
 
-// Sessions not used here, we recreate $USER every time we are called
+/** NO_MOODLE_COOKIES - bool, Disable the use of sessions/cookies - we recreate $USER for every call. */
 define('NO_MOODLE_COOKIES', true);
 
 require_once('../config.php');
@@ -178,8 +179,16 @@ if (empty($pathname) || !file_exists($pathname)) {
 send_file($pathname, 'rss.xml', 3600);   // Cached by browsers for 1 hour
 
 
-/*
- * Sends an error formatted as an rss file and then dies
+/**
+ * Sends an error formatted as an rss file and then exits
+ *
+ * @package core_rss
+ * @category rss
+ *
+ * @param string $error the error type, default is rsserror
+ * @param string $filename the name of the file to create (NOT USED)
+ * @param int $lifetime UNSURE (NOT USED)
+ * @uses exit
  */
 function rss_error($error='rsserror', $filename='rss.xml', $lifetime=0) {
     send_file(rss_geterrorxmlfile($error), $filename, $lifetime, false, true);
index 862bec3..3d7040c 100644 (file)
 
 /**
  * Web service documentation renderer.
- * @package   rss
- * @copyright 2010 Moodle Pty Ltd (http://moodle.com)
- * @author    Andrew Davis
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package    core_rss
+ * @category   rss
+ * @copyright  2010 Andrew Davis
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+/**
+ * Web service documentation renderer extending the plugin_renderer_base class.
+ * @package    core_rss
+ * @category   rss
+ * @copyright  2010 Andrew Davis
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class core_rss_renderer extends plugin_renderer_base {
     /**
-     *  Returns the html for the token reset confirmation box
-     * @param object $token to reset
+     * Returns the html for the token reset confirmation box
      * @return string html
      */
     public function user_reset_rss_token_confirmation() {
@@ -45,9 +51,8 @@ class core_rss_renderer extends plugin_renderer_base {
     }
 
     /**
-     * Display user tokens with buttons to reset them
-     * @param object $tokens
-     * @param int $userid
+     * Display a user token with buttons to reset it
+     * @param string $token The token to be displayed
      * @return string html code
      */
     public function user_rss_token_box($token) {