From 4adeba282315131cfd00146fe5306c6ad97880a7 Mon Sep 17 00:00:00 2001 From: bdaloukas Date: Sun, 18 Jun 2017 10:34:28 +0300 Subject: [PATCH] phpdoc compatibility --- README.md | 2 +- lib.php | 7 -- millionaire/play.php | 121 +++++++++++++++++++- mod_form.php | 24 +++- print.php | 7 ++ report/default.php | 23 ++++ report/overview/report.php | 15 ++- showanswers.php | 56 ++++++++++ showattempts.php | 20 ++++ snakes/createboard.php | 112 ++++++++++++++++++- sudoku/class.Sudoku.php | 208 ++++++++++++++++++----------------- sudoku/create.php | 7 ++ sudoku/play.php | 13 ++- sudoku/sdd/class.SDD.php | 35 +++--- sudoku/sdd/class.logfile.php | 17 ++- translate.php | 55 +++++++++ 16 files changed, 577 insertions(+), 145 deletions(-) diff --git a/README.md b/README.md index 4665922..921e19e 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ This module gets input from quiz, glossary or questions and plays some games. Th * The hidden picture * Book with questions -If you like the Game activity module please consider donating bdaloukas (at) yahoo (dot) gr via paypal to help me have more time to continue working on this project. This module is and will remain free, but your donation allows me to continue the development, and any amount is greatly appreciated. +If you like the Game activity module please consider donating at https://www.paypal.me/moodlegame to help me have more time to continue working on this project. This module is and will remain free, but your donation allows me to continue the development, and any amount is greatly appreciated. * Changelog: CHANGES.md * Documentation: http://docs.moodle.org/en/Game_module diff --git a/lib.php b/lib.php index 80579be..08dd788 100644 --- a/lib.php +++ b/lib.php @@ -714,8 +714,6 @@ function game_supports($feature) { /** * get extra capabilities * - * @global object - * @global stdClass * @return array all other caps used in module */ function game_get_extra_capabilities() { @@ -733,9 +731,6 @@ function game_get_extra_capabilities() { /** * Return a textual summary of the number of attemtps that have been made at a particular game, * - * @global stdClass - * @global object - * @global object * @param object $game the game object. Only $game->id is used at the moment. * @param object $cm the cm object. Only $cm->course, $cm->groupmode and $cm->groupingid fields are used at the moment. * @param boolean $returnzero if false (default), when no attempts have been made '' is returned instead of 'Attempts: 0'. @@ -1237,7 +1232,6 @@ function game_reset_course_form_defaults($course) { /** * Actual implementation of the reset course functionality, delete all the Game responses for course $data->courseid. * - * @global object * @param $data the data submitted from the reset course. * * @return array status array @@ -1378,7 +1372,6 @@ function game_get_completion_state($course, $cm, $userid, $type) { * * This is used to find out if scale used anywhere * - * @global object * @param int $scaleid * @return boolean True if the scale is used by any Game */ diff --git a/millionaire/play.php b/millionaire/play.php index 81e57f8..61f2d38 100644 --- a/millionaire/play.php +++ b/millionaire/play.php @@ -24,6 +24,15 @@ defined('MOODLE_INTERNAL') || die(); +/** + * Plays the millionaire + * + * @param $id + * @param $game + * @param $attempt + * @param $millionaire + * @param $context + */ function game_millionaire_continue( $id, $game, $attempt, $millionaire, $context) { // User must select quiz or question as a source module. if (($game->quizid == 0) and ($game->questioncategoryid == 0)) { @@ -56,6 +65,15 @@ function game_millionaire_continue( $id, $game, $attempt, $millionaire, $context game_millionaire_play( $id, $game, $attempt, $newrec, $context); } +/** + * Plays the millionaire + * + * @param $id + * @param $game + * @param $attempt + * @param $millionaire + * @param $context + */ function game_millionaire_play( $id, $game, $attempt, $millionaire, $context) { global $DB; @@ -96,6 +114,17 @@ function game_millionaire_play( $id, $game, $attempt, $millionaire, $context) { } } +/** + * Shows the grid + * + * @param $game + * @param $millionaire + * @param $id + * @param $query + * @param $aanswer + * @param $info + * @param $context + */ function game_millionaire_showgrid( $game, $millionaire, $id, $query, $aanswer, $info, $context) { global $CFG, $OUTPUT; @@ -285,6 +314,15 @@ function game_millionaire_showgrid( $game, $millionaire, $id, $query, $aanswer, echo "\r\n"; } +/** + * Show next question + * + * @param $id + * @param $game + * @param $attempt + * @param $millionaire + * @param $context + */ function game_millionaire_shownextquestion( $id, $game, $attempt, $millionaire, $context) { game_millionaire_selectquestion( $aanswer, $game, $attempt, $millionaire, $query, $context); @@ -299,7 +337,16 @@ function game_millionaire_shownextquestion( $id, $game, $attempt, $millionaire, } } -// Updates tables: games_millionaire, game_attempts, game_questions. +/** + * Updates tables: games_millionaire, game_attempts, game_questions. + * + * @param $answer + * @param $game + * @param $attemt + * @param $millionaire + * @param $query + * @param $context + */ function game_millionaire_selectquestion( &$aanswer, $game, $attempt, &$millionaire, &$query, $context) { global $DB, $USER; @@ -425,6 +472,16 @@ function game_millionaire_selectquestion( &$aanswer, $game, $attempt, &$milliona game_update_queries( $game, $attempt, $query, $score, ''); } +/** + * Select serial question + * + * @param $game + * @param $table + * @param $select + * @param $idfields + * @param $level + * @param $order + */ function game_millionaire_select_serial_question( $game, $table, $select, $idfields = "id", $level, $order) { global $DB, $USER; @@ -455,6 +512,15 @@ function game_millionaire_select_serial_question( $game, $table, $select, $idfie return $questions[ $pos]; } +/** + * Load questions for millionaire + * + * @param $game + * @param $millionaire + * @param $query + * @param $aanswer + * @param $context + */ function game_millionaire_loadquestions( $game, $millionaire, &$query, &$aanswer, $context) { global $DB; @@ -470,7 +536,12 @@ function game_millionaire_loadquestions( $game, $millionaire, &$query, &$aanswer } } -// Flag 1 is 5050, 2 is telephone 4 is people. +/** + * Set state. Flag 1 is 5050, 2 is telephone 4 is people. + * + * @param $millionaire + * @param $mask + */ function game_millionaire_setstate( &$millionaire, $mask) { global $DB; @@ -484,6 +555,15 @@ function game_millionaire_setstate( &$millionaire, $mask) { } } +/** + * One help 50-50 + * + * @param $game + * @param $id + * @param $millionaire + * @param $query + * @param $context + */ function game_millionaire_onhelp5050( $game, $id, &$millionaire, $query, $context) { game_millionaire_loadquestions( $game, $millionaire, $query, $aanswer, $context); @@ -512,6 +592,15 @@ function game_millionaire_onhelp5050( $game, $id, &$millionaire, $query, $conte game_millionaire_showgrid( $game, $millionaire, $id, $query, $aanswer, '', $context); } +/** + * One help telephone + * + * @param $game + * @param $id + * @param $millionaire + * @param $query + * @param $context + */ function game_millionaire_onhelptelephone( $game, $id, &$millionaire, $query, $context) { game_millionaire_loadquestions( $game, $millionaire, $query, $aanswer, $context); @@ -546,6 +635,15 @@ function game_millionaire_onhelptelephone( $game, $id, &$millionaire, $query, game_millionaire_showgrid( $game, $millionaire, $id, $query, $aanswer, $info, $context); } +/** + * One help people + * + * @param $game + * @param $id + * @param $millionaire + * @param $query + * @param $context + */ function game_millionaire_onhelppeople( $game, $id, &$millionaire, $query, $context) { game_millionaire_loadquestions( $game, $millionaire, $query, $aanswer, $context); @@ -586,6 +684,17 @@ function game_millionaire_onhelppeople( $game, $id, &$millionaire, $query, $con game_millionaire_showgrid( $game, $millionaire, $id, $query, $aanswer, game_substr( $info, 4), $context); } +/** + * Millionaire on answer + * + * @param $id + * @param $game + * @param $attempt + * @param $millionaire + * @param $query + * @param $answer + * @param $context + */ function game_millionaire_onanswer( $id, $game, $attempt, &$millionaire, $query, $answer, $context) { global $DB; @@ -633,6 +742,14 @@ function game_millionaire_onanswer( $id, $game, $attempt, &$millionaire, $query, } } +/** + * Millionaire on quit + * + * @param $id + * @param $game + * @param $attempt + * @param $query + */ function game_millionaire_onquit( $id, $game, $attempt, $query) { global $CFG, $DB; diff --git a/mod_form.php b/mod_form.php index d07b3fe..ee85732 100644 --- a/mod_form.php +++ b/mod_form.php @@ -27,8 +27,18 @@ defined('MOODLE_INTERNAL') || die(); require_once( $CFG->dirroot.'/course/moodleform_mod.php'); require( 'locallib.php'); +/** + * The class defines the form of game parameters + * + * @package mod_game + * @copyright 2014 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class mod_game_mod_form extends moodleform_mod { + /** + * definition + */ public function definition() { global $CFG, $DB, $COURSE; @@ -418,6 +428,14 @@ class mod_game_mod_form extends moodleform_mod { $this->add_action_buttons(); } + /** + * validation + * + * @param $data + * @param $files + * + * @return moodle_url + */ public function validation($data, $files) { $errors = parent::validation($data, $files); @@ -430,7 +448,11 @@ class mod_game_mod_form extends moodleform_mod { return $errors; } - + /** + * Set data + * + * @param $defaultvalues + */ public function set_data($defaultvalues) { global $DB; diff --git a/print.php b/print.php index 671f0fd..ad90423 100644 --- a/print.php +++ b/print.php @@ -37,6 +37,13 @@ require_capability('mod/game:view', $context); game_print( $game, $id, $context); +/** + * Print + * + * @param $game + * @param $update + * @param $context + */ function game_print( $game, $update, $context) { if ( $game->gamekind == 'cross') { game_print_cross( $game, $update, $context); diff --git a/report/default.php b/report/default.php index 1e2bd71..8f2341c 100644 --- a/report/default.php +++ b/report/default.php @@ -39,13 +39,36 @@ defined('MOODLE_INTERNAL') || die(); +/** + * default report + * + * @package mod_game + * @copyright 2014 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class game_default_report { + /** + * Display + * + * @param $cm + * @param $course + * @param $game + */ public function display($cm, $course, $game) { // This function just displays the report. return true; } + /** + * print header and tabs + * + * @param $cm + * @param $course + * @param $game + * @param $reportmode + * @param $meta + */ public function print_header_and_tabs($cm, $course, $game, $reportmode = "overview", $meta = "") { global $CFG; diff --git a/report/overview/report.php b/report/overview/report.php index 8210d9f..f135458 100644 --- a/report/overview/report.php +++ b/report/overview/report.php @@ -14,8 +14,6 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . -defined('MOODLE_INTERNAL') || die(); - /* * This script lists student attempts. * @@ -24,12 +22,25 @@ defined('MOODLE_INTERNAL') || die(); * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ +defined('MOODLE_INTERNAL') || die(); + require_once($CFG->libdir.'/tablelib.php'); +/** + * The class prints a report + * + * @package mod_game + * @copyright 2014 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class game_report extends game_default_report { /** * Display the report. + * + * @param $game + * @param $cm + * @param $course */ public function display($game, $cm, $course) { global $CFG, $SESSION, $DB; diff --git a/showanswers.php b/showanswers.php index 6b8152f..7d132ab 100644 --- a/showanswers.php +++ b/showanswers.php @@ -55,6 +55,11 @@ game_showanswers( $game, $existsbook, $context); echo $OUTPUT->footer(); +/** + * Compute repetitions + * + * @param $game + */ function game_compute_repetitions($game) { global $DB, $USER; @@ -69,6 +74,11 @@ function game_compute_repetitions($game) { } } +/** + * Show users + * + * @param $game + */ function game_showusers($game) { global $CFG, $USER; @@ -129,6 +139,13 @@ function game_showusers($game) { echo $output . '' . "\n"; } +/** + * Show answers + * + * @param $game + * @param $existsbook + * @param $context + */ function game_showanswers( $game, $existsbook, $context) { if ($game->gamekind == 'bookquiz' and $existsbook) { game_showanswers_bookquiz( $game, $context); @@ -148,6 +165,11 @@ function game_showanswers( $game, $existsbook, $context) { } } +/** + * append select to SQL + * + * @param $game + */ function game_showanswers_appendselect( $game) { switch ($game->gamekind) { case 'hangman': @@ -165,6 +187,12 @@ function game_showanswers_appendselect( $game) { return ''; } +/** + * Show answers question + * + * @param $game + * @param $context + */ function game_showanswers_question( $game, $context) { global $DB; @@ -197,6 +225,12 @@ function game_showanswers_question( $game, $context) { game_showanswers_question_select( $game, '{question} q', $select, '*', $order, $showcategories, $game->course, $context); } +/** + * Show answers quiz + * + * @param $game + * @param $context + */ function game_showanswers_quiz( $game, $context) { global $CFG; @@ -215,6 +249,18 @@ function game_showanswers_quiz( $game, $context) { game_showanswers_question_select( $game, $table, $select, 'q.*', 'category,questiontext', false, $game->course, $context); } +/** + * Create the select for SQL + * + * @param $game + * @param $table + * @param $select + * @param $fields + * @param $order + * @param $showcategoryname + * @param $courseid + * @param $context + */ function game_showanswers_question_select( $game, $table, $select, $fields, $order, $showcategoryname, $courseid, $context) { global $CFG, $DB, $OUTPUT; @@ -354,6 +400,11 @@ function game_showanswers_question_select( $game, $table, $select, $fields, $ord echo "
\r\n\r\n"; } +/** + * Show answers glossary + * + * @param $game + */ function game_showanswers_glossary( $game) { global $CFG, $DB; @@ -432,6 +483,11 @@ function game_showanswers_glossary( $game) { echo "
\r\n\r\n"; } +/** + * Show answers bookquiz + * + * @param $game + */ function game_showanswers_bookquiz( $game, $context) { global $CFG; diff --git a/showattempts.php b/showattempts.php index 5b35bee..7248648 100644 --- a/showattempts.php +++ b/showattempts.php @@ -47,6 +47,11 @@ game_showattempts( $game); echo $OUTPUT->footer(); +/** + * Show users + * + * @param $game + */ function game_showusers($game) { global $CFG, $USER, $DB; @@ -114,6 +119,11 @@ function game_showusers($game) { echo $output . '' . "\n"; } +/** + * Show groups + * + * @param $game + */ function game_showgroups($game) { global $CFG, $USER, $DB; @@ -167,6 +177,11 @@ function game_showgroups($game) { echo $output . '' . "\n"; } +/** + * Show attempts + * + * @param $game + */ function game_showattempts($game) { global $CFG, $DB, $OUTPUT; @@ -264,6 +279,11 @@ function game_showattempts($game) { } } +/** + * One delete attempt + * + * @param $game + */ function game_ondeleteattempt( $game) { global $CFG, $DB; diff --git a/snakes/createboard.php b/snakes/createboard.php index bb7a916..d1176c3 100644 --- a/snakes/createboard.php +++ b/snakes/createboard.php @@ -14,8 +14,6 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . -defined('MOODLE_INTERNAL') || die(); - /** * This file creates a board for "Snakes and Ladders". * @@ -23,6 +21,18 @@ defined('MOODLE_INTERNAL') || die(); * @copyright 2007 Vasilis Daloukas * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ + +defined('MOODLE_INTERNAL') || die(); + +/** + * Create snakes board + * + * @param $imageasstring + * @param $colsx + * @param $colsy + * @param $ofstop + * @param $ofsbottom + */ function game_createsnakesboard($imageasstring, $colsx, $colsy, $ofstop, $ofsbottom, $ofsright, $ofsleft, $board, $setwidth, $setheight) { global $CFG; @@ -84,6 +94,15 @@ function game_createsnakesboard($imageasstring, $colsx, $colsy, $ofstop, $ofsbot return $im; } +/** + * Compute coordinates + * + * @param $pos + * @param $x + * @param $y + * @param $colsx + * @param $colsy + */ function computexy( $pos, &$x, &$y, $colsx, $colsy) { $x = ($pos - 1) % $colsx; $y = ($colsy - 1) - floor( ($pos - 1) / $colsy); @@ -92,6 +111,18 @@ function computexy( $pos, &$x, &$y, $colsx, $colsy) { } } +/** + * Make board + * + * @param $im + * @param $cs + * @param $cy + * @param $board + * @param $colsx + * @param $colsy + * @param $ofsleft + * @param $ofstop + */ function makeboard( $im, $dir, $cx, $cy, $board, $colsx, $colsy, $ofsleft, $ofstop) { $a = explode( ',', $board); foreach ($a as $s) { @@ -103,6 +134,19 @@ function makeboard( $im, $dir, $cx, $cy, $board, $colsx, $colsy, $ofsleft, $ofst } } + +/** + * Make board ladders + * + * @param $im + * @param $dir + * @param $cx + * @param $s + * @param $colsx + * @param $colsy + * @param $ofsleft + * @param $ofstop + */ function makeboardl( $im, $dir, $cx, $cy, $s, $colsx, $colsy, $ofsleft, $ofstop) { $pos = strpos( $s, '-'); $from = substr( $s, 0, $pos); @@ -160,6 +204,19 @@ function makeboardl( $im, $dir, $cx, $cy, $s, $colsx, $colsy, $ofsleft, $ofstop) } } +/** + * Make board snakes + * + * @param $im + * @param $dit + * @param $cx + * @param $cy + * @param $s + * @param $colsx + * @param $colsy + * @param $ofsleft + * @param $ofstop + */ function makeboards( $im, $dir, $cx, $cy, $s, $colsx, $colsy, $ofsleft, $ofstop) { $pos = strpos( $s, '-'); $from = substr( $s, 0, $pos); @@ -237,6 +294,11 @@ function makeboards( $im, $dir, $cx, $cy, $s, $colsx, $colsy, $ofsleft, $ofstop) } } +/** + * Image create from png + * + * @param $file + */ function game_imagecreatefrompng( $file) { if (file_exists( $file)) { return imagecreatefrompng( $file); @@ -245,6 +307,18 @@ function game_imagecreatefrompng( $file) { return 0; } +/** + * Show number + * + * @param $imghandle + * @param $imgnumbers + * @param $number + * @param $x1 + * @param $y1 + * @param $width + * @param $height + * @param $sizenumbers + */ function shownumber( $imghandle, $imgnumbers, $number, $x1 , $y1, $width, $height, $sizenumbers) { if ($number < 10) { $widthnumber = $sizenumbers[ 0] / 10; @@ -264,6 +338,15 @@ function shownumber( $imghandle, $imgnumbers, $number, $x1 , $y1, $width, $heigh } } +/** + * Return rotated point + * + * @param $x + * @param $y + * @param $cx + * @param $cy + * @param $a + */ function returnrotatedpoint($x, $y, $cx, $cy, $a) { // Radius using distance formula. $r = sqrt(pow(($x - $cx), 2) + pow(($y - $cy), 2)); @@ -277,6 +360,19 @@ function returnrotatedpoint($x, $y, $cx, $cy, $a) { return array("x" => $cx + $nx, "y" => $cy + $ny); } + +/** + * Print ladder + * + * @param $im + * @param $file + * @param $x + * @param $y + * @param $width + * @param $height + * @param $cellx + * @param $celly + */ function game_printladder( $im, $file, $x, $y, $width, $height, $cellx, $celly) { $color = imagecolorallocate($im, 0, 0, 255); $x2 = $x + $width - $cellx / 2; @@ -294,6 +390,18 @@ function game_printladder( $im, $file, $x, $y, $width, $height, $cellx, $celly) imageline( $im, $x2, $y2, $a[ 'x'], $a[ 'y'], $color); } +/** + * Print snake + * + * @param $im + * @param $file + * @param $x + * @param $y + * @param $width + * @param $height + * @param $cellx + * @param $celly + */ function game_printsnake( $im, $file, $x, $y, $width, $height, $cellx, $celly) { $color = imagecolorallocate($im, 0, 255, 0); $x2 = $x + $width - $cellx / 2; diff --git a/sudoku/class.Sudoku.php b/sudoku/class.Sudoku.php index e7dcc6f..910e74c 100644 --- a/sudoku/class.Sudoku.php +++ b/sudoku/class.Sudoku.php @@ -70,7 +70,6 @@ defined('MOODLE_INTERNAL') || die(); * @author Dick Munroe * @copyright copyright @ 2005 by Dick Munroe, Cottage Software Works, Inc. * @license http://www.csworks.com/publications/ModifiedNetBSD.html - * @package Sudoku */ /** @@ -82,7 +81,8 @@ defined('MOODLE_INTERNAL') || die(); */ class objects { /** - * @desc Are two array's equal (have the same contents). + * Are two array's equal (have the same contents). + * * @param array * @param array * @return boolean @@ -121,7 +121,8 @@ class objects { } /** - * @desc Debugging output interface. + * Debugging output interface. + * * @param mixed $theValue The "thing" to be pretty printed. * @param boolean $theHTMLFlag True if the output will be seen in a browser, false otherwise. */ @@ -150,7 +151,8 @@ class cell extends objects { protected $applied = false; /** - * @desc Constructor + * Constructor + * * @param integer $r row address of this cell (not used, primarily for debugging purposes). * @param integer $c column address of this cell (ditto). * @param integer $nStates The number of states each cell can have. Looking forward to @@ -167,9 +169,8 @@ class cell extends objects { } /** - * @desc This cell has been "applied", i.e., solved, to the board. + * This cell has been "applied", i.e., solved, to the board. */ - public function applied() { $this->applied = true; } @@ -178,10 +179,9 @@ class cell extends objects { * Only those cells which are not subsets of the tuple have the * contents of the tuple removed. * - * @desc apply a 23Tuple to a cell. + * apply a 23Tuple to a cell. * @param array $aTuple the tuple to be eliminated. */ - public function apply23tuple($atuple) { if (is_array($this->state)) { $xxx = array_intersect($this->state, $atuple); @@ -198,7 +198,7 @@ class cell extends objects { /** * For more details on the pair tuple algorithm, see RCS::_pairSolution. * - * @desc Remove all values in the tuple, but only if the cell is a superset. + * Remove all values in the tuple, but only if the cell is a superset. * @param array A tuple to be eliminated from the cell's state. */ public function applytuple($atuple) { @@ -212,7 +212,8 @@ class cell extends objects { } /** - * @desc Return the string representation of the cell. + * Return the string representation of the cell. + * * @param boolean $theFlag true if the intermediate states of the cell are to be visible. * @return string */ @@ -229,11 +230,11 @@ class cell extends objects { } /* + * Assert pending solution. * Used to make sure that solved positions show up at print time. * The value is used as a candidate for "slicing and dicing" by elimination in * Sudoku::_newSolvedPosition. * - * @desc Assert pending solution. * @param integer $value The value for the solved position. */ public function flagsolvedposition($value) { @@ -241,7 +242,8 @@ class cell extends objects { } /* - * @desc return the state of a cell. + * return the state of a cell. + * * @return mixed Either solved state or array of state pending solution. */ public function &getstate() { @@ -249,7 +251,8 @@ class cell extends objects { } /* - * @desc Has the state of this cell been applied to the board. + * Has the state of this cell been applied to the board. + * * @return boolean True if it has, false otherwise. Implies that IsSolved is true as well. */ public function isapplied() { @@ -257,7 +260,8 @@ class cell extends objects { } /* - * @desc Has this cell been solved? + * Has this cell been solved? + * * @return boolean True if this cell has hit a single state. */ public function issolved() { @@ -265,10 +269,10 @@ class cell extends objects { } /* - * This is used primarily by the pretty printer, but has other applications - * in the code. + * This is used primarily by the pretty printer, but has other applications in the code. + * + * Return information about the state of a cell. * - * @desc Return information about the state of a cell. * @return integer 0 => the cell has been solved. * 1 => the cell has been solved but not seen a solved. * 2 => the cell has not been solved. @@ -286,12 +290,13 @@ class cell extends objects { } /* + * Eliminate one or more values from the state information of the cell. + * * This is the negative inference of Sudoku. By eliminating values the * cells approach solutions. Once a cell has been completely eliminated, * the value causing the complete elimination must be the solution and the * cell is promoted into the solved state. * - * @desc Eliminate one or more values from the state information of the cell. * @param mixed The value or values to be removed from the cell state. * @return boolean True if the cell state was modified, false otherwise. */ @@ -322,7 +327,9 @@ class cell extends objects { /** * The individual row column or square on the Sudoku board. * - * @package Sudoku + * package Sudoku + * @copyright 2007 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class rcs extends ObjectS { protected $theindex; @@ -334,15 +341,14 @@ class rcs extends ObjectS { protected $thetag = ""; /** - * This - * @desc Constructor + * Constructor + * * @param string $theTag "Row", "Column", "Square", used primarily in debugging. * @param integer $theIndex 1..9, where is this on the board. Square are numbered top * left, ending bottom right * @param ObjectS $a1..9 of class Cell. The cells comprising this entity. This interface is what * limts things to 9x9 Sudoku currently. */ - public function init($thetag, $theindex, &$a1, &$a2, &$a3, &$a4, &$a5, &$a6, &$a7, &$a8, &$a9) { $this->thetag = $thetag; $this->theindex = $theindex; @@ -366,10 +372,8 @@ class rcs extends ObjectS { * three cells. I'm pretty sure that this is a general rule, but for * 9x9 Sudoku, they probably aren't of interested. * - * @desc * @return boolean True if a 23 solution exists and has been applied. */ - public function _23solution() { $thecounts = array(); $thetuples = array(); @@ -433,11 +437,11 @@ class rcs extends ObjectS { } /** - * @desc apply a tuple to exclude items from within the row/column/square. + * apply a tuple to exclude items from within the row/column/square. + * * @param array $aTuple the tuple to be excluded. * @return boolean true if anything changes. */ - protected function _applytuple(&$atuple) { $thereturn = false; @@ -449,6 +453,8 @@ class rcs extends ObjectS { } /** + * Calculate the coupling for a cell within the row/column/square. + * * This is a placeholder to be overridden to calculate the "coupling" for * a cell. Coupling is defined to be the sum of the sizes of the intersection * between this cell and all others in the row/column/square. This provides @@ -459,7 +465,6 @@ class rcs extends ObjectS { * available for the state of the cell. By selecting areas with the least information * the clue sets are substantially smaller than simple random placement. * - * @desc Calculate the coupling for a cell within the row/column/square. * @param integer $theRow the row coordinate on the board of the cell. * @param integer $theColumn the column coordinate on the board of the cell. * @return integer the degree of coupling between the cell and the rest of the cells @@ -470,13 +475,14 @@ class rcs extends ObjectS { } /** + * Run the inference engine for a row/column/square. + * * I think that the goal of the inference engine is to eliminate * as much "junk" state as possible on each pass. Therefore the * order of the inferences should be 23 tuple, pair, unique because * the 23 tuple allows you to eliminate 3 values (if it works), and the * pair (generally) only 2. The unique solution adds no new information. * - * @desc Run the inference engine for a row/column/square. * @param array theRow A row/column/square data structure. * @param string theType A string merged with the standard headers during * intermediate solution printing. @@ -493,9 +499,10 @@ class rcs extends ObjectS { } /** - * @desc Find all tuples with the same contents. + * Find all tuples with the same contents. + * * @param array Array of n size tuples. - * @returns array of tuples that appear the same number of times as the size of the contents + * @return array of tuples that appear the same number of times as the size of the contents */ public function _findtuples(&$thearray) { $thereturn = array(); @@ -526,7 +533,8 @@ class rcs extends ObjectS { } /** - * @desc Get a reference to the specified cell. + * Get a reference to the specified cell. + * * @return reference to ObjectS of class Cell. */ public function &getcell($i) { @@ -534,21 +542,21 @@ class rcs extends ObjectS { } /** - * @desc Get the header set by the last call to doAnInference. - * + * Get the header set by the last call to doAnInference. */ public function getheader() { return $this->theheader; } /** + * Eliminate tuple-locked alternatives. + * * Turns out if you every find a position of n squares which can only contain * the same values, then those values cannot appear elsewhere in the structure. * This is a second positive inference that provides additional negative information. * Thanks to Ghica van Emde Boas (also an author of a Sudoku class) for convincing * me that these situations really occurred. * - * @desc Eliminate tuple-locked alternatives. * @return boolean True if something changed. */ protected function _pairsolution() { @@ -563,8 +571,7 @@ class rcs extends ObjectS { unset($thecounts[1]); /* - ** Get rid of any set of counts which cannot possibly meet the - ** requirements. + ** Get rid of any set of counts which cannot possibly meet the requirements. */ $thepossibilities = $thecounts; @@ -677,7 +684,8 @@ class rcs extends ObjectS { } /* - * @desc Check to see if the RCS contains a valid state. + * Check to see if the RCS contains a valid state. + * * @return boolean True if the state of the RCS could be part of a valid * solution, false otherwise. */ @@ -722,11 +730,14 @@ class rcs extends ObjectS { /** * Row ObjectS. * - * @package Sudoku + * package Sudoku + * @copyright 2007 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class r extends rcs { /** - * @desc Constructor + * Constructor + * * @param string $theTag "Row", "Column", "Square", used primarily in debugging. * @param integer $theIndex 1..9, where is this on the board. Square are numbered top * left, ending bottom right @@ -742,8 +753,9 @@ class r extends rcs { } /** + * Heavy lifting for row/column coupling calculations. + * * @see RCS::coupling - * @desc Heavy lifting for row/column coupling calculations. * @param integer $theIndex the index of the cell within the row or column. * @return integer the "coupling coefficient" for the cell. The sum of the * sizes of the intersection between this and all other @@ -771,11 +783,14 @@ class r extends rcs { /** * The column ObjectS. * - * @package Sudoku + * package Sudoku + * @copyright 2007 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class c extends r { /** - * @desc Constructor + * Constructor + * * @param string $theTag "Row", "Column", "Square", used primarily in debugging. * @param integer $theIndex 1..9, where is this on the board. Square are numbered top * left, ending bottom right @@ -795,7 +810,9 @@ class c extends r { /** * The Square ObjectS. * - * @package Sudoku + * package Sudoku + * @copyright 2007 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class s extends rcs { /* @@ -817,7 +834,8 @@ class s extends rcs { 9 => array(1, 2, 4, 5)); /** - * @desc Constructor + * Constructor + * * @param string $theTag "Row", "Column", "Square", used primarily in debugging. * @param integer $theIndex 1..9, where is this on the board. Square are numbered top * left, ending bottom right @@ -872,88 +890,59 @@ class s extends rcs { * generating an initial state. Not guarateed, but in engineering terms * "close enough". * - * @package Sudoku - * @example ./example.php - * @example ./example1.php - * @example ./example2.php - * @example ./example3.php + * package Sudoku + * @copyright 2007 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class sudoku extends ObjectS { - /* - * An array of Cell ObjectSs, organized into rows and columns. - * - * @var array of ObjectSs of type Cell. - */ + /** @var array of ObjectSs of type Cell. */ protected $theboard = array(); - /* - * True if debugging output is to be provided during a run. - * - * @var boolean - */ + /** @var boolean True if debugging output is to be provided during a run. */ protected $thedebug = false; - /* - * An array of RCS ObjectSs, one ObjectS for each row. - * - * @var ObjectS of type R - */ + /** @var ObjectS of type R An array of RCS ObjectSs, one ObjectS for each row. */ protected $therows = array(); - /* - * An array of RCS ObjectSs, one ObjectS for each Column. - * - * @var ObjectS of type C - */ + /** @var ObjectS of type C An array of RCS ObjectSs, one ObjectS for each Column. */ private $thecolumns = array(); - /** - * An array of RCS ObjectSs, one ObjectS for each square. - * - * @var ObjectS of type S - */ + /** @var ObjectS of type S An array of RCS ObjectSs, one ObjectS for each square. */ protected $thesquares = array(); - /* - * Used during puzzle generation for debugging output. There may + /** @var integer. Used during puzzle generation for debugging output. There may * eventually be some use of theLevel to figure out where to stop * the backtrace when puzzle generation fails. - * - * @var integer. */ protected $thelevel = 0; - /* - * Used during puzzle generation to determine when the generation + /** @var integer. Used during puzzle generation to determine when the generation * will fail. Failure, in this case, means to take a LONG time. The * backtracing algorithm used in the puzzle generator will always find * a solution, it just might take a very long time. This is a way to * limit the damage before taking another guess. - * - * @var integer. */ protected $themaxiterations = 50; - /* - * Used during puzzle generation to limit the number of trys at + /** @var integer. Used during puzzle generation to limit the number of trys at * generation a puzzle in the event puzzle generation fails * (@see Suduko::$theMaxIterations). I've never seen more than * a couple of failures in a row, so this should be sufficient * to get a puzzle generated. - * - * @var integer. */ protected $thetrys = 10; - /* - * Used during puzzle generation to count the number of iterations + /** @var integer. Used during puzzle generation to count the number of iterations * during puzzle generation. It the number gets above $theMaxIterations, * puzzle generation has failed and another try is made. - * - * @var integer. */ protected $thegenerationiterations = 0; + /** + * Constructor + * + * @param $thedebug + */ public function init($thedebug = false) { $this->thedebug = $thedebug; @@ -995,7 +984,8 @@ class sudoku extends ObjectS { } /* - * @desc Apply all pending solved positions to the board. + * Apply all pending solved positions to the board. + * * @return boolean True if at least one solved position was applied, false * otherwise. */ @@ -1024,7 +1014,7 @@ class sudoku extends ObjectS { } /* - * @desc build the row/column/square structures for the board. + * build the row/column/square structures for the board. */ protected function _buildrcs() { for ($i = 1; $i <= 9; $i++) { @@ -1356,11 +1346,11 @@ class sudoku extends ObjectS { } /* + * Get the current state of the board as a string. + * * Return the contents of the board as a string of digits and blanks. Blanks * are used where the corresponding board item is an array, indicating the cell * has not yet been solved. - * - * @desc Get the current state of the board as a string. */ public function getboardasstring() { $thestring = ""; @@ -1374,6 +1364,12 @@ class sudoku extends ObjectS { return $thestring; } + /* + * Get cel + * + * @param $r + * @param $c + */ public function &getcell($r, $c) { return $this->theboard[$r][$c]; } @@ -1440,10 +1436,11 @@ class sudoku extends ObjectS { } /** + * Initialize puzzle from a string. + * * The input parameter consists of a string of 81 digits and blanks. If fewer characters * are provide, the string is padded on the right. * - * @desc Initialize puzzle from a string. * @param string $theString The initial state of each cell in the puzzle. */ public function initializepuzzlefromstring($thestring) { @@ -1459,7 +1456,8 @@ class sudoku extends ObjectS { } /* - * @desc predicate to determine if the current puzzle has been solved. + * predicate to determine if the current puzzle has been solved. + * * @return boolean true if the puzzle has been solved. */ public function issolved() { @@ -1666,6 +1664,8 @@ class sudoku extends ObjectS { } /** + * Brute force additional solutions. + * * Here there be dragons. In conversations with other Sudoku folks, I find that there ARE Sudoku with * unique solutions for which a clue set may be incomplete, i.e., does not lead to a solution. The * solution may only be found by guessing the next move. I'm of the opinion that this violates the @@ -1685,8 +1685,7 @@ class sudoku extends ObjectS { * There's a bit of bookkeeping to keep the state right when backing up, but that's pretty * straightforward and looks a lot like that of generatePuzzle. * - * @desc Brute force additional solutions. - * @returns array The clues added sufficient to solve the puzzle. + * @return array The clues added sufficient to solve the puzzle. */ public function solvebruteforce($i = 1, $j = 1) { for (; $i <= 9; $i++) { @@ -1734,7 +1733,8 @@ class sudoku extends ObjectS { } /** - * @desc Calculate the index of the square containing a specific cell. + * Calculate the index of the square containing a specific cell. + * * @param integer $theRow the row coordinate. * @param integer $theColumn the column coordinate. * @return integer the square index in the range 1..9 @@ -1796,8 +1796,8 @@ class sudoku extends ObjectS { * Extend Sudoku to generate puzzles based on templates. * * Templates are either input files or arrays containing doubles. - * - * @package Sudoku + * @copyright 2007 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class SudokuTemplates extends Sudoku { @@ -1838,7 +1838,8 @@ class SudokuTemplates extends Sudoku /** * Extend Sudoku to print all intermediate results. * - * @package Sudoku + * @copyright 2007 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class sudokuintermediatesolution extends sudoku { public function sudokuintermediateresults($thedebug = false) { @@ -1850,6 +1851,9 @@ class sudokuintermediatesolution extends sudoku { } } +/** + * make seed + */ function make_seed() { list($usec, $sec) = explode(' ', microtime()); return (float) $sec + ((float) $usec * 100000); diff --git a/sudoku/create.php b/sudoku/create.php index 9b030af..bf09592 100644 --- a/sudoku/create.php +++ b/sudoku/create.php @@ -33,6 +33,9 @@ if ($action == 'create') { showform(); } +/** + * Show form + */ function showform() { $id = required_param('id', PARAM_NUMBER); // The action. @@ -95,6 +98,8 @@ function appendsudokub() { * * @param $si * @param $sp + * + * @return the packed sudoku */ function packsudoku( $si, $sp) { $data = ''; @@ -127,6 +132,8 @@ function packsudoku( $si, $sp) { * @param $id * @param $sp * @param $level + * + * @return true if created correctly */ function create( &$si, &$sp, $level=1) { for ($i = 1; $i <= 40; $i++) { diff --git a/sudoku/play.php b/sudoku/play.php index 8bddbc8..5db2dbd 100644 --- a/sudoku/play.php +++ b/sudoku/play.php @@ -33,8 +33,8 @@ require_once( "../../lib/questionlib.php"); * @param $game * @param $attempt * @param $sudoku - * @param boolean $endofgame - * @param stdClass $context + * @param $endofgame + * @param $context */ function game_sudoku_continue( $id, $game, $attempt, $sudoku, $endofgame, $context) { global $CFG, $DB, $USER; @@ -133,9 +133,9 @@ function game_sudoku_continue( $id, $game, $attempt, $sudoku, $endofgame, $conte * @param $game * @param $attempt * @param $sudoku - * @param boolean $onlyshow - * @param boolean $showsolution - * @param stdClass $context + * @param $onlyshow + * @param $showsolution + * @param $context */ function game_sudoku_play( $id, $game, $attempt, $sudoku, $onlyshow, $showsolution, $context) { $offsetquestions = game_sudoku_compute_offsetquestions( $game->sourcemodule, $attempt, $numbers, $correctquestions); @@ -707,7 +707,8 @@ function game_sudoku_check_glossaryentries( $id, $game, $attempt, $sudoku, $fini return true; } -/**This is the last function after submiting the answers. +/** + * This is the last function after submiting the answers. * * @param $id * @param $game diff --git a/sudoku/sdd/class.SDD.php b/sudoku/sdd/class.SDD.php index 307a2cf..a20a356 100644 --- a/sudoku/sdd/class.SDD.php +++ b/sudoku/sdd/class.SDD.php @@ -30,23 +30,24 @@ defined('MOODLE_INTERNAL') || die(); +/** + * Dump structured data, i.e., Objects and Arrays, in either plain text or + * html. This is a class wrapper for a couple of utility routines that I use + * all the time. It's handier to have them as a class. + * + * @author Dick Munroe + * @copyright copyright @ by Dick Munroe, 2004 + * @license http://opensource.org/licenses/gpl-license.php GNU Public License + * @package StructuredDataDumper + */ class sdd { - /* - * HTML to be generated flag. - */ - + /** @var HTML to be generated flag. */ protected $m_htmlflag; - /* - * logging flag. - */ - + /** @var logging flag. */ protected $m_logging = false; - /* - * In memory log file. - */ - + /** @var In memory log file. */ protected $m_log = array(); /* @@ -59,7 +60,6 @@ class sdd { * @param boolean $theLoggingFlag [optional] the state of logging for * this object. By default, logging is off. */ - public function init($thehtmlflag = null, $theloggingflag = false) { if ($thehtmlflag === null) { $thehtmlflag = (!empty($_SERVER['DOCUMENT_ROOT'])); @@ -74,7 +74,6 @@ class sdd { * * @abstract */ - public function close() { } @@ -82,8 +81,8 @@ class sdd { * Dump a structured variable. * * @static - * @param mixed $theVariable the variable to be dumped. - * @param boolean $theHtmlFlag [optional] true if HTML is to be generated, + * @param mixed $thevariable the variable to be dumped. + * @param boolean $thehtmlflag [optional] true if HTML is to be generated, * false if plain text is to be generated, null (default) if * dump is to guess which to display. * @return string The data to be displayed. @@ -115,14 +114,13 @@ class sdd { /* * Dump the contents of an array. * - * @param array $theArray the array whose contents are to be displayed. + * @param array $thearray the array whose contents are to be displayed. * @param boolean $theHTMLFlag True if an HTML table is to be generated, * false otherwise. * @param string $theIndent [optional] Used by SDD::dArray during recursion * to get indenting right. * @return string The display form of the array. */ - public function darray(&$thearray, $thehtmlflag, $theindent = "") { $theoutput = array(); @@ -173,7 +171,6 @@ class sdd { * @param boolean $theHTMLFlag true if HTML is to be generated. * @return string the display form of the object. */ - public function dobject(&$theobject, $thehtmlflag) { $theobjectvars = get_object_vars($theobject); diff --git a/sudoku/sdd/class.logfile.php b/sudoku/sdd/class.logfile.php index ee9e302..b4f6ee9 100644 --- a/sudoku/sdd/class.logfile.php +++ b/sudoku/sdd/class.logfile.php @@ -32,6 +32,13 @@ defined('MOODLE_INTERNAL') || die(); require_once('SDD/class.SDD.php'); +/** + * log file + * + * @package mod_game + * @copyright 2014 Vasilis Daloukas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class logfile extends SDD { /* @@ -42,8 +49,10 @@ class logfile extends SDD { protected $m_handle; - /* + /** * Constructor + * + * @param $thefilename */ public function init($thefilename) { if (file_exists($thefilename)) { @@ -53,8 +62,10 @@ class logfile extends SDD { } } - /* - * close + /** + * Close + * + * @param $thefilename */ public function close() { fclose($this->m_handle); diff --git a/translate.php b/translate.php index 6320205..d094703 100644 --- a/translate.php +++ b/translate.php @@ -252,6 +252,13 @@ if ($ret != '') { echo ''.$ret.'
Word1Word2Translation
'; } +/** + * Returns the language file for lang + * + * @param $lang + * @param string module + * @return the path of language file + */ function getlangfile( $lang) { global $CFG; @@ -262,6 +269,12 @@ function getlangfile( $lang) { } } +/** + * Reads the language file + * + * @param $lang + * @param $header + */ function readlangfile( $lang, &$header) { $file = getlangfile( $lang); @@ -291,6 +304,13 @@ function readlangfile( $lang, &$header) { return $a; } +/** + * Split language definition for one line + * + * @param string $line + * @param string $name + * @return string $trans + */ function splitlangdefinition($line, &$name, &$trans) { $pos1 = strpos( $line, '='); if ($pos1 == 0) { @@ -317,6 +337,12 @@ function splitlangdefinition($line, &$name, &$trans) { return true; } +/** + * Read source code + * + * @param string $file + * @param $strings + */ function readsourcecode( $file, &$strings) { global $CFG; @@ -328,6 +354,13 @@ function readsourcecode( $file, &$strings) { return $strings; } +/** + * Parse line + * + * @param $strings + * @param string $line + * @param string $filename + */ function parseline( &$strings, $line, $filename) { global $CFG; @@ -379,6 +412,11 @@ function parseline( &$strings, $line, $filename) { } } +/** + * get string + * + * @param string $s + */ function gets( $s) { $s = trim( $s); if (substr( $s, 0, 1) == '"') { @@ -391,6 +429,12 @@ function gets( $s) { return $s; } +/** + * Read dir + * + * @param string $dir + * @param string $ext + */ function read_dir($dir, $ext) { if ($ext != '') { $ext = '.' .$ext; @@ -426,6 +470,17 @@ function read_dir($dir, $ext) { return $ret; } +/** + * Compute difference + * + * @param string $en + * @param string $lang + * @param $strings + * @param $langfile + * @param $sum + * @param $outdir + * @param $utranslated + */ function computediff( $en, $lang, $strings, $langname, &$sum, $outdir, &$untranslated) { global $CFG; $untranslated = '';