MDL-85530 course: Improve PHPDoc types for course format code

2025-12-30 19:40:00 +13:00
parent 8316779bd9
commit 45761788de
32 changed files with 49 additions and 45 deletions
@@ -38,7 +38,7 @@ use grade_grade;
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
 abstract class activityoverviewbase {
-    /** @var cm_info The course module. */
+    /** @var module_context The course module's context */
    protected module_context $context;

    /** @var \stdClass $course */
@@ -297,7 +297,7 @@ abstract class activityoverviewbase {
     * and provide names for each grade item that want to be displayed.
     *
     * @param grade_item[] $items
-     * @return array<integer, string> the grade item names indexed by item id.
+     * @return array<int, string> the grade item names indexed by item id.
     */
    protected function get_grade_item_names(array $items): array {
        if (count($items) == 1) {
@@ -213,7 +213,7 @@ abstract class base {
     *
     * @param int $courseid
     */
-    final public static function reset_course_cache($courseid = 0) {
+    final public static function reset_course_cache($courseid = 0): void {
        if ($courseid) {
            if (isset(self::$instances[$courseid])) {
                foreach (self::$instances[$courseid] as $format => $object) {
@@ -328,7 +328,7 @@ abstract class base {
     * Returns a record from course database table plus additional fields
     * that course format defines
     *
-     * @return ?stdClass
+     * @return stdClass|null
     */
    public function get_course() {
        global $DB;
@@ -479,7 +479,7 @@ abstract class base {
     * Initially this was created to know if forms should add a button to return to the course page.
     * So if 'Return to course' does not make sense in your format your should probably return false.
     *
-     * @return boolean
+     * @return bool
     * @since Moodle 2.6
     */
    public function has_view_page() {
@@ -557,7 +557,7 @@ abstract class base {
     *
     * @param int|stdClass $section either section number (field course_section.section) or row from course_section table
     * @param int $strictness
-     * @return ?section_info
+     * @return section_info|null
     */
    final public function get_section($section, $strictness = IGNORE_MISSING) {
        if (is_object($section)) {
@@ -906,7 +906,7 @@ abstract class base {
     *
     * Used in course/rest.php
     *
-     * @return ?array This will be passed in ajax respose
+     * @return array|null This will be passed in ajax respose
     */
    public function ajax_section_move() {
        return null;
@@ -1884,7 +1884,7 @@ abstract class base {
     *
     * @param section_info $section the section to move
     * @param section_info $destination the section that should be below the moved section
-     * @return boolean if the section can be moved or not
+     * @return bool if the section can be moved or not
     */
    public function move_section_after(section_info $section, section_info $destination): bool {
        if ($section->section == $destination->section || $section->section == $destination->section + 1) {
@@ -1958,7 +1958,7 @@ abstract class base {
     * @param stdClass $section
     * @param string $itemtype
     * @param mixed $newvalue
-     * @return ?\core\output\inplace_editable
+     * @return \core\output\inplace_editable|null
     */
    public function inplace_editable_update_section_name($section, $itemtype, $newvalue) {
        if ($itemtype === 'sectionname' || $itemtype === 'sectionnamenl') {
@@ -64,7 +64,7 @@ use stdClass;
 */
 final class formatactions {
    /**
-     * @var courseactions|null courseactions instance.
+     * @var courseactions courseactions instance.
     */
    public courseactions $course;

@@ -96,7 +96,7 @@ abstract class basecontrolmenu implements named_templatable, renderable {
     * Export this data so it can be used as the context for a mustache template.
     *
     * @param renderer_base $output typically, the renderer that's calling this function
-     * @return null|array data context for a mustache template
+     * @return stdClass|null data context for a mustache template
     */
    public function export_for_template(renderer_base $output): ?stdClass {
        $menu = $this->get_action_menu($output);
@@ -144,7 +144,7 @@ abstract class basecontrolmenu implements named_templatable, renderable {
    /**
     * Format control array into an action_menu.
     *
-     * @param \renderer_base $output typically, the renderer that's calling this function
+     * @param array $controls array of edit control items
     * @return action_menu|null the action menu
     */
    protected function format_controls(array $controls): ?action_menu {
@@ -182,7 +182,7 @@ abstract class basecontrolmenu implements named_templatable, renderable {
     *
     * @todo Remove this method in Moodle 6.0 (MDL-83530).
     * @param array|null $itemdata the item data
-     * @return void
+     * @return link_secondary|null
     */
    private function normalize_action_menu_link(
        array|null $itemdata
@@ -46,7 +46,7 @@ class bulkedittoggler implements named_templatable, renderable {
    /**
     * Export this data so it can be used as the context for a mustache template (core/inplace_editable).
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
+     * @param \renderer_base $output typically, the renderer that's calling this function
     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output) {
@@ -48,7 +48,7 @@ class bulkedittools implements named_templatable, renderable {
    /**
     * Export this data so it can be used as the context for a mustache template (core/inplace_editable).
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
+     * @param \renderer_base $output typically, the renderer that's calling this function
     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): stdClass {
@@ -66,7 +66,7 @@ class cmicon implements named_templatable, renderable {
     * Export this data so it can be used as the context for a mustache template.
     *
     * @param \renderer_base $output typically, the renderer that's calling this function
-     * @return stdClass data context for a mustache template
+     * @return array data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): array {
        $mod = $this->mod;
@@ -95,7 +95,7 @@ class cmname implements named_templatable, renderable {
     * Export this data so it can be used as the context for a mustache template.
     *
     * @param \renderer_base $output typically, the renderer that's calling this function
-     * @return stdClass data context for a mustache template
+     * @return array data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): array {
        $mod = $this->mod;
@@ -299,7 +299,7 @@ class controlmenu extends basecontrolmenu {
    /**
     * Generates the visibility item for a course module.
     *
-     * @return link|null The menu item if applicable, otherwise null.
+     * @return link_secondary|subpanel|null The menu item if applicable, otherwise null.
     */
    protected function get_cm_visibility_item(): link_secondary|subpanel|null {
        if (!has_capability('moodle/course:activityvisibility', $this->modcontext)) {
@@ -121,7 +121,7 @@ class title extends inplace_editable implements named_templatable, renderable {
     * Export this data so it can be used as the context for a mustache template.
     *
     * @param \renderer_base $output typically, the renderer that's calling this function
-     * @return stdClass data context for a mustache template
+     * @return array data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): array {

@@ -72,7 +72,7 @@ class frontpagesection implements named_templatable, renderable {
    /**
     * Export this data so it can be used as the context for a mustache template.
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
+     * @param \renderer_base $output typically, the renderer that's calling this function
     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): stdClass {
@@ -127,7 +127,7 @@ class availability implements named_templatable, renderable {
     * activities.
     *
     * @param \renderer_base $output typically, the renderer that's calling this function
-     * @return stdclass data context for a mustache template
+     * @return array data context for a mustache template
     */
    protected function get_info(\renderer_base $output): array {
        global $CFG, $USER;
@@ -78,8 +78,8 @@ class cmlist implements named_templatable, renderable {
    /**
     * Export this data so it can be used as the context for a mustache template.
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
-     * @return array data context for a mustache template
+     * @param \renderer_base $output typically, the renderer that's calling this function
+     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): stdClass {
        global $USER;
@@ -63,8 +63,8 @@ class cmsummary implements named_templatable, renderable {
    /**
     * Export this data so it can be used as the context for a mustache template.
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
-     * @return array data context for a mustache template
+     * @param \renderer_base $output typically, the renderer that's calling this function
+     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): stdClass {

@@ -62,8 +62,8 @@ class header implements named_templatable, renderable {
    /**
     * Export this data so it can be used as the context for a mustache template.
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
-     * @return array data context for a mustache template
+     * @param \renderer_base $output typically, the renderer that's calling this function
+     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): stdClass {

@@ -63,8 +63,8 @@ class summary implements named_templatable, renderable {
    /**
     * Export this data so it can be used as the context for a mustache template.
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
-     * @return array data context for a mustache template
+     * @param \renderer_base $output typically, the renderer that's calling this function
+     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): stdClass {

@@ -65,7 +65,7 @@ class sectionnavigation implements named_templatable, renderable {
    /**
     * Export this data so it can be used as the context for a mustache template.
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
+     * @param \renderer_base $output typically, the renderer that's calling this function
     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): stdClass {
@@ -50,7 +50,7 @@ class cm implements renderable {
        protected cm_info $cm,
        /** @var bool $exportcontent False if pre-rendered cmitem HTML content must be exported. */
        protected bool $exportcontent = false,
-        /** @var ?bool $istrackeduser If is_tracked_user is pre-computed for this CM's course, it can be provided here. */
+        /** @var bool|null $istrackeduser If is_tracked_user is pre-computed for this CM's course, it can be provided here. */
        protected ?bool $istrackeduser = null,
    ) {
    }
@@ -46,7 +46,7 @@ class course implements renderable {
    /**
     * Export this data so it can be used as state object in the course editor.
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
+     * @param \renderer_base $output typically, the renderer that's calling this function
     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): stdClass {
@@ -53,7 +53,7 @@ class section implements renderable {
     * Export this data so it can be used as state object in the course editor.
     *
     * @param \renderer_base $output typically, the renderer that's calling this function
-     * @return array data context for a mustache template
+     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): stdClass {
        $format = $this->format;
@@ -176,9 +176,9 @@ abstract class section_renderer extends core_course_renderer {
     * If the format is not compatible with the course index, this method will return an empty string.
     *
     * @param course_format $format the course format
-     * @return String the course index HTML.
+     * @return string the course index HTML.
     */
-    public function course_index_drawer(course_format $format): ?String {
+    public function course_index_drawer(course_format $format): ?string {
        if ($format->uses_course_index()) {
            include_course_editor($format);
            return $this->render_from_template('core_courseformat/local/courseindex/drawer', []);
@@ -31,7 +31,7 @@ class provider implements
    // This system has some sitewide user preferences to export.
    \core_privacy\local\request\user_preference_provider {

-    /** The user preference for the navigation drawer. */
+    /** @var string The user preference for the navigation drawer. */
    public const SECTION_PREFERENCES_PREFIX = 'coursesectionspreferences';

    /**
@@ -49,7 +49,7 @@ abstract class sectiondelegate {
     * Get the section info instance if available.
     *
     * @param section_info $sectioninfo
-     * @return section_info|null
+     * @return sectiondelegate|null
     */
    public static function instance(section_info $sectioninfo): ?self {
        if (empty($sectioninfo->component)) {
@@ -64,7 +64,7 @@ class stateupdates implements JsonSerializable {
    /**
     * Return the data to serialize the current track in JSON.
     *
-     * @return stdClass the statement data structure
+     * @return array the statement data structure
     */
    public function jsonSerialize(): array {
        return $this->updates;
@@ -34,6 +34,7 @@ class renderer extends section_renderer {
     * @param \stdClass $course record from table course
     * @param bool $orphaned if false displays the main activity (if present)
     *     if true displays all other activities
+     * @return string
     */
    public function display($course, $orphaned) {

@@ -782,7 +782,7 @@ final class base_test extends advanced_testcase {
     *
     * @param string $action the ajax action name
     * @param string $expectedparam the expected param to check
-     * @param string $exception if an exception is expected
+     * @param bool $exception if an exception is expected
     */
    #[\PHPUnit\Framework\Attributes\DataProvider('get_non_ajax_cm_action_url_provider')]
    public function test_get_non_ajax_cm_action_url(string $action, string $expectedparam, bool $exception): void {
@@ -85,6 +85,8 @@ class format_theunittest extends core_courseformat\base {

    /**
     * Returns true if this course format uses sections
+     *
+     * @return bool
     */
    public function uses_sections() {
        return true;
@@ -32,7 +32,7 @@ class invalidoutput implements renderable, templatable {
    /**
     * Export some data.
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
+     * @param \renderer_base $output typically, the renderer that's calling this function
     * @return stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): stdClass {
@@ -30,8 +30,8 @@ class course extends course_state {
    /**
     * Export this data so it can be used as state object in the course editor.
     *
-     * @param renderer_base $output typically, the renderer that's calling this function
-     * @return stdClass data context for a mustache template
+     * @param \renderer_base $output typically, the renderer that's calling this function
+     * @return \stdClass data context for a mustache template
     */
    public function export_for_template(\renderer_base $output): \stdClass {
        $data = parent::export_for_template($output);
@@ -37,6 +37,7 @@ final class overviewfactory_test extends \advanced_testcase {
     * Test create method on resource activities.
     *
     * @param string $resourcetype
+     * @param string|null $expected
     */
    #[\PHPUnit\Framework\Attributes\DataProvider('create_resource_provider')]
    public function test_create_resource(
@@ -175,7 +175,7 @@ final class stateactions_test extends \advanced_testcase {
     * @param stdClass $course the course data
     * @param string $rolename the testing role name
     */
-    private function set_test_user_by_role(stdClass $course, string $rolename) {
+    private function set_test_user_by_role(stdClass $course, string $rolename): void {
        if ($rolename == 'admin') {
            $this->setAdminUser();
        } else {
@@ -655,7 +655,7 @@ final class stateactions_test extends \advanced_testcase {
     * @param string $role the user role
     * @param string[] $idrefs the sections or cms id references to be used as method params
     * @param bool $expectedexception whether the call should throw an exception
-     * @param int[] $expectedtotal the expected total number of state indexed by put, remove and create
+     * @param int[] $expectedtotals the expected total number of state indexed by put, remove and create
     * @param string|null $coursefield the course field to check
     * @param int|string|null $coursevalue the section field value
     * @param string|null $sectionfield the section field to check
@@ -96,7 +96,7 @@ class controlmenu extends controlmenu_base {
    /**
     * Retrieves the view item for the section control menu.
     *
-     * @return action_menu_link|null The menu item if applicable, otherwise null.
+     * @return action_menu_link_secondary The menu item if applicable, otherwise null.
     */
    protected function get_section_highlight_item(): action_menu_link_secondary {
        $format = $this->format;