Some docs are added

openmeetings · Dec 20, 2023 · 4223977 · 4223977
1 parent 951ee9a
commit 4223977
Show file tree

Hide file tree

Showing 2 changed files with 71 additions and 9 deletions.
diff --git a/api/OmGateway.php b/api/OmGateway.php
@@ -44,24 +44,52 @@
 
 require_once('OmRestService.php');
 
+/**
+ * Class responsible for communications with OM
+ * Prepares data for OM REST call, and processes the results
+ */
 class OmGateway {
+    /** @var string $sessionid - OM sessionID */
     private $sessionid = "";
+    /** @var array $config - Gateway config */
     private $config = array();
+    /** @var bool $debug - debug flag */
     private $debug = false;
 
+    /**
+     * Constructor
+     *
+     * @param array $cfg - Gateway config
+     */
     public function __construct($cfg) {
         $this->config = $cfg;
         $this->debug = true === $cfg["debug"];
     }
 
+    /**
+     * Method to get URL for specific REST endpoint
+     *
+     * @param string $name - the name of the endpoint
+     * @return string - URL
+     */
     private function get_rest_url($name) {
         return $this->get_url() . "/services/" . $name . "/";
     }
 
+    /**
+     * Method to get OM URL
+     *
+     * @return string - OM URL
+     */
     public function get_url() {
         return $this->config["url"];
     }
 
+    /**
+     * Method to get response from OM version endpoint
+     *
+     * @return array - response from OM version endpoint
+     */
     public function version() {
         $rest = new OmRestService($this->config);
         $response = $rest->call(
@@ -75,6 +103,11 @@ public function version() {
         return $response;
     }
 
+    /**
+     * Displays an error
+     *
+     * @param array $rest - REST error
+     */
     private function show_error($rest) {
         echo '<h2>Fault (Service error)</h2><pre>';
         if ($this->debug) {
@@ -83,11 +116,22 @@ private function show_error($rest) {
         echo '</pre>';
     }
 
+    /**
+     * Displays service error
+     *
+     * @param string $msg - message
+     * @param array $response - REST response
+     */
     private function show_service_error($msg, $response) {
         echo '<h2>REST call failed</h2>';
         echo '<div>' . $msg . '; message: ' . $response['message'] . '</div>';
     }
 
+    /**
+     * Method to perform login to OM server
+     *
+     * @return bool - if login was successful or not
+     */
     public function login() {
         $rest = new OmRestService($this->config);
         $response = $rest->call(
@@ -112,6 +156,17 @@ public function login() {
         return false;
     }
 
+    /**
+     * Constructs OM user based on passed params
+     *
+     * @param string $login - user's login
+     * @param string $firstname - user's first name
+     * @param string $lastname - user's last name
+     * @param string $pictureurl - URL of user's avatar
+     * @param string $email - user's email
+     * @param string $userid - The ID of user in Moodle
+     * @return array - user array
+     */
     public function get_user($login, $firstname, $lastname, $pictureurl, $email, $userid) {
         return array(
             "login" => $login
@@ -124,6 +179,13 @@ public function get_user($login, $firstname, $lastname, $pictureurl, $email, $us
         );
     }
 
+    /**
+     * Retrieves secure hash for OM room
+     *
+     * @param array $user - Moodle user
+     * @param array $options - external options
+     * @return string - secure hash of the room or -1 in case of error
+     */
     public function get_secure_hash($user, $options) {
         $rest = new OmRestService($this->config);
         $options['externalType'] = $this->config["module"];

diff --git a/db/upgrade.php b/db/upgrade.php
@@ -43,7 +43,7 @@
  * Upgrade to version '20111001'
  *
  * @param int $oldversion - previous version
- * @param $dbman - DB structure to be patched
+ * @param database_manager $dbman - DB structure to be patched
  */
 function upgrade20111001($oldversion, $dbman) {
     $ver = 20111001;
@@ -67,7 +67,7 @@ function upgrade20111001($oldversion, $dbman) {
  * Upgrade to version '20111002'
  *
  * @param int $oldversion - previous version
- * @param $dbman - DB structure to be patched
+ * @param database_manager $dbman - DB structure to be patched
  */
 function upgrade20111002($oldversion, $dbman) {
     $ver = 20111002;
@@ -90,7 +90,7 @@ function upgrade20111002($oldversion, $dbman) {
  * Upgrade to version '2014031603'
  *
  * @param int $oldversion - previous version
- * @param $dbman - DB structure to be patched
+ * @param database_manager $dbman - DB structure to be patched
  */
 function upgrade2014031603($oldversion, $dbman) {
     $ver = 2014031603;
@@ -113,7 +113,7 @@ function upgrade2014031603($oldversion, $dbman) {
  * Upgrade to version '2016042002'
  *
  * @param int $oldversion - previous version
- * @param $dbman - DB structure to be patched
+ * @param database_manager $dbman - DB structure to be patched
  */
 function upgrade2016042002($oldversion, $dbman) {
     global $CFG;
@@ -159,7 +159,7 @@ function upgrade2016042002($oldversion, $dbman) {
  * Upgrade to version '2017101000'
  *
  * @param int $oldversion - previous version
- * @param $dbman - DB structure to be patched
+ * @param database_manager $dbman - DB structure to be patched
  */
 function upgrade2017101000($oldversion, $dbman) {
     global $CFG, $DB;
@@ -180,7 +180,7 @@ function upgrade2017101000($oldversion, $dbman) {
  * Upgrade to version '2018072401'
  *
  * @param int $oldversion - previous version
- * @param $dbman - DB structure to be patched
+ * @param database_manager $dbman - DB structure to be patched
  */
 function upgrade2018072401($oldversion) {
     $ver = 2018072401;
@@ -194,7 +194,7 @@ function upgrade2018072401($oldversion) {
  * Upgrade to version '2018101600'
  *
  * @param int $oldversion - previous version
- * @param $dbman - DB structure to be patched
+ * @param database_manager $dbman - DB structure to be patched
  */
 function upgrade2018101600($oldversion, $dbman) {
     $ver = 2018101600;
@@ -221,7 +221,7 @@ function upgrade2018101600($oldversion, $dbman) {
  * Upgrade to version '20200404'
  *
  * @param int $oldversion - previous version
- * @param $dbman - DB structure to be patched
+ * @param database_manager $dbman - DB structure to be patched
  */
 function upgrade20200404($oldversion, $dbman) {
     global $CFG, $DB;
@@ -244,7 +244,7 @@ function upgrade20200404($oldversion, $dbman) {
  * Upgrade to version '2021020900'
  *
  * @param int $oldversion - previous version
- * @param $dbman - DB structure to be patched
+ * @param database_manager $dbman - DB structure to be patched
  */
 function upgrade2021020900($oldversion) {
     global $CFG;