Merge branch 's17_MDL-30984_comment_docblock_master' of git://github.com/dongsheng...
authorEloy Lafuente (stronk7) <stronk7@moodle.org>
Thu, 16 Feb 2012 01:07:48 +0000 (02:07 +0100)
committerEloy Lafuente (stronk7) <stronk7@moodle.org>
Thu, 16 Feb 2012 01:07:48 +0000 (02:07 +0100)
blocks/comments/lib.php
blog/lib.php
comment/comment_ajax.php
comment/comment_post.php
comment/index.php
comment/lib.php
comment/locallib.php
mod/data/lib.php
mod/glossary/lib.php
mod/wiki/lib.php

index 3f10939..30cca1e 100644 (file)
@@ -28,6 +28,9 @@ defined('MOODLE_INTERNAL') || die();
 /**
  * Validate comment parameter before perform other comments actions
  *
+ * @package  block_comments
+ * @category comment
+ *
  * @param stdClass $comment_param {
  *              context  => context the context object
  *              courseid => int course id
@@ -50,6 +53,9 @@ function block_comments_comment_validate($comment_param) {
 /**
  * Running addtional permission check on plugins
  *
+ * @package  block_comments
+ * @category comment
+ *
  * @param stdClass $args
  * @return array
  */
@@ -60,6 +66,9 @@ function block_comments_comment_permissions($args) {
 /**
  * Validate comment data before displaying comments
  *
+ * @package  block_comments
+ * @category comment
+ *
  * @param stdClass $comment
  * @param stdClass $args
  * @return boolean
index 5a92fb5..080df70 100644 (file)
@@ -1002,6 +1002,9 @@ function blog_get_associated_count($courseid, $cmid=null) {
  * Capability check has been done in comment->check_permissions(), we
  * don't need to do it again here.
  *
+ * @package  core_blog
+ * @category comment
+ *
  * @param stdClass $comment_param {
  *              context  => context the context object
  *              courseid => int course id
@@ -1018,6 +1021,9 @@ function blog_comment_permissions($comment_param) {
 /**
  * Validate comment parameter before perform other comments actions
  *
+ * @package  core_blog
+ * @category comment
+ *
  * @param stdClass $comment {
  *              context  => context the context object
  *              courseid => int course id
index 828d5c8..91b99ca 100644 (file)
 
 /*
  * Handling all ajax request for comments API
+ *
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 define('AJAX_SCRIPT', true);
 
index 4e852b4..b7a39a8 100644 (file)
 
 /*
  * Handling new comments from non-js comments interface
+ *
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 require_once('../config.php');
 require_once($CFG->dirroot . '/comment/lib.php');
index b9a2abd..ab5daa3 100644 (file)
 
 /*
  * Comments management interface
+ *
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 require_once('../config.php');
 require_once($CFG->libdir.'/adminlib.php');
index 99e92f9..171e619 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Comment is helper class to add/delete comments anywhere in moodle
+ * Functions and classes for commenting
  *
- * @package   comment
- * @copyright 2010 Dongsheng Cai <dongsheng@moodle.com>
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-
 defined('MOODLE_INTERNAL') || die();
 
+/**
+ * Comment is helper class to add/delete comments anywhere in moodle
+ *
+ * @package   core
+ * @category  comment
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class comment {
-    /**
-     * there may be several comment box in one page
-     * so we need a client_id to recognize them
-     * @var integer
-     */
+    /** @var int there may be several comment box in one page so we need a client_id to recognize them */
     private $cid;
-    /**
-     * commentarea is used to specify different
-     * parts shared the same itemid
-     * @var string
-     */
+    /** @var string commentarea is used to specify different parts shared the same itemid */
     private $commentarea;
-    /**
-     * itemid is used to associate with commenting content
-     * @var integer
-     */
+    /** @var int itemid is used to associate with commenting content */
     private $itemid;
-    /**
-     * this html snippet will be used as a template
-     * to build comment content
-     * @var string
-     */
+    /** @var string this html snippet will be used as a template to build comment content */
     private $template;
-    /**
-     * The context id for comments
-     * @var int
-     */
+    /** @var int The context id for comments */
     private $contextid;
-    /**
-     * The context itself
-     * @var stdClass
-     */
+    /** @var stdClass The context itself */
     private $context;
-    /**
-     * The course id for comments
-     * @var int
-     */
+    /** @var int The course id for comments */
     private $courseid;
-    /**
-     * course module object, only be used to help find pluginname automatically
-     * if pluginname is specified, it won't be used at all
-     * @var stdClass
-     */
+    /** @var stdClass course module object, only be used to help find pluginname automatically */
     private $cm;
-    /**
-     * The component that this comment is for. It is STRONGLY recommended to set this.
-     * @var string
-     */
+    /** @var string The component that this comment is for. It is STRONGLY recommended to set this. */
     private $component;
-    /**
-     * This is calculated by normalising the component
-     * @var string
-     */
+    /** @var string This is calculated by normalising the component */
     private $pluginname;
-    /**
-     * This is calculated by normalising the component
-     * @var string
-     */
+    /** @var string This is calculated by normalising the component */
     private $plugintype;
-    /**
-     * Whether the user has the required capabilities/permissions to view comments.
-     * @var bool
-     */
+    /** @var bool Whether the user has the required capabilities/permissions to view comments. */
     private $viewcap = false;
-    /**
-     * Whether the user has the required capabilities/permissions to post comments.
-     * @var bool
-     */
+    /** @var bool Whether the user has the required capabilities/permissions to post comments. */
     private $postcap = false;
-    /**
-     * to costomize link text
-     * @var string
-     */
+    /** @var string to customize link text */
     private $linktext;
-    /**
-     * If set to true then comment sections won't be able to be opened and closed
-     * instead they will always be visible.
-     * @var bool
-     */
+    /** @var bool If set to true then comment sections won't be able to be opened and closed instead they will always be visible. */
     protected $notoggle = false;
-    /**
-     * If set to true comments are automatically loaded as soon as the page loads.
-     * Normally this happens when the user expands the comment section.
-     * @var bool
-     */
+    /** @var bool If set to true comments are automatically loaded as soon as the page loads. */
     protected $autostart = false;
-    /**
-     * If set to true the total count of comments is displayed when displaying comments.
-     * @var bool
-     */
+    /** @var bool If set to true the total count of comments is displayed when displaying comments. */
     protected $displaytotalcount = false;
-    /**
-     * If set to true a cancel button will be shown on the form used to submit comments.
-     * @var bool
-     */
+    /** @var bool If set to true a cancel button will be shown on the form used to submit comments. */
     protected $displaycancel = false;
-    /**
-     * The number of comments associated with this comments params
-     * @var int
-     */
+    /** @var int The number of comments associated with this comments params */
     protected $totalcommentcount = null;
 
-    /**#@+
-     * static variable will be used by non-js comments UI
-     */
+    /** @var bool Use non-javascript UI */
     private static $nonjs = false;
+    /** @var int comment itemid used in non-javascript UI */
     private static $comment_itemid = null;
+    /** @var int comment context used in non-javascript UI */
     private static $comment_context = null;
+    /** @var string comment area used in non-javascript UI */
     private static $comment_area = null;
+    /** @var string comment page used in non-javascript UI */
     private static $comment_page = null;
+    /** @var string comment itemid component in non-javascript UI */
     private static $comment_component = null;
-    /**#@-*/
 
     /**
      * Construct function of comment class, initialise
      * class members
-     * @param stdClass $options
-     * @param object $options {
+     *
+     * @param stdClass $options {
      *            context => context context to use for the comment [required]
      *            component => string which plugin will comment being added to [required]
      *            itemid  => int the id of the associated item (forum post, glossary item etc) [required]
@@ -301,7 +247,6 @@ class comment {
      * A coding_error is now thrown if code attempts to change the component.
      *
      * @param string $component
-     * @return void
      */
     public function set_component($component) {
         if (!empty($this->component) && $this->component !== $component) {
@@ -443,7 +388,7 @@ class comment {
     /**
      * Prepare comment code in html
      * @param  boolean $return
-     * @return mixed
+     * @return string|void
      */
     public function output($return = true) {
         global $PAGE, $OUTPUT;
@@ -536,7 +481,7 @@ class comment {
      * Return matched comments
      *
      * @param  int $page
-     * @return mixed
+     * @return array
      */
     public function get_comments($page = '') {
         global $DB, $CFG, $USER, $OUTPUT;
@@ -646,7 +591,8 @@ class comment {
      *
      * @global moodle_database $DB
      * @param string $content
-     * @return mixed
+     * @param int $format
+     * @return stdClass
      */
     public function add($content, $format = FORMAT_MOODLE) {
         global $CFG, $DB, $USER, $OUTPUT;
@@ -721,7 +667,7 @@ class comment {
      * Delete a comment
      *
      * @param  int $commentid
-     * @return mixed
+     * @return bool
      */
     public function delete($commentid) {
         global $DB, $USER;
@@ -740,9 +686,9 @@ class comment {
      * Print comments
      *
      * @param int $page
-     * @param boolean $return return comments list string or print it out
-     * @param boolean $nonjs print nonjs comments list or not?
-     * @return mixed
+     * @param bool $return return comments list string or print it out
+     * @param bool $nonjs print nonjs comments list or not?
+     * @return string|void
      */
     public function print_comments($page = 0, $return = true, $nonjs = true) {
         global $DB, $CFG, $PAGE;
@@ -935,5 +881,12 @@ class comment {
     }
 }
 
+/**
+ * Comment exception class
+ *
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class comment_exception extends moodle_exception {
 }
index fd62b61..5a8b0d7 100644 (file)
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Functions and classes for comments management
+ *
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+defined('MOODLE_INTERNAL') || die();
+
 /**
  * comment_manager is helper class to manage moodle comments in admin page (Reports->Comments)
  *
- * @package   comment
- * @copyright  2010 Dongsheng Cai <dongsheng@moodle.com>
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class comment_manager {
 
-    /**
-     * The number of comments to display per page
-     * @var int
-     */
+    /** @var int The number of comments to display per page */
     private $perpage;
 
     /**
@@ -85,7 +91,6 @@ class comment_manager {
      * @global moodle_page $PAGE
      * @global moodle_database $DB
      * @param int $courseid
-     * @return void
      */
     private function setup_course($courseid) {
         global $PAGE, $DB;
@@ -136,7 +141,7 @@ class comment_manager {
     /**
      * Print comments
      * @param int $page
-     * @return boolean return false if no comments available
+     * @return bool return false if no comments available
      */
     public function print_comments($page = 0) {
         global $OUTPUT, $CFG, $OUTPUT, $DB;
index 364ad4c..d0c6b39 100644 (file)
@@ -3252,6 +3252,9 @@ function data_presets_export($course, $cm, $data, $tostorage=false) {
  * Capability check has been done in comment->check_permissions(), we
  * don't need to do it again here.
  *
+ * @package  mod_data
+ * @category comment
+ *
  * @param stdClass $comment_param {
  *              context  => context the context object
  *              courseid => int course id
@@ -3279,6 +3282,9 @@ function data_comment_permissions($comment_param) {
 /**
  * Validate comment parameter before perform other comments actions
  *
+ * @package  mod_data
+ * @category comment
+ *
  * @param stdClass $comment_param {
  *              context  => context the context object
  *              courseid => int course id
index 5f1417d..2a83818 100644 (file)
@@ -2789,6 +2789,9 @@ function glossary_extend_settings_navigation(settings_navigation $settings, navi
  * Capability check has been done in comment->check_permissions(), we
  * don't need to do it again here.
  *
+ * @package  mod_glossary
+ * @category comment
+ *
  * @param stdClass $comment_param {
  *              context  => context the context object
  *              courseid => int course id
@@ -2805,6 +2808,9 @@ function glossary_comment_permissions($comment_param) {
 /**
  * Validate comment parameter before perform other comments actions
  *
+ * @package  mod_glossary
+ * @category comment
+ *
  * @param stdClass $comment_param {
  *              context  => context the context object
  *              courseid => int course id
index 72a266b..4f573ce 100644 (file)
@@ -583,6 +583,9 @@ function wiki_get_extra_capabilities() {
  * Capability check has been done in comment->check_permissions(), we
  * don't need to do it again here.
  *
+ * @package  mod_wiki
+ * @category comment
+ *
  * @param stdClass $comment_param {
  *              context  => context the context object
  *              courseid => int course id
@@ -606,6 +609,10 @@ function wiki_comment_permissions($comment_param) {
  *              commentarea => string comment area
  *              itemid      => int itemid
  * }
+ *
+ * @package  mod_wiki
+ * @category comment
+ *
  * @return boolean
  */
 function wiki_comment_validate($comment_param) {