MDL-30984 comment API, check and update DocBlock

abgreeve · Feb 15, 2012 · 3545365 · 3545365
1 parent 5fc420e
commit 3545365
Show file tree

Hide file tree

Showing 10 changed files with 112 additions and 108 deletions.
diff --git a/blocks/comments/lib.php b/blocks/comments/lib.php
@@ -28,6 +28,9 @@
 /**
  * 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

diff --git a/blog/lib.php b/blog/lib.php
@@ -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

diff --git a/comment/comment_ajax.php b/comment/comment_ajax.php
@@ -16,6 +16,10 @@
 
 /*
  * 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);
 

diff --git a/comment/comment_post.php b/comment/comment_post.php
@@ -16,6 +16,10 @@
 
 /*
  * 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');

diff --git a/comment/index.php b/comment/index.php
@@ -17,6 +17,10 @@
 
 /*
  * 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');

diff --git a/comment/lib.php b/comment/lib.php
@@ -15,134 +15,80 @@
 // 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 <[email protected]>
+ * @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 @@ public static function init(moodle_page $page = null) {
      * 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 @@ public function initialise_javascript(moodle_page $page) {
     /**
      * 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 @@ public function output($return = true) {
      * Return matched comments
      *
      * @param  int $page
-     * @return mixed
+     * @return array
      */
     public function get_comments($page = '') {
         global $DB, $CFG, $USER, $OUTPUT;
@@ -646,7 +591,8 @@ public function get_pagination($page = 0) {
      *
      * @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 @@ public function reset_course_page_comments($context) {
      * Delete a comment
      *
      * @param  int $commentid
-     * @return mixed
+     * @return bool
      */
     public function delete($commentid) {
         global $DB, $USER;
@@ -740,9 +686,9 @@ public function delete($commentid) {
      * 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 @@ public function get_commentarea() {
     }
 }
 
+/**
+ * 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 {
 }
diff --git a/comment/locallib.php b/comment/locallib.php
@@ -15,19 +15,25 @@
 // 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 <[email protected]>
+ * @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 @@ function get_comments($page) {
      * @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 @@ private function setup_plugin($comment) {
     /**
      * 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;

diff --git a/mod/data/lib.php b/mod/data/lib.php
@@ -3242,6 +3242,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
@@ -3269,6 +3272,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