diff --git a/lib/classes/oauth2/api.php b/lib/classes/oauth2/api.php
index a27e60525fe..48745527a19 100644
--- a/lib/classes/oauth2/api.php
+++ b/lib/classes/oauth2/api.php
@@ -44,7 +44,7 @@ class api {
 
     /**
      * Create a google ready OAuth 2 service.
-     * @return core\oauth2\issuer
+     * @return \core\oauth2\issuer
      */
     private static function create_google() {
         $record = (object) [
@@ -70,7 +70,7 @@ class api {
 
     /**
      * Create a facebook ready OAuth 2 service.
-     * @return core\oauth2\issuer
+     * @return \core\oauth2\issuer
      */
     private static function create_facebook() {
         // Facebook is a custom setup.
@@ -125,7 +125,7 @@ class api {
 
     /**
      * Create a microsoft ready OAuth 2 service.
-     * @return core\oauth2\issuer
+     * @return \core\oauth2\issuer
      */
     private static function create_microsoft() {
         // Microsoft is a custom setup.
@@ -200,7 +200,7 @@ class api {
 
     /**
      * List all the issuers, ordered by the sortorder field
-     * @return core\oauth2\issuer[]
+     * @return \core\oauth2\issuer[]
      */
     public static function get_all_issuers() {
         return issuer::get_records([], 'sortorder');
@@ -210,7 +210,7 @@ class api {
      * Get a single issuer by id.
      *
      * @param int $id
-     * @return core\oauth2\issuer
+     * @return \core\oauth2\issuer
      */
     public static function get_issuer($id) {
         return new issuer($id);
@@ -220,7 +220,7 @@ class api {
      * Get a single endpoint by id.
      *
      * @param int $id
-     * @return core\oauth2\endpoint
+     * @return \core\oauth2\endpoint
      */
     public static function get_endpoint($id) {
         return new endpoint($id);
@@ -230,7 +230,7 @@ class api {
      * Get a single user field mapping by id.
      *
      * @param int $id
-     * @return core\oauth2\user_field_mapping
+     * @return \core\oauth2\user_field_mapping
      */
     public static function get_user_field_mapping($id) {
         return new user_field_mapping($id);
@@ -286,8 +286,9 @@ class api {
      * Get an authenticated oauth2 client using the system account.
      * This call uses the refresh token to get an access token.
      *
-     * @param core\oauth2\issuer $issuer
-     * @return core\oauth2\client
+     * @param \core\oauth2\issuer $issuer
+     * @return \core\oauth2\client|false An authenticated client (or false if the token could not be upgraded)
+     * @throws moodle_exception Request for token upgrade failed for technical reasons
      */
     public static function get_system_oauth_client(issuer $issuer) {
         $systemaccount = self::get_system_account($issuer);
@@ -311,10 +312,10 @@ class api {
      * Get an authenticated oauth2 client using the current user account.
      * This call does the redirect dance back to the current page after authentication.
      *
-     * @param core\oauth2\issuer $issuer The desired OAuth issuer
+     * @param \core\oauth2\issuer $issuer The desired OAuth issuer
      * @param moodle_url $currenturl The url to the current page.
      * @param string $additionalscopes The additional scopes required for authorization.
-     * @return core\oauth2\client
+     * @return \core\oauth2\client
      */
     public static function get_user_oauth_client(issuer $issuer, moodle_url $currenturl, $additionalscopes = '') {
         $client = new \core\oauth2\client($issuer, $currenturl, $additionalscopes);
@@ -325,8 +326,8 @@ class api {
     /**
      * Get the list of defined endpoints for this OAuth issuer
      *
-     * @param core\oauth2\issuer $issuer The desired OAuth issuer
-     * @return core\oauth2\endpoint[]
+     * @param \core\oauth2\issuer $issuer The desired OAuth issuer
+     * @return \core\oauth2\endpoint[]
      */
     public static function get_endpoints(issuer $issuer) {
         return endpoint::get_records(['issuerid' => $issuer->get('id')]);
@@ -335,8 +336,8 @@ class api {
     /**
      * Get the list of defined mapping from OAuth user fields to moodle user fields.
      *
-     * @param core\oauth2\issuer $issuer The desired OAuth issuer
-     * @return core\oauth2\user_field_mapping[]
+     * @param \core\oauth2\issuer $issuer The desired OAuth issuer
+     * @return \core\oauth2\user_field_mapping[]
      */
     public static function get_user_field_mappings(issuer $issuer) {
         return user_field_mapping::get_records(['issuerid' => $issuer->get('id')]);
@@ -345,7 +346,7 @@ class api {
     /**
      * Guess an image from the discovery URL.
      *
-     * @param core\oauth2\issuer $issuer The desired OAuth issuer
+     * @param \core\oauth2\issuer $issuer The desired OAuth issuer
      */
     protected static function guess_image($issuer) {
         if (empty($issuer->get('image'))) {
@@ -447,7 +448,7 @@ class api {
      * Take the data from the mform and update the issuer.
      *
      * @param stdClass $data
-     * @return core\oauth2\issuer
+     * @return \core\oauth2\issuer
      */
     public static function update_issuer($data) {
         require_capability('moodle/site:config', context_system::instance());
@@ -466,7 +467,7 @@ class api {
      * Take the data from the mform and create the issuer.
      *
      * @param stdClass $data
-     * @return core\oauth2\issuer
+     * @return \core\oauth2\issuer
      */
     public static function create_issuer($data) {
         require_capability('moodle/site:config', context_system::instance());
@@ -485,7 +486,7 @@ class api {
      * Take the data from the mform and update the endpoint.
      *
      * @param stdClass $data
-     * @return core\oauth2\endpoint
+     * @return \core\oauth2\endpoint
      */
     public static function update_endpoint($data) {
         require_capability('moodle/site:config', context_system::instance());
@@ -501,7 +502,7 @@ class api {
      * Take the data from the mform and create the endpoint.
      *
      * @param stdClass $data
-     * @return core\oauth2\endpoint
+     * @return \core\oauth2\endpoint
      */
     public static function create_endpoint($data) {
         require_capability('moodle/site:config', context_system::instance());
@@ -516,7 +517,7 @@ class api {
      * Take the data from the mform and update the user field mapping.
      *
      * @param stdClass $data
-     * @return core\oauth2\user_field_mapping
+     * @return \core\oauth2\user_field_mapping
      */
     public static function update_user_field_mapping($data) {
         require_capability('moodle/site:config', context_system::instance());
@@ -532,7 +533,7 @@ class api {
      * Take the data from the mform and create the user field mapping.
      *
      * @param stdClass $data
-     * @return core\oauth2\user_field_mapping
+     * @return \core\oauth2\user_field_mapping
      */
     public static function create_user_field_mapping($data) {
         require_capability('moodle/site:config', context_system::instance());
@@ -710,7 +711,7 @@ class api {
      *
      * Requires moodle/site:config capability at the system context.
      *
-     * @param core\oauth2\issuer $issuer
+     * @param \core\oauth2\issuer $issuer
      * @param moodle_url $returnurl The url to the current page (we will be redirected back here after authentication).
      * @return boolean
      */
diff --git a/lib/classes/oauth2/client.php b/lib/classes/oauth2/client.php
index 528e511a0e7..07a775dbb0a 100644
--- a/lib/classes/oauth2/client.php
+++ b/lib/classes/oauth2/client.php
@@ -30,7 +30,6 @@ require_once($CFG->libdir . '/filelib.php');
 
 use moodle_url;
 use moodle_exception;
-use curl;
 use stdClass;
 
 /**
@@ -172,6 +171,7 @@ class client extends \oauth2_client {
      *
      * @param \core\oauth2\system_account $systemaccount
      * @return boolean true if token is upgraded succesfully
+     * @throws moodle_exception Request for token upgrade failed for technical reasons
      */
     public function upgrade_refresh_token(system_account $systemaccount) {
         $refreshtoken = $systemaccount->get('refreshtoken');
@@ -233,7 +233,7 @@ class client extends \oauth2_client {
      * Fetch the user info from the user info endpoint and map all
      * the fields back into moodle fields.
      *
-     * @return array (Moodle user fields for the logged in user).
+     * @return array|false Moodle user fields for the logged in user (or false if request failed)
      */
     public function get_userinfo() {
         $url = $this->get_issuer()->get_endpoint_url('userinfo');
@@ -244,7 +244,7 @@ class client extends \oauth2_client {
         $userinfo = new stdClass();
         try {
             $userinfo = json_decode($response);
-        } catch (Exception $e) {
+        } catch (\Exception $e) {
             return false;
         }
 
diff --git a/lib/classes/oauth2/rest.php b/lib/classes/oauth2/rest.php
index ca48a3590e1..bb1cd100d5d 100644
--- a/lib/classes/oauth2/rest.php
+++ b/lib/classes/oauth2/rest.php
@@ -25,6 +25,7 @@ namespace core\oauth2;
 
 use curl;
 use coding_exception;
+use stdClass;
 
 defined('MOODLE_INTERNAL') || die();
 
@@ -64,7 +65,7 @@ abstract class rest {
      * @param string $functionname
      * @param array $functionargs
      * @param string $rawpost Optional param to include in the body of a post.
-     * @return string|object
+     * @return string|stdClass
      */
     public function call($functionname, $functionargs, $rawpost = false, $contenttype = false) {
         $functions = $this->get_api_functions();