PHPDoc documentation

This commit is contained in:
PMKuipers 2023-08-28 09:21:00 +02:00
parent 701f4d7363
commit 7de179e6e6
2 changed files with 123 additions and 25 deletions

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Scan course completion criteria for pending grading actions
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -26,24 +26,56 @@ defined('MOODLE_INTERNAL') || die();
require_once($CFG->libdir.'/externallib.php');
use \grade_item;
use \completion_criteria;
/**
* Scan course completion criteria for pending grading actions
*/
class completionscanner {
/**
* Cache of supported mods
* @var array
*/
private static $modsupported = [];
/**
* Cache of enrolled students in a particular course
* @var array
*/
private static $coursestudents = [];
/** The internally used grading scanner
* @var local\ungradedscanners\scanner_base
*/
private $scanner = null;
private $course = null;
/**
* Course module
* @var \cm_info
*/
private $cm = null;
/** @var grade_item */
private $gi = null;
/**
* Cache of pending ungraded results per user
* @var array
*/
private $pendingcache = [];
public static function supported($mod) {
/**
* Check if a certain activity type is supported for scanning pending results
* @param string $mod name of activity module
*/
public static function supported($mod) : bool {
if (!array_key_exists($mod, self::$modsupported)) {
self::$modsupported[$mod] = class_exists("\local_treestudyplan\\local\\ungradedscanners\\{$mod}_scanner");
}
return self::$modsupported[$mod];
}
public static function get_course_students($courseid) {
/**
* List all users enrolled in a course as student by userid
* @param int $courseid Course id of the course to check
* @return int[] Array if user ids
*/
public static function get_course_students($courseid) : array {
global $CFG;
if (!array_key_exists($courseid, self::$coursestudents)) {
$students = [];
@ -57,7 +89,12 @@ class completionscanner {
return self::$coursestudents[$courseid];
}
public function __construct(\completion_criteria $crit, $course) {
/**
* Construct new scanner based on completion criteria and course
* @param completion_criteria $crit Criteria to check for
* @param stdClass $course Course DB record
*/
public function __construct(completion_criteria $crit, $course) {
$this->courseid = $course->id;
$this->course = $course;
$this->modinfo = get_fast_modinfo($course);
@ -91,18 +128,26 @@ class completionscanner {
}
public function pending($userid) {
if (!array_key_exists($userid, $this->pending_cache)) {
/**
* Check if the criteria this scanner scans has pending submissions for a specific user
* @param int $userid ID of the user to check for
*/
public function pending($userid) : bool {
if (!array_key_exists($userid, $this->pendingcache)) {
if ($this->scanner === null) {
$this->pending_cache[$userid] = false;
$this->pendingcache[$userid] = false;
} else {
$this->pending_cache[$userid] = $this->scanner->has_ungraded_submission($userid);;
$this->pendingcache[$userid] = $this->scanner->has_ungraded_submission($userid);;
}
}
return $this->pending_cache[$userid];
return $this->pendingcache[$userid];
}
public static function structure($value = VALUE_OPTIONAL) {
/**
* Webservice structure for basic info
* @param int $value Webservice requirement constant
*/
public static function structure($value = VALUE_OPTIONAL) : \external_description {
return new \external_single_structure([
"ungraded" => new \external_value(PARAM_INT, 'number of ungraded submissions'),
"completed" => new \external_value(PARAM_INT, 'number of completed students'),
@ -112,7 +157,10 @@ class completionscanner {
], "details about gradable submissions", $value);
}
public function model() {
/**
* Webservice model for basic info
*/
public function model() : array {
// Get completion info.
$students = self::get_course_students($this->courseid);

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Scan gradables for a pending grading action
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -27,21 +27,49 @@ require_once($CFG->libdir.'/externallib.php');
use \grade_item;
/**
* Scan gradables for a pending grading action
*/
class gradingscanner {
/**
* Cache of supported mods
* @var array
*/
private static $modsupported = [];
/**
* Cache of enrolled students in a particular course
* @var array
*/
private static $coursestudents = [];
/** The internally used grading scanner
* @var local\ungradedscanners\scanner_base
*/
private $scanner = null;
/** @var grade_item */
private $gi = null;
/**
* Cache of pending ungraded results per user
* @var array
*/
private $pendingcache = [];
public static function supported($mod) {
/**
* Check if a certain activity type is supported for scanning pending results
* @param string $mod name of activity module
*/
public static function supported($mod) : bool {
if (!array_key_exists($mod, self::$modsupported)) {
self::$modsupported[$mod] = class_exists("\local_treestudyplan\\local\\ungradedscanners\\{$mod}_scanner");
}
return self::$modsupported[$mod];
}
public static function get_course_students($courseid) {
/**
* List all users enrolled in a course as student by userid
* @param int $courseid Course id of the course to check
* @return int[] Array if user ids
*/
public static function get_course_students($courseid) : array {
global $CFG;
if (!array_key_exists($courseid, self::$coursestudents)) {
$students = [];
@ -55,6 +83,10 @@ class gradingscanner {
return self::$coursestudents[$courseid];
}
/**
* Construct new scanner based on grade item
* @param grade_item $gi Grade item
*/
public function __construct(grade_item $gi) {
$this->courseid = $gi->courseid;
$this->gi = $gi;
@ -64,22 +96,33 @@ class gradingscanner {
}
}
public function is_available() {
/**
* Check if this scanner is usable (has an internal activity specific scanner)
*/
public function is_available() : bool {
return $this->scanner !== null;
}
public function pending($userid) {
if (!array_key_exists($userid, $this->pending_cache)) {
/**
* Check if the gradable item this scanner scans has pending submissions for a specific user
* @param int $userid ID of the user to check for
*/
public function pending($userid) : bool {
if (!array_key_exists($userid, $this->pendingcache)) {
if ($this->scanner === null) {
$this->pending_cache[$userid] = false;
$this->pendingcache[$userid] = false;
} else {
$this->pending_cache[$userid] = $this->scanner->has_ungraded_submission($userid);;
$this->pendingcache[$userid] = $this->scanner->has_ungraded_submission($userid);;
}
}
return $this->pending_cache[$userid];
return $this->pendingcache[$userid];
}
public static function structure($value =VALUE_OPTIONAL) {
/**
* Webservice structure for basic info
* @param int $value Webservice requirement constant
*/
public static function structure($value = VALUE_OPTIONAL) : \external_description {
return new \external_single_structure([
"ungraded" => new \external_value(PARAM_INT, 'number of ungraded submissions'),
"completed" => new \external_value(PARAM_INT, 'number of completed students'),
@ -89,7 +132,10 @@ class gradingscanner {
], "details about gradable submissions", $value);
}
public function model() {
/**
* Webservice model for basic info
*/
public function model() : array {
// Upda.
$students = self::get_course_students($this->courseid);
$completed = 0;
@ -123,8 +169,12 @@ class gradingscanner {
}
/**
* Check if a grade is considered passed according to the rules
* @param grade_grade $grade
*/
private function grade_passed($grade) : bool {
// Function copied from bistate aggregator to avoid reference mazes.
private function grade_passed($grade) {
global $DB;
$table = "local_treestudyplan_gradecfg";
// First determine if we have a grade_config for this scale or this maximum grade.