From 35453657a272fc474d7e876b6a62d9060959489f Mon Sep 17 00:00:00 2001 From: Dongsheng Cai Date: Wed, 15 Feb 2012 11:21:35 +0800 Subject: [PATCH] MDL-30984 comment API, check and update DocBlock --- blocks/comments/lib.php | 9 +++ blog/lib.php | 6 ++ comment/comment_ajax.php | 4 + comment/comment_post.php | 4 + comment/index.php | 4 + comment/lib.php | 153 ++++++++++++++------------------------- comment/locallib.php | 21 ++++-- mod/data/lib.php | 6 ++ mod/glossary/lib.php | 6 ++ mod/wiki/lib.php | 7 ++ 10 files changed, 112 insertions(+), 108 deletions(-) diff --git a/blocks/comments/lib.php b/blocks/comments/lib.php index 3f10939bb3d..30cca1ee24b 100644 --- a/blocks/comments/lib.php +++ b/blocks/comments/lib.php @@ -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 diff --git a/blog/lib.php b/blog/lib.php index 5a92fb5a426..080df708c88 100644 --- 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 index 828d5c8a2c3..91b99cafa8d 100644 --- 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 index 4e852b43900..b7a39a8448b 100644 --- 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 index b9a2abd63c1..ab5daa37833 100644 --- 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 index 99e92f990ed..171e619c782 100644 --- a/comment/lib.php +++ b/comment/lib.php @@ -15,134 +15,80 @@ // along with Moodle. If not, see . /** - * Comment is helper class to add/delete comments anywhere in moodle + * Functions and classes for commenting * - * @package comment - * @copyright 2010 Dongsheng Cai + * @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 { } diff --git a/comment/locallib.php b/comment/locallib.php index fd62b619347..5a8b0d7bf99 100644 --- 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 . +/** + * 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 + * @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; diff --git a/mod/data/lib.php b/mod/data/lib.php index 2bee85bf059..5cbd1ef2877 100644 --- 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 diff --git a/mod/glossary/lib.php b/mod/glossary/lib.php index 5f1417d118a..2a83818c9ed 100644 --- a/mod/glossary/lib.php +++ b/mod/glossary/lib.php @@ -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 diff --git a/mod/wiki/lib.php b/mod/wiki/lib.php index 72a266b8fbc..4f573ce2f1d 100644 --- a/mod/wiki/lib.php +++ b/mod/wiki/lib.php @@ -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) {