MDL-28980 improve expiry notification inline docs

enrol/manual/lib.php

@@ -456,7 +456,12 @@ public function send_notifications($verbose = false) {
     }
 
     /**
-     * Returns the user who is resposible for manual enrolments in given course
+     * Returns the user who is responsible for manual enrolments in given course.
+     *
+     * Usually it is the first editing teacher - the person with "highest authority"
+     * as defined by sort_by_roleassignment_authority() having 'enrol/manual:manage'
+     * capability.
+     *
      * @param int $courseid
      * @return stdClass user record
      */
@@ -480,7 +485,12 @@ protected function get_enroller($courseid) {
     }
 
     /**
-     * Notify user about incoming expiration of their enrolment.
+     * Notify user about incoming expiration of their enrolment,
+     * it is called only if notification of enrolled users (aka students) is enabled in course.
+     *
+     * This is executed only once for each expiring enrolment right
+     * at the start of the expiration threshold.
+     *
      * @param stdClass $user
      * @param stdClass $ue
      * @param bool $verbose
@@ -537,7 +547,12 @@ protected function notify_expiry_enrolled($user, $ue, $verbose) {
     }
 
     /**
-     * Notify person responsible for enrolments that some user enrolments will be expired soon.
+     * Notify person responsible for enrolments that some user enrolments will be expired soon,
+     * it is called only if notification of enrollers (aka teachers) is enabled in course.
+     *
+     * This is called repeatedly every day for each course if there are any pending expiration
+     * in the expiration threshold.
+     *
      * @param int $eid
      * @param array $users
      * @param bool $verbose