From a343faaa7d2da5d740c1f7d3a7d2aca89d270a7b Mon Sep 17 00:00:00 2001 From: Jun Pataleta Date: Thu, 3 Nov 2022 11:55:42 +0800 Subject: [PATCH] MDL-75759 courseformat: Link classes in PHPDocs with @see tags - Linking classes/methods mentioned in PHPDoc with @see tags help devs checking the PHPDoc to quickly navigate to the class/method mentioned and also helps us ensure that it points to the correct class/method. - Some typo/grammar fixes as well in existing PHPDoc descriptions. - Fixed parameter type in execute()'s PHPDoc block. --- course/format/classes/external/update_course.php | 14 +++++++------- course/format/classes/stateupdates.php | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/course/format/classes/external/update_course.php b/course/format/classes/external/update_course.php index 2fad991a264..870ea6985ad 100644 --- a/course/format/classes/external/update_course.php +++ b/course/format/classes/external/update_course.php @@ -72,22 +72,22 @@ class update_course extends external_api { /** * This webservice will execute any action from the course editor. The default actions - * are located in core_courseformat\stateactions but the format plugin can extend that class + * are located in {@see \core_courseformat\stateactions} but the format plugin can extend that class * in format_XXX\course. * - * The specific action methods will register in a core_courseformat\stateupdates all the affected - * sections, cms and course attribute. This object (in JSON) will be send back to the + * The specific action methods will register in a {@see \core_courseformat\stateupdates} all the affected + * sections, cms and course attribute. This object (in JSON) will be sent back to the * frontend editor to refresh the updated state elements. * - * By default, core_courseformat\stateupdates will register only create, delete and update events + * By default, {@see \core_courseformat\stateupdates} will register only create, delete and update events * on cms, sections and the general course data. However, if some plugin needs adhoc messages for - * its own mutation module, it extend this class in format_XXX\course. + * its own mutation module, extend this class in format_XXX\course. * * @param string $action the action name to execute * @param int $courseid the course id * @param int[] $ids the affected ids (section or cm depending on the action) - * @param int $targetsectionid optional target section id (for move action) - * @param int $targetcmid optional target cm id (for move action) + * @param int|null $targetsectionid optional target section id (for move action) + * @param int|null $targetcmid optional target cm id (for move action) * @return string Course state in JSON */ public static function execute(string $action, int $courseid, array $ids = [], diff --git a/course/format/classes/stateupdates.php b/course/format/classes/stateupdates.php index de4d79918ee..eb2bfe2acb9 100644 --- a/course/format/classes/stateupdates.php +++ b/course/format/classes/stateupdates.php @@ -30,8 +30,8 @@ use JsonSerializable; * * Each format plugin could extend this class to provide new updates to the frontend * mutation module. - * Extended classes should be locate in "format_XXX\course" namespace and - * extends core_courseformat\stateupdates. + * Extended classes should be located in "format_XXX\course" namespace and + * extends {@see \core_courseformat\stateupdates}. * * @package core_course * @copyright 2021 Ferran Recio