Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

MDL-30984 comment API, check and update DocBlock

  • Loading branch information...
commit 35453657a272fc474d7e876b6a62d9060959489f 1 parent 5fc420e
@dcai dcai authored
View
9 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
View
6 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
View
4 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);
View
4 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');
View
4 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');
View
153 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 <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 @@ 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 {
}
View
21 comment/locallib.php
@@ -16,18 +16,24 @@
// 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 @@ 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;
View
6 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
View
6 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
View
7 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) {
Please sign in to comment.
Something went wrong with that request. Please try again.