phpdoc compatibility

backup/moodle2/backup_game_stepslib.php

@@ -34,6 +34,9 @@ defined('MOODLE_INTERNAL') || die();
 
 /**
  * Define the complete game structure for backup, with file and id annotations
+ *
+ * @copyright 2007 Vasilis Daloukas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_game_activity_structure_step extends backup_activity_structure_step {
 

backup/moodle2/restore_game_activity_task.class.php

@@ -25,8 +25,10 @@ defined('MOODLE_INTERNAL') || die();
 require_once($CFG->dirroot . '/mod/game/backup/moodle2/restore_game_stepslib.php'); // Because it exists (must).
 
 /**
- * game restore task that provides all the settings and steps to perform one
+ * game restore task that provides all the settings and steps to perform one complete restore of the activity
- * complete restore of the activity
+ *
+ * @copyright 2007 Vasilis Daloukas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_game_activity_task extends restore_activity_task {
 

backup/moodle2/restore_game_stepslib.php

@@ -32,6 +32,9 @@ class restore_game_activity_structure_step extends restore_activity_structure_st
 
     /**
      * Defines the neeeded structures.
+     *
+     * @copyright 2007 Vasilis Daloukas
+     * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
      */
     protected function define_structure() {
 

classes/event/course_module_viewed.php

@@ -57,6 +57,10 @@ class course_module_viewed extends \core\event\course_module_viewed {
 
     /**
      * Create instance of event.
+     * @param stdClass $game
+     * @param stdClass $context
+     *
+     * @return event
      */
     public static function played(\stdClass $game, \context_module $context) {
         $data = array(

cross/cross_class.php

@@ -44,7 +44,7 @@ Author Àngel Fenoy from Arenys de Mar, Barcelona.
 class Cross
 {
     /** @var int Contains the words and the answers. */
-    public $minputanswers;   // 
+    public $minputanswers;
     /** @var The words that will be used. */
     public $mwords;
 
@@ -170,12 +170,12 @@ class Cross
     /**
      * Compute one crossword.
      *
-     * @param stdClass crossm
+     * @param stdClass $crossm
-     * @param stdClass crossd
+     * @param stdClass $crossd
      * @param string $letters
-     * @param int minwords
+     * @param int $minwords
-     * @param int maxwords
+     * @param int $maxwords
-     * @param int mtimelimit
+     * @param int $mtimelimit
      *
      * @return the crossword
      */
@@ -368,7 +368,7 @@ class Cross
      * @param int $crosspos
      * @param int $crossdir
      * @param stdClass $crossword
-     * @param boolean bprint
+     * @param boolean $bprint
      */
     public function computepuzzleinfo( $n20, $crosspos, $crossdir, $crossword, $bprint=false) {
         $bprint = false;
@@ -745,8 +745,8 @@ class Cross
      * Set a char to the specified position.
      *
      * @param $s
-     * @param int $pos
+     * @param $pos
-     * @param char $char
+     * @param $char
      */
     public function setchar( &$s, $pos, $char) {
         $ret = "";

db/importsnakes.php

@@ -68,6 +68,9 @@ function game_importsnakes() {
     game_importsnakes_do( $newrec);
 }
 
+/**
+  * Insert one board to database
+  */ 
 function game_importsnakes_do( $newrec) {
     global $DB;
 

export.php

@@ -316,7 +316,7 @@ echo $OUTPUT->footer();
 /**
  * Sends via html a file.
  *
- * @param string file
+ * @param string $file
  */
 function game_send_stored_file($file) {
     if (file_exists($file)) {

export/exportjavame.php

@@ -27,7 +27,7 @@ defined('MOODLE_INTERNAL') || die();
 /**
  * Exports to javame.
  *
- * @param stdClass $game
+ * @param object $game
  * @param $javame
  */
 function game_onexportjavame( $game, $javame) {
@@ -100,7 +100,7 @@ function game_onexportjavame( $game, $javame) {
  * @param $src
  * @param $destmobiledir
  * @param $destdir
- * @param stdClass $game
+ * @param $game
  * @param $maxwidth
  * @param $maxheight
  */
@@ -163,7 +163,7 @@ function game_exportjavame_exportdata( $src, $destmobiledir, $destdir, $game, $m
  * @param $game
  * @param $map
  * @param $maxwidth
- * @param @maxheight
+ * @param $maxheight
  */
 function game_exportjavame_exportdata_hangmanp( $src, $destmobiledir, $destdir, $game, $map, $maxwidth, $maxheight) {
     global $CFG;
@@ -194,9 +194,9 @@ function game_exportjavame_exportdata_hangmanp( $src, $destmobiledir, $destdir,
 /**
  * Exports to javame.
  *
- * @param stdClass $game
+ * @param $game
- * @param stdClass $context
+ * @param $context
- * @param string $exportattachments
+ * @param $exportattachments
  * @param $dest
  * @param $files
  */
@@ -219,9 +219,9 @@ function game_exmportjavame_getanswers( $game, $context, $exportattachment, $des
 /**
  * Exports to javame.
  *
- * @param stdClass $game
+ * @param $game
- * @param stdClass $context
+ * @param $context
- * @param string $destdir
+ * @param $destdir
  * @param $files
  */
 function game_exmportjavame_getanswers_question( $game, $context, $destdir, &$files) {
@@ -236,9 +236,9 @@ function game_exmportjavame_getanswers_question( $game, $context, $destdir, &$fi
 /**
  * Exports to javame.
  *
- * @param stdClass $game
+ * @param $game
- * @param stdClass $context
+ * @param $context
- * @param string $destdir
+ * @param $destdir
  * @param $files
  */
 function game_exmportjavame_getanswers_quiz( $game, $context, $destdir, $files) {
@@ -256,9 +256,9 @@ function game_exmportjavame_getanswers_quiz( $game, $context, $destdir, $files)
 /**
  * Exports to javame.
  *
- * @param stdClass $game
+ * @param $game
- * @param stdClass $context
+ * @param $context
- * @param string $table
+ * @param $table
  * @param $select
  * @param $fields
  * @param $courseid
@@ -302,8 +302,8 @@ function game_exmportjavame_getanswers_question_select( $game, $context, $table,
 /**
  * Exports to javame.
  *
- * @param stdClass $game
+ * @param $game
- * @param stdClass $context
+ * @param $context
  * @param $exportattachments
  * @param $destdir
  * @param $files
@@ -412,7 +412,7 @@ function game_create_manifest_mf( $dir, $javame, $destmobiledir) {
  * Creates a jar file.
  *
  * @param $srcdir
- * @param stdClass $course
+ * @param $course
  * @param $javame
  */
 function game_create_jar( $srcdir, $course, $javame) {

export/html/snakes/css/subModal.css

@@ -19,7 +19,6 @@
      * you can uncomment the background-image if you don't care about opera.
      * this gives you the flexibility to use any bg color that you want, instead of the png
      */
-    background-image: url("../images/maskBG.png") !important; // For browsers Moz, Opera, etc.
     background-image: none;
     background-repeat: repeat;
     display: none;

export/html/snakes/js/snakes-mod.js

@@ -17,7 +17,6 @@ var laddest = new Array(3);
 var quest = new Array(); // Available questions along with multiple answers.
 var coranswered = new Array(); // Record all questions (along with answers) the user responded CORRECTLY.
 var wroanswered = new Array(); // Record all questions (along with answers) the user responded WRONGLY.
-var user = new Array();
 
 // Constract table with questions and answers and pick question to display.
 
@@ -54,88 +53,6 @@ function selectQuest(all) {
     return pickone;
 }
 
-// The Below Function will hide all the snakes.
-
-function hideAll() {
-    document.getElementById("img1").style.display = "none";
-    document.getElementById("img2").style.display = "none";
-    document.getElementById("img3").style.display = "none";
-    document.getElementById("img4").style.display = "none";
-
-    document.getElementById("lad1").style.display = "none";
-    document.getElementById("lad2").style.display = "none";
-    document.getElementById("lad3").style.display = "none";
-}
-
-// The Below Function will Render The Main Board.
-function paintBoard( a) {
-    var i, j;
-
-    totblocks = (a * a);
-    if ((a * a) % 2 == 0) {
-        currentblock = (a * a) - a + 1;
-        for (j = 0; j < (a / 2); j++) {
-            for (i = 0; i < a; i++) {
-                data += "<div class='blocks' id='" + currentblock + "'>" + currentblock + "</div>";
-                currentblock++;
-            }
-            currentblock -= (a + 1);
-
-            for (i = 0; i < a; i++) {
-                data += "<div id='" + currentblock + "' class ='blocks'>" + currentblock + "</div>";
-                currentblock--;
-            }
-            currentblock -= (a - 1);
-        }
-    } else {
-        currentblock = (a * a);
-        for (j = 0; j < (a / 2); j++) {
-            for (i = 0; i < a; i++) {
-                data += "<div class='blocks' id='" + currentblock + "'>" + currentblock + "</div>";
-                currentblock--;
-            }
-
-            currentblock -= (a - 1);
-
-            if (currentblock < 2) {
-                break;
-            }
-
-            for (i = 0; i < a; i++) {
-                data += "<div id='" + currentblock + "' class ='blocks'>" + currentblock + "</div>";
-                currentblock++;
-            }
-            currentblock -= (a + 1);
-        }
-    }
-    document.getElementById("cont").style.width = (a * 52 + 52) + "px";
-
-    document.getElementById("cont").innerHTML = data;
-    $("#cont").slideDown("slow");
-    $("#cont").effect("shake", 3000);
-    $("img:hidden").fadeIn( 5000);
-
-    if (a == 6) {
-        registerSnake(158, 196, "img1", 14, 3, 0);
-        registerSnake(62, 183, "img2", 27, 24, 1);
-        registerSnake(175, 18, "img3", 18, 4, 2);
-        registerSnake(10, 45, "img4", 32, 23, 3);
-
-        registerLadder(27, 132, "lad1", 28, 34, 0);
-        registerLadder(90, 22, "lad2", 19, 30, 1);
-        registerLadder(179, 137, "lad3", 2, 16, 2);
-    } else if (a == 8) {
-        registerSnake(300, 380, "img1", 44, 29, 0);
-        registerSnake(180, 550, "img2", 51, 46, 1);
-        registerSnake(290, 50, "img3", 41, 40, 2);
-        registerSnake(500, 280, "img4", 27, 22, 3);
-
-        registerLadder(350, 515, "lad1", 19, 35, 0);
-        registerLadder(180, 230, "lad2", 43, 54, 1);
-        registerLadder(80, 350, "lad3", 53, 60, 2);
-    }
-}
-
 // The below Function will simulate throwing of a dice.
 function throwDice(i) {
     randomno = Math.floor((Math.random() * 6)) + 1;
@@ -210,31 +127,6 @@ function registerLadder(tp, lft, dv, src, dest, i) {
     laddest[i] = dest;
 }
 
-// The below function starts the play.
-function play() {
-    if (tots[l] != null) {
-        var s;
-
-        s = "<ul class='nodis'><li>O Paiktis " + (l + 1);
-        s = s + " </li><li>brisketai sto tetragwno " + tots[l] + "</li><li></li></ul>";
-        disableField();
-        document.getElementById("status").innerHTML = s;
-
-        question();
-        s = "<ul class='nodis'><li>O Paiktis " + (l + 1);
-        s = s + " </li><li>vrisketai sto tetragwno " + tots[l] + "</li></ul>";
-        document.getElementById("status").innerHTML = s;
-    } else {
-        document.getElementById("status").innerHTML = "<ul class='nodis'><li>Molis exases...</li></ul>";
-    }
-
-    if( l == lastposition.length - 1) {
-        l = 0;
-    } else {
-        l++;
-    }
-}
-
 // The below function regulates the play.
 function doit(i) {
     throwDice(i);
@@ -268,7 +160,7 @@ function question() {
     alert("Randomly selected number:" + picked);
     q1 = prompt(quest[picked * 4], "Απάντηση");
     if (q1 == quest[picked * 4 + 1]) {
-        alert("Σωστά!")
+        alert("Σωστά!");
         doit(l);
 
         coranswered.concat(quest.splice(picked * 4, 4));

hangman/play.php

@@ -33,7 +33,7 @@ defined('MOODLE_INTERNAL') || die();
  * @param $hangman
  * @param $newletter
  * @param $action
- * @param stdClass $context
+ * @param $context
  */
 function game_hangman_continue( $id, $game, $attempt, $hangman, $newletter, $action, $context) {
     global $DB, $USER;
@@ -234,12 +234,12 @@ function game_hangman_onfinishgame( $game, $attempt, $hangman) {
  * Plays the hangman game.
  *
  * @param $id
- * @param stdClass $game
+ * @param $game
- * @param stdClass $attempt
+ * @param $attempt
- * @param stdClass $hangman
+ * @param $hangman
- * @param boolean $onlyshow
+ * @param $onlyshow
- * @param boolean $showsolution
+ * @param $showsolution
- * @param stdClass $context
+ * @param $context
  */
 function game_hangman_play( $id, $game, $attempt, $hangman, $onlyshow, $showsolution, $context) {
     global $CFG, $DB, $OUTPUT;
@@ -326,15 +326,15 @@ function game_hangman_play( $id, $game, $attempt, $hangman, $onlyshow, $showsolu
  * @param $wrong
  * @param $max
  * @param wordline
- * @param @wordline2
+ * @param $wordline2
  * @param $links
  * @param stdClass $game
  * @param $attempt
  * @param $hangman
  * @param $query
- * @param boolean $onlyshow
+ * @param $onlyshow
- * @param boolean $showsolution
+ * @param $showsolution
- * @param $stdClass $context
+ * @param $context
  */
 function hangman_showpage(&$done, &$correct, &$wrong, $max, &$wordline, &$wordline2, &$links,
     $game, &$attempt, &$hangman, &$query, $onlyshow, $showsolution, $context) {
@@ -486,9 +486,9 @@ function hangman_showpage(&$done, &$correct, &$wrong, $max, &$wordline, &$wordli
  *
  * @param $id
  * @param $wordline
- * @param stdClass $game
+ * @param $game
- * @param stdClass $attempt
+ * @param $attempt
- * @param stdClass $hangman
+ * @param $hangman
  * @param $query
  */
 function hangman_oncorrect( $id, $wordline, $game, $attempt, $hangman, $query) {
@@ -513,11 +513,11 @@ function hangman_oncorrect( $id, $wordline, $game, $attempt, $hangman, $query) {
  * @param $id
  * @param $wordline
  * @param $word
- * @param stdClass $game
+ * @param $game
- * @param stdClass $attempt
+ * @param $attempt
- * @param stdClass $hangman
+ * @param $hangman
- * @param boolean $onlyshow
+ * @param $onlyshow
- * @param boolean $showsolution
+ * @param $showsolution
  */
 function hangman_onincorrect( $id, $wordline, $word, $game, $attempt, $hangman, $onlyshow, $showsolution) {
     echo "\r\n<br/><br/><font size=\"5\">\n$wordline</font>\r\n";
@@ -545,9 +545,9 @@ function hangman_onincorrect( $id, $wordline, $word, $game, $attempt, $hangman,
  * Shows the next word.
  *
  * @param $id
- * @param stdClass $game
+ * @param $game
- * @param stdClass $attempt
+ * @param $attempt
- * @param stdClass $hangman
+ * @param $hangman
  */
 function game_hangman_show_nextword( $id, $game, $attempt, $hangman) {
     global $CFG, $DB;

hiddenpicture/play.php

@@ -24,7 +24,15 @@
  */
 
 defined('MOODLE_INTERNAL') || die();
-
+/**
+ * Plays the game "Hidden picture"
+ *
+ * @param $id
+ * @param $game
+ * @param $attempt
+ * @param $hiddenpicture
+ * @param $context
+ */
 function game_hiddenpicture_continue( $id, $game, $attempt, $hiddenpicture, $context) {
     global $DB, $USER;
 

lang/en/game.php

@@ -16,7 +16,6 @@
 
 /**
  * Strings for component 'game', language 'en', branch 'MOODLE_20_STABLE'
- * Translated by Vasilis Daloukas.
  *
  * @package mod_game
  * @copyright 2007 Vasilis Daloukas

lib.php

@@ -53,10 +53,7 @@ define('GAME_REVIEW_SOLUTIONS',  16 * 0x1041);      // Show solutions.
 define('GAME_REVIEW_GENERALFEEDBACK', 32 * 0x1041); // Show general feedback.
 
 /**
- * Given an object containing all the necessary data,
+ * Given an object containing all the necessary data, will create a new instance and return the id number of the new instance.
- * (defined by the form in mod.html) this function
- * will create a new instance and return the id number
- * of the new instance.
  *
  * @param object $instance An object from the form in mod.html
  * @return int The id of the newly inserted game record
@@ -80,9 +77,7 @@ function game_add_instance($game) {
 }
 
 /**
- * Given an object containing all the necessary data,
+ * Given an object containing all the necessary data, this function will update an existing instance with new data.
- * (defined by the form in mod.html) this function
- * will update an existing instance with new data.
  *
  * @param object $instance An object from the form in mod.html
  * @return boolean Success/Fail
@@ -183,9 +178,7 @@ function game_before_add_or_update(&$game) {
 }
 
 /**
- * Given an ID of an instance of this module,
+ * Given an ID of an instance of this module, this function will permanently delete the instance and any data that depends on it.
- * this function will permanently delete the instance
- * and any data that depends on it.
  *
  * @param int $id Id of the module instance
  * @return boolean Success/Failure
@@ -242,9 +235,13 @@ function game_delete_instance($gameid) {
 }
 
 /**
- * Return a small object with summary information about what a
+ * Return a small object with summary information about what a user has done
- * user has done with a given particular instance of this module
+ *
- * Used for user activity reports.
+ * @param $course
+ * @param $user
+ * @param $mod
+ * @param $game
+ *
  * $return->time = the time they did it
  * $return->info = a short text description
  **/
@@ -266,8 +263,7 @@ function game_user_outline($course, $user, $mod, $game) {
 }
 
 /**
- * Print a detailed representation of what a user has done with
+ * Print a detailed representation of what a user has done with a given particular instance of this module, for user activity reports.
- * a given particular instance of this module, for user activity reports.
 
  * @param stdClass $course
  * @param stdClass $user
@@ -298,9 +294,7 @@ function game_user_complete($course, $user, $mod, $game) {
 }
 
 /**
- * Given a course and a time, this module should find recent activity
+ * Given a course and a time, this module should find recent activity that has occurred in game activities and print it out.
- * that has occurred in game activities and print it out.
- * Return true if there was output, or false is there was none.
  *
  * @uses $CFG
  * @return boolean
@@ -320,8 +314,6 @@ function game_print_recent_activity($course, $isteacher, $timestart) {
 
 /**
  * Function to be run periodically according to the moodle cron
- * This function searches for things that need to be done, such
- * as sending out mail, toggling flags etc ...
  *
  * @uses $CFG
  * @return boolean
@@ -334,8 +326,7 @@ function game_cron() {
 }
 
 /**
- * Must return an array of grades for a given instance of this module,
+ * Must return an array of grades for a given instance of this module, indexed by user.
- * indexed by user.  It also returns a maximum allowed grade.
  *
  * Example:
  *    $return->grades = array of grades;
@@ -388,10 +379,7 @@ function game_get_user_grades($game, $userid=0) {
 }
 
 /**
- * Must return an array of user records (all data) who are participants
+ * Must return an array of user records (all data) who are participants for a given instance of game. Must include every user involved
- * for a given instance of game. Must include every user involved
- * in the instance, independient of his role (student, teacher, admin...)
- * See other modules as example.
  *
  * @param int $gameid ID of an instance of this module
  * @return mixed boolean/array of students
@@ -401,10 +389,7 @@ function game_get_participants($gameid) {
 }
 
 /**
- * This function returns if a scale is being used by one game
+ * This function returns if a scale is being used by one game it it has support for grading and scales.
- * it it has support for grading and scales. Commented code should be
- * modified if necessary. See forum, glossary or journal modules
- * as reference.
  *
  * @param int $gameid ID of an instance of this module
  * @return mixed
@@ -526,6 +511,7 @@ function game_grade_item_delete( $game) {
 
 /**
  * Returns all game graded users since a given time for specified game
+ *
  * @param stdClass $activities
  * @param int $index
  * @param int $timestart
@@ -673,6 +659,7 @@ function game_print_recent_mod_activity($activity, $courseid, $detail, $modnames
 
 /**
  * Removes all grades from gradebook
+ *
  * @param int $courseid
  * @param string optional type
  */
@@ -691,6 +678,8 @@ function game_reset_gradebook($courseid, $type='') {
 }
 
 /**
+ * What supports.
+ *
  * @uses FEATURE_GRADE_HAS_GRADE
  * @return bool True if quiz supports feature
  */
@@ -723,6 +712,8 @@ function game_supports($feature) {
 }
 
 /**
+ * get extra capabilities
+ *
  * @global object
  * @global stdClass
  * @return array all other caps used in module
@@ -741,7 +732,6 @@ function game_get_extra_capabilities() {
 
 /**
  * Return a textual summary of the number of attemtps that have been made at a particular game,
- * returns '' if no attemtps have been made yet, unless $returnzero is passed as true.
  *
  * @global stdClass
  * @global object
@@ -809,6 +799,8 @@ function game_format_grade($game, $grade) {
 }
 
 /**
+ * get grading options
+ *
  * @return the options for calculating the quiz grade from the individual attempt grades.
  */
 function game_get_grading_options() {
@@ -896,14 +888,16 @@ function game_extend_settings_navigation($settings, $gamenode) {
     $gamenode->make_active();
 }
 
-/* Returns an array of game type objects to construct
+/* Returns an array of game type objects to construct menu list when adding new game  */
-   menu list when adding new game  */
 require($CFG->dirroot.'/version.php');
 if ($branch >= '31') {
     define('USE_GET_SHORTCUTS', '1');
 }
 
 if (!defined('USE_GET_SHORTCUTS')) {
+    /**
+     * Shows kind of games
+     */
     function game_get_types() {
         global $DB;
 
@@ -1014,9 +1008,7 @@ if (!defined('USE_GET_SHORTCUTS')) {
 
 if (defined('USE_GET_SHORTCUTS')) {
     /**
-     * Returns an array of game type objects to construct
+     * Returns an array of game type objects to construct menu list when adding new game
-     * menu list when adding new game
-     *
      */
     function game_get_shortcuts($defaultitem) {
         global $DB, $CFG;
@@ -1221,8 +1213,8 @@ function mod_game_pluginfile($course, $cm, $context, $filearea, $args, $forcedow
 }
 
 /**
- * Implementation of the function for printing the form elements that control
+ * Implementation of the function for printing the form elements that control whether the course reset functionality affects the Game.
- * whether the course reset functionality affects the Game.
+ *
  * @param object $mform form passed by reference
  */
 function game_reset_course_form_definition(&$mform) {
@@ -1233,6 +1225,7 @@ function game_reset_course_form_definition(&$mform) {
 
 /**
  * Course reset form defaults.
+ *
  * @param stdClass $course
  *
  * @return array
@@ -1242,8 +1235,7 @@ function game_reset_course_form_defaults($course) {
 }
 
 /**
- * Actual implementation of the reset course functionality, delete all the
+ * Actual implementation of the reset course functionality, delete all the Game responses for course $data->courseid.
- * Game responses for course $data->courseid.
  *
  * @global object
  * @param $data the data submitted from the reset course.
@@ -1348,8 +1340,7 @@ function game_reset_userdata($data) {
 }
 
 /**
- * Obtains the automatic completion state for this module based on any conditions
+ * Obtains the automatic completion state for this module based on any conditions in game settings.
- * in game settings.
  *
  * @param object $course Course
  * @param object $cm Course-module

locallib.php

@@ -554,7 +554,13 @@ function game_questions_selectrandom_detail( $table, $select, $idfield="id", $co
     }
 }
 
-// Tries to detect the language of word.
+/**
+ * Tries to detect the language of word.
+ *
+ * @param $word
+ *
+ * @return the language detected
+ */
 function game_detectlanguage( $word) {
     global $CFG;
 
@@ -591,7 +597,15 @@ function game_detectlanguage( $word) {
     return false;
 }
 
-// The words maybe are in two languages e.g. greek or english so I try to find the correct one.
+/**
+ * The words maybe are in two languages e.g. greek or english so I try to find the correct one.
+ *
+ * @param $word
+ * @param $lang
+ * @param $userlanguage
+ *
+ * @return the letters detected
+ */
 function game_getallletters( $word, $lang='', $userlanguage='') {
     for (;;) {
         if ($lang == 'user') {
@@ -622,6 +636,14 @@ function game_getallletters( $word, $lang='', $userlanguage='') {
     return '';
 }
 
+/**
+ * true if exist all the letters
+ *
+ * @param $str
+ * @param $strfile
+ *
+ * @return the letters detected
+ */
 function hangman_existall( $str, $strfind) {
     $n = game_strlen( $str);
     for ($i = 0; $i < $n; $i++) {
@@ -634,7 +656,13 @@ function hangman_existall( $str, $strfind) {
     return true;
 }
 
-// Used by cross.
+/**
+ * return a short answer randomly selected. used by cross
+ *
+ * @param $game
+ *
+ * @return a question
+ */
 function game_questions_shortanswer( $game) {
     switch( $game->sourcemodule) {
         case 'glossary':
@@ -651,7 +679,13 @@ function game_questions_shortanswer( $game) {
     return $recs;
 }
 
-// Used by cross.
+/**
+ * return a short answer (from glossary) randomly selected. used by cross
+ *
+ * @param $game
+ *
+ * @return a question
+ */
 function game_questions_shortanswer_glossary( $game) {
     global $DB;
 
@@ -670,7 +704,13 @@ function game_questions_shortanswer_glossary( $game) {
     return $DB->get_records_sql( $sql);
 }
 
-// Used by cross.
+/**
+ * return a short answer (from quiz) randomly selected. used by cross
+ *
+ * @param $game
+ *
+ * @return a question
+ */
 function game_questions_shortanswer_quiz( $game) {
     global $DB;
 
@@ -701,7 +741,13 @@ function game_questions_shortanswer_quiz( $game) {
     return game_questions_shortanswer_question_fraction( $table, $fields, $select);
 }
 
-// Used by cross.
+/**
+ * return a short answer (from question) randomly selected. used by cross
+ *
+ * @param $game
+ *
+ * @return a question
+ */
 function game_questions_shortanswer_question( $game) {
     if ($game->questioncategoryid == 0) {
         print_error( get_string( 'must_select_questioncategory', 'game'));
@@ -726,6 +772,15 @@ function game_questions_shortanswer_question( $game) {
     return game_questions_shortanswer_question_fraction( $table, $fields, $select);
 }
 
+/**
+ * question fraction
+ *
+ * @param $table
+ * @param $field
+ * @param $select
+ *
+ * @return the record
+ */
 function game_questions_shortanswer_question_fraction( $table, $fields, $select) {
     global $DB;
 
@@ -757,6 +812,13 @@ function game_questions_shortanswer_question_fraction( $table, $fields, $select)
     return $recs2;
 }
 
+/**
+ * sets char
+ *
+ * @param $d
+ * @param $pos
+ * @param $char
+ */
 function game_setchar( &$s, $pos, $char) {
     $ret = "";
 
@@ -767,6 +829,12 @@ function game_setchar( &$s, $pos, $char) {
     $s = $ret . $char . game_substr( $s, $pos + 1);
 }
 
+/**
+ * insert a record
+ *
+ * @param $table
+ * @param $rec
+ */
 function game_insert_record( $table, $rec) {
     global $DB;
 
@@ -791,7 +859,16 @@ function game_insert_record( $table, $rec) {
     return $ret;
 }
 
-// If score is negative doesn't update the record score is between 0 and 1.
+/**
+ * If score is negative doesn't update the record score is between 0 and 1.
+ *
+ * @param $game
+ * @param $attempt
+ * @param $score
+ * @param $finished
+ *
+ * @return the record
+ */
 function game_updateattempts( $game, $attempt, $score, $finished) {
     global $DB, $USER;
 
@@ -837,6 +914,16 @@ function game_updateattempts( $game, $attempt, $score, $finished) {
     }
 }
 
+/**
+ * Computes max grade
+ *
+ * @param $game
+ * @param $attempt
+ * @param $grade
+ * @param $finished
+ *
+ * @return the record
+ */
 function game_updateattempts_maxgrade( $game, $attempt, $grade, $finished) {
     global $DB;
 
@@ -849,6 +936,18 @@ function game_updateattempts_maxgrade( $game, $attempt, $grade, $finished) {
     game_updateattempts( $game, $attempt, $grade, $finished);
 }
 
+/**
+ * Update queries
+ *
+ * @param $game
+ * @param $attempt
+ * @param $query
+ * @param $score
+ * @param $studentanswer
+ * @param $updatetries
+ *
+ * @return the record
+ */
 function game_update_queries( $game, $attempt, $query, $score, $studentanswer, $updatetries=false) {
     global $DB, $USER;
 
@@ -905,6 +1004,13 @@ function game_update_queries( $game, $attempt, $query, $score, $studentanswer, $
     }
 }
 
+/**
+ * get attempt
+ *
+ * @param $game
+ * @param $detail
+ * @param $autoadd
+ */
 function game_getattempt( $game, &$detail, $autoadd=false) {
     global $DB, $USER;
 
@@ -939,6 +1045,8 @@ function game_getattempt( $game, &$detail, $autoadd=false) {
 }
 
 /**
+ * get user attempts
+ *
  * @param integer $gameid the game id.
  * @param integer $userid the userid.
  * @param string $status 'all', 'finished' or 'unfinished' to control
@@ -963,8 +1071,7 @@ function game_get_user_attempts( $gameid, $userid, $status = 'finished') {
 
 
 /**
- * Returns an unfinished attempt (if there is one) for the given
+ * Returns an unfinished attempt (if there is one) for the given user on the given game. This function does not return preview attempts.
- * user on the given game. This function does not return preview attempts.
  *
  * @param integer $gameid the id of the game.
  * @param integer $userid the id of the user.
@@ -1000,6 +1107,13 @@ function game_get_best_score($game, $userid) {
     }
 }
 
+/**
+ * Get the best current grade for a particular user in a game.
+ *
+ * @param object $game the game object.
+ * @param integer $userid the id of the user.
+ * @return float the user's current grade for this game.
+ */
 function game_get_best_grade($game, $userid) {
     $score = game_get_best_score( $game, $userid);
 
@@ -1010,6 +1124,13 @@ function game_get_best_grade($game, $userid) {
     }
 }
 
+/**
+ * Converts score to grade
+ *
+ * @param $score
+ * @param $grade
+ * @return float the user's current grade for this game.
+ */
 function game_score_to_grade($score, $game) {
     if ($score) {
         return round($score * $game->grade, $game->decimalpoints);
@@ -1071,6 +1192,13 @@ function game_get_reviewoptions($game, $attempt, $context=null) {
     return $options;
 }
 
+/**
+ * Compute attempt layout
+ *
+ * @param object $game the game object.
+ * @param $attempt
+ * @return float the user's current grade for this game.
+ */
 function game_compute_attempt_layout( $game, &$attempt) {
     global $DB;
 
@@ -1092,9 +1220,6 @@ function game_compute_attempt_layout( $game, &$attempt) {
 
 /**
  * Combines the review options from a number of different game attempts.
- * Returns an array of two ojects, so he suggested way of calling this
- * funciton is:
- * list($someoptions, $alloptions) = game_get_combined_reviewoptions(...)
  *
  * @param object $game the game instance.
  * @param array $attempts an array of attempt objects.
@@ -1248,6 +1373,11 @@ function game_calculate_best_attempt($game, $attempts) {
     }
 }
 
+/**
+ * get questions for sudoku
+ *
+ * @param $questionlist
+ */
 function game_sudoku_getquestions( $questionlist) {
     global $CFG, $DB;
 
@@ -1268,6 +1398,14 @@ function game_sudoku_getquestions( $questionlist) {
     return $questions;
 }
 
+/**
+ * Filter glossary
+ *
+ * @param $text
+ * @param $entryid
+ * @param $contextid
+ * @param $courseid
+ */
 function game_filterglossary( $text, $entryid, $contextid, $courseid) {
     global $CFG, $DB;
 
@@ -1298,6 +1436,14 @@ function game_filterglossary( $text, $entryid, $contextid, $courseid) {
     return game_filtertext( $text, $courseid);
 }
 
+/**
+ * Filter book
+ *
+ * @param $text
+ * @param $chapterid
+ * @param $contextid
+ * @param $courseid
+ */
 function game_filterbook( $text, $chapterid, $contextid, $courseid) {
     global $CFG, $DB;
 
@@ -1328,6 +1474,14 @@ function game_filterbook( $text, $chapterid, $contextid, $courseid) {
     return game_filtertext( $text, $courseid);
 }
 
+/**
+ * Filter questio
+ *
+ * @param $questiontext
+ * @param $questionid
+ * @param $contextid
+ * @param $courseid
+ */
 function game_filterquestion( $questiontext, $questionid, $contextid, $courseid) {
     global $CFG, $DB;
 
@@ -1358,6 +1512,14 @@ function game_filterquestion( $questiontext, $questionid, $contextid, $courseid)
     return game_filtertext( $questiontext, $courseid);
 }
 
+/**
+ * Filter question answer
+ *
+ * @param $questiontext
+ * @param $questionid
+ * @param $contextid
+ * @param $courseid
+ */
 function game_filterquestion_answer( $questiontext, $questionid, $contextid, $courseid) {
     global $CFG, $DB;
 
@@ -1387,7 +1549,13 @@ function game_filterquestion_answer( $questiontext, $questionid, $contextid, $co
     return game_filtertext( $questiontext, $courseid);
 }
 
-function game_filtertext( $text, $courseid) {
+/**
+ * Filter text
+ *
+ * @param $text
+ * @param $courseid
+ */
+ function game_filtertext( $text, $courseid) {
     $formatoptions = new stdClass();
     $formatoptions->noclean = true;
     $formatoptions->filter = 1;
@@ -1408,6 +1576,11 @@ function game_filtertext( $text, $courseid) {
     return $text;
 }
 
+/**
+ * To javascript string
+ *
+ * @param $text
+ */
 function game_tojavascriptstring( $text) {
     $from = array('"', "\r", "\n");
     $to = array('\"', ' ', ' ');
@@ -1420,6 +1593,11 @@ function game_tojavascriptstring( $text) {
     return $text;
 }
 
+/**
+ * Repair question
+ *
+ * @param $s
+ */
 function game_repairquestion( $s) {
     if (substr( $s, 0, 3) == '<p>') {
         $s = substr( $s, 3);
@@ -1447,6 +1625,9 @@ function game_repairquestion( $s) {
 
 /**
  * Delete a game attempt.
+ *
+ * @param $attempt
+ * @param $game
  */
 function game_delete_attempt($attempt, $game) {
     global $DB;
@@ -1479,8 +1660,7 @@ function game_delete_attempt($attempt, $game) {
 }
 
 /**
- * Returns the most recent attempt by a given user on a given game.
+ * Returns the most recent attempt by a given user on a given game. May be finished, or may not.
- * May be finished, or may not.
  *
  * @param integer $gameid the id of the game.
  * @param integer $userid the id of the user.
@@ -1501,6 +1681,8 @@ function game_get_latest_attempt_by_user($gameid, $userid) {
 }
 
 /**
+ * get grading option name
+ *
  * @param int $option one of the values GAME_GRADEHIGHEST, GAME_GRADEAVERAGE, GAME_ATTEMPTFIRST or GAME_ATTEMPTLAST.
  * @return the lang string for that option.
  */
@@ -1514,10 +1696,22 @@ function game_get_grading_option_name($option) {
     return $strings[$option];
 }
 
+/**
+ * Right to left.
+ *
+ * @param $lang
+ */
 function game_right_to_left( $lang) {
     return ( get_string_manager()->get_string('thisdirection', 'langconfig', null, $lang) == 'rtl');
 }
 
+/**
+ * Compute reverse print
+ *
+ * @param $attempt
+ * @param $wordctrl
+ * @param $reverseprint
+ */
 function game_compute_reserve_print( $attempt, &$wordrtl, &$reverseprint) {
     if (function_exists( 'right_to_left')) {
         if ($attempt->language != '') {
@@ -1532,6 +1726,13 @@ function game_compute_reserve_print( $attempt, &$wordrtl, &$reverseprint) {
     }
 }
 
+/**
+ * select from repetitions
+ *
+ * @param $game
+ * @param $recs
+ * @param $need
+ */
 function game_select_from_repetitions( $game, $recs, $need) {
     global $DB, $USER;
 
@@ -1573,6 +1774,15 @@ function game_select_from_repetitions( $game, $recs, $need) {
     return $ret;
 }
 
+/**
+ * Grades responses
+ *
+ * @param $question
+ * @param $responses
+ * @param $maxgrade
+ * @param $answertext
+ * @param $answered
+ */
 function game_grade_responses( $question, $responses, $maxgrade, &$answertext, &$answered) {
     $answered = true;
 
@@ -1608,6 +1818,14 @@ function game_grade_responses( $question, $responses, $maxgrade, &$answertext, &
     }
 }
 
+/**
+ * Responses multianswer
+ *
+ * @param $question
+ * @param $responses
+ * @param $maxgrade
+ * @param $answertext
+ */
 function game_grade_responses_multianswer( $question, $responses, $maxgrade, &$answertext) {
     $name = "resp{$question->id}_";
 
@@ -1628,6 +1846,13 @@ function game_grade_responses_multianswer( $question, $responses, $maxgrade, &$a
     return $fraction * $maxgrade;
 }
 
+/**
+ * Print question
+ *
+ * @param $game
+ * @param $question
+ * @param $context
+ */
 function game_print_question( $game, $question, $context) {
     if ($question->qtype == 'multichoice') {
         if ($question->options->single == 0) {
@@ -1640,6 +1865,13 @@ function game_print_question( $game, $question, $context) {
     }
 }
 
+/**
+ * Print question multichoice
+ *
+ * @param $game
+ * @param $question
+ * @param $context
+ */
 function game_print_question_multichoice( $game, $question, $context) {
     global $CFG;
 
@@ -1696,6 +1928,13 @@ foreach ($anss as $answer) {
 <?php
 }
 
+/**
+ * Print question multianswer
+ *
+ * @param object $game the game object.
+ * @param $question
+ * @param $context
+ */
 function game_print_question_multianswer( $game, $question, $context) {
     global $CFG;
 
@@ -1773,6 +2012,11 @@ echo game_filterquestion(str_replace( '\"', '"', $questiontext), $question->id,
 <?php
 }
 
+/**
+ * Snakes get board.
+ *
+ * @param object $game the game object.
+ */
 function game_snakes_get_board( $game) {
     global $CFG, $DB;
 
@@ -1795,6 +2039,11 @@ function game_snakes_get_board( $game) {
     return $board;
 }
 
+/**
+ * Creates user defined board.
+ *
+ * @param object $game the game object.
+ */
 function game_snakes_create_user_defined_board( &$game) {
     global $CFG, $DB;
 
@@ -1851,6 +2100,11 @@ function game_snakes_create_user_defined_board( &$game) {
     return $board;
 }
 
+/**
+ * Snakes get board params.
+ *
+ * @param object $game the game object.
+ */
 function game_snakes_get_board_params( $game) {
     $board = new stdClass();
 
@@ -1869,6 +2123,9 @@ function game_snakes_get_board_params( $game) {
     return $board;
 }
 
+/**
+ * Export create temp dir
+ */
 function game_export_createtempdir() {
     global $CFG;
 
@@ -1889,6 +2146,13 @@ function game_export_createtempdir() {
     }
 }
 
+/**
+ * Create zip
+ *
+ * @param $srcdir
+ * @param $couseid
+ * @param $filename
+ */
 function game_create_zip( $srcdir, $courseid, $filename) {
     global $CFG;
 
@@ -1918,12 +2182,26 @@ function game_create_zip( $srcdir, $courseid, $filename) {
     return (file_exists( $filezip) ? $filezip : '');
 }
 
+/**
+ * Get string lang
+ *
+ * @param $identifier
+ * @param $module
+ * @param $lang
+ */
 function game_get_string_lang( $identifier, $module, $lang) {
     global $CFG;
 
     return get_string_manager()->get_string($identifier, $module, null, $lang);
 }
 
+/**
+ * Get string from file
+ *
+ * @param $identifier
+ * @param $lanfile
+ * @param $destination
+ */
 function get_string_from_file($identifier, $langfile, $destination) {
     static $strings;    // Keep the strings cached in memory.
 
@@ -1942,7 +2220,11 @@ function get_string_from_file($identifier, $langfile, $destination) {
     return $string[ $identifier];
 }
 
-// Inserts a record to game_attempts.
+/**
+ * Inserts a record to game_attempts.
+ *
+ * @param object $game the game object.
+ */
 function game_addattempt( $game) {
     global $DB, $USER;
 
@@ -1970,6 +2252,9 @@ function game_addattempt( $game) {
     return $DB->get_record_select( 'game_attempts', 'id='.$newid);
 }
 
+/**
+ * Get contexts
+ */
 function game_get_contexts() {
     global $CFG, $COURSE;
 
@@ -1981,6 +2266,17 @@ function game_get_contexts() {
     return $contexts->having_one_cap( $caps);
 }
 
+/**
+ * Export split files
+ *
+ * @param $courseid
+ * @param $context
+ * @param $filearea
+ * @param $id
+ * @param $line
+ * @param $destdir
+ * @pram $files
+ */
 function game_export_split_files( $courseid, $context, $filearea, $id, $line, $destdir, &$files) {
     global $CFG, $DB;
 
@@ -2039,6 +2335,11 @@ function game_export_split_files( $courseid, $context, $filearea, $id, $line, $d
     return $line;
 }
 
+/**
+ * Grade questions
+ *
+ * @param $questions
+ */
 function game_grade_questions( $questions) {
     $grades = array();
     foreach ($_POST as $key => $value) {
@@ -2090,6 +2391,9 @@ function game_question_get_id_from_name_prefix($name) {
     return (integer) $matches[ 1];
 }
 
+/**
+ * Get version.
+ */
 function game_get_version() {
     global $CFG, $DB;
 
@@ -2106,6 +2410,11 @@ function game_get_version() {
     return $module->version;
 }
 
+/**
+ * Can start a new attempt
+ *
+ * @param object $game the game object.
+ */
 function game_can_start_new_attempt( $game) {
     global $DB, $USER;
 
@@ -2125,6 +2434,11 @@ function game_can_start_new_attempt( $game) {
     }
 }
 
+/**
+ * strlen
+ *
+ * @param $str
+ */
 function game_strlen( $str) {
     if (game_get_moodle_version() >= '02.08') {
         return core_text::strlen( $str);
@@ -2135,6 +2449,9 @@ function game_strlen( $str) {
     }
 }
 
+/**
+ * substr
+ */
 function game_substr() {
     $num = func_num_args();
     $a = func_get_args();
@@ -2161,6 +2478,11 @@ function game_substr() {
     }
 }
 
+/**
+ * strtoupper
+ *
+ * @param $str
+ */
 function game_strtoupper( $str) {
     if (game_get_moodle_version() >= '02.08') {
         return core_text::strtoupper( $str);
@@ -2174,6 +2496,13 @@ function game_strtoupper( $str) {
     }
 }
 
+/**
+ * strpos
+ *
+ * @param $haystack
+ * @param $needle
+ * @param $offset
+ */
 function game_strpos( $haystack, $needle, $offset = 0) {
     if (game_get_moodle_version() >= '02.08') {
         return core_text::strpos( $haystack, $needle, $offset);
@@ -2186,6 +2515,13 @@ function game_strpos( $haystack, $needle, $offset = 0) {
     return textlib_get_instance()->strpos( $haystack, $needle, $offset);
 }
 
+/**
+ * show query
+ *
+ * @param object $game the game 
+ * @param $query
+ * @param $text
+ */
 function game_show_query( $game, $query, $text) {
     if ($game->glossaryid) {
         $cmglossary = get_coursemodule_from_instance('glossary', $game->glossaryid, $game->course);
@@ -2201,6 +2537,9 @@ function game_show_query( $game, $query, $text) {
     return $text;
 }
 
+/**
+ * use events?
+ */
 function game_use_events() {
     $version = game_get_moodle_version();
 
@@ -2208,8 +2547,7 @@ function game_use_events() {
 }
 
 /**
- * Get the feedback text that should be show to a student who
+ * Get the feedback text that should be show to a student who got this grade on this game.
- * got this grade on this game.
  *
  * @param float $grade a grade on this game.
  * @param integer $gameid the id of the game object.