Skip to content
GitLab
Commit 3542c4f4 authored by Eloy Lafuente's avatar Eloy Lafuente
Browse files

MDL-32709 book: general comments and phpdocs cleanup

parent e81c01b6
Hide whitespace changes
Inline Side-by-side
mod/book/backup/moodle1/lib.php
View file @ 3542c4f4
......@@ -17,8 +17,7 @@
/**
* Provides support for the conversion of moodle1 backup to the moodle2 format
*
* @package mod
* @subpackage book
* @package mod_book
* @copyright 2011 Tõnis Tartes <t6nis20@gmail.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......
mod/book/backup/moodle2/backup_book_activity_task.class.php
View file @ 3542c4f4
......@@ -17,9 +17,8 @@
/**
* Description of book backup task
*
* @package mod
* @subpackage book
* @copyright 2010-2011 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2010-2011 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......@@ -28,10 +27,6 @@ defined('MOODLE_INTERNAL') || die;
require_once($CFG->dirroot.'/mod/book/backup/moodle2/backup_book_stepslib.php'); // Because it exists (must)
require_once($CFG->dirroot.'/mod/book/backup/moodle2/backup_book_settingslib.php'); // Because it exists (optional)
/**
* book backup task that provides all the settings and steps to perform one
* complete backup of the activity
*/
class backup_book_activity_task extends backup_activity_task {
/**
......
mod/book/backup/moodle2/backup_book_settingslib.php
View file @ 3542c4f4
......@@ -17,9 +17,8 @@
/**
* Description of book backup settings
*
* @package mod
* @subpackage book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......
mod/book/backup/moodle2/backup_book_stepslib.php
View file @ 3542c4f4
......@@ -17,16 +17,15 @@
/**
* Define all the backup steps that will be used by the backup_book_activity_task
*
* @package mod
* @subpackage book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
defined('MOODLE_INTERNAL') || die;
/**
* Define the complete book structure for backup, with file and id annotations
* Structure step to backup one book activity
*/
class backup_book_activity_structure_step extends backup_activity_structure_step {
......
mod/book/backup/moodle2/restore_book_activity_task.class.php
View file @ 3542c4f4
......@@ -15,11 +15,10 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Define all the restore tasks
* Description of book restore task
*
* @package mod
* @subpackage book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......@@ -27,10 +26,6 @@ defined('MOODLE_INTERNAL') || die();
require_once($CFG->dirroot . '/mod/book/backup/moodle2/restore_book_stepslib.php'); // Because it exists (must)
/**
* book restore task that provides all the settings and steps to perform one
* complete restore of the activity
*/
class restore_book_activity_task extends restore_activity_task {
/**
......
mod/book/backup/moodle2/restore_book_stepslib.php
View file @ 3542c4f4
......@@ -17,9 +17,9 @@
/**
* Define all the restore steps that will be used by the restore_book_activity_task
*
* @package mod
* @package mod_book
* @subpackage book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......@@ -39,6 +39,10 @@ class restore_book_activity_structure_step extends restore_activity_structure_st
return $this->prepare_activity_structure($paths);
}
/**
* Process book tag information
* @param array $data information
*/
protected function process_book($data) {
global $DB;
......@@ -50,6 +54,10 @@ class restore_book_activity_structure_step extends restore_activity_structure_st
$this->apply_activity_instance($newitemid);
}
/**
* Process chapter tag information
* @param array $data information
*/
protected function process_book_chapter($data) {
global $DB;
......
mod/book/db/access.php
View file @ 3542c4f4
......@@ -17,12 +17,13 @@
/**
* Book module capability definition
*
* @package mod
* @subpackage book
* @copyright 2009-2012 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2009-2012 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
defined('MOODLE_INTERNAL') || die();
$capabilities = array(
'mod/book:addinstance' => array(
......
mod/book/db/log.php
View file @ 3542c4f4
......@@ -15,11 +15,10 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Definition of log events
* Book module log events definition
*
* @package mod
* @subpackage book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......
mod/book/db/subplugins.php
View file @ 3542c4f4
......@@ -15,10 +15,9 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Book subplugin types declaration
* Book module subplugin types declaration
*
* @package mod
* @subpackage book
* @package mod_book
* @copyright 2011 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......@@ -26,5 +25,5 @@
defined('MOODLE_INTERNAL') || die();
$subplugins = array(
'booktool' => 'mod/book/tool',
);
'booktool' => 'mod/book/tool',
);
mod/book/db/upgrade.php
View file @ 3542c4f4
......@@ -17,14 +17,19 @@
/**
* Book module upgrade code
*
* @package mod
* @subpackage book
* @copyright 2009-2011 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2009-2011 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
defined('MOODLE_INTERNAL') || die;
/**
* Book module upgrade task
*
* @param int $oldversion the version we are upgrading from
* @return bool always true
*/
function xmldb_book_upgrade($oldversion) {
global $CFG, $DB;
......@@ -36,20 +41,20 @@ function xmldb_book_upgrade($oldversion) {
if ($oldversion < 2007052001) {
/// Changing type of field importsrc on table book_chapters to char
// Changing type of field importsrc on table book_chapters to char
$table = new xmldb_table('book_chapters');
$field = new xmldb_field('importsrc', XMLDB_TYPE_CHAR, '255', null, XMLDB_NOTNULL, null, null, 'timemodified');
/// Launch change of type for field importsrc
// Launch change of type for field importsrc
$dbman->change_field_type($table, $field);
upgrade_mod_savepoint(true, 2007052001, 'book');
}
//===== 1.9.0 upgrade line ======//
// 1.9.0 upgrade line.
if ($oldversion < 2010120801) {
// Rename field summary on table book to intro
// Rename field summary on table book to intro
$table = new xmldb_table('book');
$field = new xmldb_field('summary', XMLDB_TYPE_TEXT, 'small', null, null, null, null, 'name');
......@@ -63,7 +68,7 @@ function xmldb_book_upgrade($oldversion) {
}
if ($oldversion < 2010120802) {
// Rename field summary on table book to intro
// Rename field summary on table book to intro
$table = new xmldb_table('book');
$field = new xmldb_field('intro', XMLDB_TYPE_TEXT, 'big', null, null, null, null, 'name');
......@@ -84,7 +89,7 @@ function xmldb_book_upgrade($oldversion) {
$dbman->add_field($table, $field);
}
// conditionally migrate to html format in intro
// Conditionally migrate to html format in intro
if ($CFG->texteditors !== 'textarea') {
$rs = $DB->get_recordset('book', array('introformat'=>FORMAT_MOODLE), '', 'id,intro,introformat');
foreach ($rs as $b) {
......
mod/book/db/upgradelib.php
View file @ 3542c4f4
......@@ -15,11 +15,10 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Resource module upgrade related helper functions
* Book module upgrade related helper functions
*
* @package mod
* @subpackage book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2010 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......@@ -73,7 +72,7 @@ function mod_book_migrate_moddata_dir_to_legacy($book, $context, $path) {
$filename = clean_param($item->getFilename(), PARAM_FILE);
if ($filename === '') {
//unsupported chars, sorry
// unsupported chars, sorry
unset($item); // release file handle
continue;
}
......@@ -94,7 +93,7 @@ function mod_book_migrate_moddata_dir_to_legacy($book, $context, $path) {
@unlink($oldpathname);
} else {
//migrate recursively all subdirectories
// migrate recursively all subdirectories
$oldpathname = $base.$item->getFilename().'/';
$subpath = $path.$item->getFilename().'/';
unset($item); // release file handle
......@@ -102,7 +101,7 @@ function mod_book_migrate_moddata_dir_to_legacy($book, $context, $path) {
@rmdir($oldpathname); // deletes dir if empty
}
}
unset($items); //release file handles
unset($items); // release file handles
}
/**
......@@ -130,14 +129,15 @@ function mod_book_migrate_all_areas() {
/**
* Migrate one area, this should be probably part of moodle core...
* @param $record
* @param $field
* @param $table
* @param $courseid
* @param $context
* @param $component
* @param $filearea
* @param $itemid
*
* @param stdClass $record object to migrate files (book, chapter)
* @param string $field field in the record we are going to migrate
* @param string $table DB table containing the information to migrate
* @param int $courseid id of the course the book module belongs to
* @param context_module $context context of the book module
* @param string $component component to be used for the migrated files
* @param string $filearea filearea to be used for the migrated files
* @param int $itemid id to be used for the migrated files
* @return void
*/
function mod_book_migrate_area($record, $field, $table, $courseid, $context, $component, $filearea, $itemid) {
......
mod/book/delete.php
View file @ 3542c4f4
......@@ -17,9 +17,8 @@
/**
* Delete book chapter
*
* @package mod
* @subpackage book
* @copyright 2004-2011 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2004-2011 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......@@ -45,15 +44,15 @@ $PAGE->set_url('/mod/book/delete.php', array('id'=>$id, 'chapterid'=>$chapterid)
$chapter = $DB->get_record('book_chapters', array('id'=>$chapterid, 'bookid'=>$book->id), '*', MUST_EXIST);
///header and strings
// Header and strings.
$PAGE->set_title(format_string($book->name));
$PAGE->add_body_class('mod_book');
$PAGE->set_heading(format_string($course->fullname));
///form processing
// Form processing.
if ($confirm) { // the operation was confirmed.
$fs = get_file_storage();
if (!$chapter->subchapter) { //delete all its subchapters if any
if (!$chapter->subchapter) { // Delete all its sub-chapters if any
$chapters = $DB->get_records('book_chapters', array('bookid'=>$book->id), 'pagenum', 'id, subchapter');
$found = false;
foreach($chapters as $ch) {
......@@ -73,7 +72,7 @@ if ($confirm) { // the operation was confirmed.
add_to_log($course->id, 'course', 'update mod', '../mod/book/view.php?id='.$cm->id, 'book '.$book->id);
add_to_log($course->id, 'book', 'update', 'view.php?id='.$cm->id, $book->id, $cm->id);
book_preload_chapters($book); //fix structure
book_preload_chapters($book); // Fix structure.
$DB->set_field('book', 'revision', $book->revision+1, array('id'=>$book->id));
redirect('view.php?id='.$cm->id);
......@@ -81,11 +80,11 @@ if ($confirm) { // the operation was confirmed.
echo $OUTPUT->header();
// the operation has not been confirmed yet so ask the user to do so
// The operation has not been confirmed yet so ask the user to do so.
if ($chapter->subchapter) {
$strconfirm = get_string('confchapterdelete','mod_book');
$strconfirm = get_string('confchapterdelete', 'mod_book');
} else {
$strconfirm = get_string('confchapterdeleteall','mod_book');
$strconfirm = get_string('confchapterdeleteall', 'mod_book');
}
echo '<br />';
$continue = new moodle_url('/mod/book/delete.php', array('id'=>$cm->id, 'chapterid'=>$chapter->id, 'confirm'=>1));
......
mod/book/edit.php
View file @ 3542c4f4
......@@ -17,9 +17,8 @@
/**
* Edit book chapter
*
* @package mod
* @subpackage book
* @copyright 2004-2011 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2004-2011 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......@@ -42,7 +41,7 @@ $context = get_context_instance(CONTEXT_MODULE, $cm->id);
require_capability('mod/book:edit', $context);
$PAGE->set_url('/mod/book/edit.php', array('cmid'=>$cmid, 'id'=>$chapterid, 'pagenum'=>$pagenum, 'subchapter'=>$subchapter));
$PAGE->set_pagelayout('admin'); //this is a bloody hack!
$PAGE->set_pagelayout('admin'); // TODO: Something. This is a bloody hack!
if ($chapterid) {
$chapter = $DB->get_record('book_chapters', array('id'=>$chapterid, 'bookid'=>$book->id), '*', MUST_EXIST);
......@@ -59,7 +58,7 @@ $chapter = file_prepare_standard_editor($chapter, 'content', $options, $context,
$mform = new book_chapter_edit_form(null, array('chapter'=>$chapter, 'options'=>$options));
/// If data submitted, then process and store.
// If data submitted, then process and store.
if ($mform->is_cancelled()) {
if (empty($chapter->id)) {
redirect("view.php?id=$cm->id");
......@@ -78,7 +77,7 @@ if ($mform->is_cancelled()) {
add_to_log($course->id, 'book', 'update', 'view.php?id='.$cm->id.'&chapterid='.$data->id, $book->id, $cm->id);
} else {
/// adding new chapter
// adding new chapter
$data->bookid = $book->id;
$data->hidden = 0;
$data->timecreated = time();
......@@ -108,7 +107,7 @@ if ($mform->is_cancelled()) {
redirect("view.php?id=$cm->id&chapterid=$data->id");
}
/// Otherwise fill and print the form.
// Otherwise fill and print the form.
$PAGE->set_title(format_string($book->name));
$PAGE->add_body_class('mod_book');
$PAGE->set_heading(format_string($course->fullname));
......
mod/book/edit_form.php
View file @ 3542c4f4
......@@ -17,9 +17,8 @@
/**
* Chapter edit form
*
* @package mod
* @subpackage book
* @copyright 2004-2010 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2004-2010 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......@@ -58,7 +57,6 @@ class book_chapter_edit_form extends moodleform {
$mform->addElement('hidden', 'pagenum');
$mform->setType('pagenum', PARAM_INT);
$this->add_action_buttons(true);
// set the defaults
......
mod/book/index.php
View file @ 3542c4f4
......@@ -17,16 +17,15 @@
/**
* This page lists all the instances of book in a particular course
*
* @package mod
* @subpackage book
* @copyright 2004-2011 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2004-2011 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
require(dirname(__FILE__).'/../../config.php');
require_once(dirname(__FILE__).'/locallib.php');
$id = required_param('id', PARAM_INT); // Course Module ID
$id = required_param('id', PARAM_INT); // Course ID.
$course = $DB->get_record('course', array('id'=>$id), '*', MUST_EXIST);
......@@ -35,7 +34,7 @@ unset($id);
require_course_login($course, true);
$PAGE->set_pagelayout('incourse');
/// Get all required strings
// Get all required strings
$strbooks = get_string('modulenameplural', 'mod_book');
$strbook = get_string('modulename', 'mod_book');
$strsectionname = get_string('sectionname', 'format_'.$course->format);
......@@ -51,7 +50,7 @@ echo $OUTPUT->header();
add_to_log($course->id, 'book', 'view all', 'index.php?id='.$course->id, '');
/// Get all the appropriate data
// Get all the appropriate data
if (!$books = get_all_instances_in_course('book', $course)) {
notice(get_string('thereareno', 'moodle', $strbooks), "$CFG->wwwroot/course/view.php?id=$course->id");
die;
......
mod/book/lang/en/book.php
View file @ 3542c4f4
......@@ -17,9 +17,8 @@
/**
* Book module language strings
*
* @package mod
* @subpackage book
* @copyright 2004-2012 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2004-2012 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......
mod/book/lib.php
View file @ 3542c4f4
......@@ -17,9 +17,8 @@
/**
* Book module core interaction API
*
* @package mod
* @subpackage book
* @copyright 2004-2011 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2004-2011 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......@@ -33,10 +32,12 @@ function book_get_numbering_types() {
global $CFG; // required for the include
require_once(dirname(__FILE__).'/locallib.php');
return array (BOOK_NUM_NONE => get_string('numbering0', 'mod_book'),
BOOK_NUM_NUMBERS => get_string('numbering1', 'mod_book'),
BOOK_NUM_BULLETS => get_string('numbering2', 'mod_book'),
BOOK_NUM_INDENTED => get_string('numbering3', 'mod_book') );
return array (
BOOK_NUM_NONE => get_string('numbering0', 'mod_book'),
BOOK_NUM_NUMBERS => get_string('numbering1', 'mod_book'),
BOOK_NUM_BULLETS => get_string('numbering2', 'mod_book'),
BOOK_NUM_INDENTED => get_string('numbering3', 'mod_book')
);
}
/**
......@@ -144,10 +145,10 @@ function book_user_outline($course, $user, $mod, $book) {
* Print a detailed representation of what a user has done with
* a given particular instance of this module, for user activity reports.
*
* @param $course
* @param $user
* @param $mod
* @param $book
* @param stdClass $course
* @param stdClass $user
* @param stdClass $mod
* @param stdClass $book
* @return bool
*/
function book_user_complete($course, $user, $mod, $book) {
......@@ -157,13 +158,13 @@ function book_user_complete($course, $user, $mod, $book) {
/**
* Given a course and a time, this module should find recent activity
* that has occurred in book activities and print it out.
* Return true if there was output, or false is there was none.
* @param $course
* @param $isteacher
* @param $timestart
* @return bool
*
* @param stdClass $course
* @param bool $viewfullnames
* @param int $timestart
* @return bool true if there was output, or false is there was none
*/
function book_print_recent_activity($course, $isteacher, $timestart) {
function book_print_recent_activity($course, $viewfullnames, $timestart) {
return false; // True if anything was printed, otherwise false
}
......@@ -179,18 +180,25 @@ function book_cron () {
/**
* No grading in book.
*
* @param $bookid
* @param int $bookid
* @return null
*/
function book_grades($bookid) {
return null;
}
/**
* Returns the users with data in one book
*
* @todo deprecated - to be deleted in 2.2
* @param int $bookid
* @return array
*/
function book_get_participants($bookid) {
//Must return an array of user records (all data) who are participants
//for a given instance of book. Must include every user involved
//in the instance, independent of his role (student, teacher, admin...)
//See other modules as example.
// Must return an array of user records (all data) who are participants
// for a given instance of book. Must include every user involved
// in the instance, independent of his role (student, teacher, admin...)
// See other modules as example.
return false;
}
......@@ -201,8 +209,8 @@ function book_get_participants($bookid) {
* modified if necessary. See book, glossary or journal modules
* as reference.
*
* @param $bookid int
* @param $scaleid int
* @param int $bookid
* @param int $scaleid
* @return boolean True if the scale is used by any journal
*/
function book_scale_used($bookid,$scaleid) {
......@@ -214,8 +222,8 @@ function book_scale_used($bookid,$scaleid) {
*
* This is used to find out if scale used anywhere
*
* @param $scaleid int
* @return boolean True if the scale is used by any journal
* @param int $scaleid
* @return bool true if the scale is used by any book
*/
function book_scale_used_anywhere($scaleid) {
return false;
......@@ -380,7 +388,7 @@ function book_get_file_info($browser, $areas, $course, $cm, $context, $filearea,
require_once("$CFG->dirroot/mod/book/locallib.php");
if (is_null($itemid)) {
return new book_file_info($browser, $course, $cm, $context, $areas, $filearea, $itemid);
return new book_file_info($browser, $course, $cm, $context, $areas, $filearea);
}
$fs = get_file_storage();
......
mod/book/locallib.php
View file @ 3542c4f4
......@@ -17,9 +17,8 @@
/**
* Book module local lib functions
*
* @package mod
* @subpackage book
* @copyright 2010-2011 Petr Skoda {@link http://skodak.org}
* @package mod_book
* @copyright 2010-2011 Petr Skoda {@link http://skodak.org}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
......@@ -124,6 +123,15 @@ function book_preload_chapters($book) {
return $chapters;
}
/**
* Returns the title for a given chapter
*
* @param int $chid
* @param array $chapters
* @param stdClass $book
* @param context_module $context
* @return string
*/
function book_get_chapter_title($chid, $chapters, $book, $context) {
$ch = $chapters[$chid];
$title = trim(format_string($ch->title, true, array('context'=>$context)));
......@@ -165,6 +173,15 @@ function book_log($str1, $str2, $level = 0) {
}
}
/**