MDL-30989 portfolio: updated portfolio phpdocs.
authorRossiani Wijaya <rwijaya@moodle.com>
Mon, 30 Jan 2012 07:37:46 +0000 (15:37 +0800)
committerRossiani Wijaya <rwijaya@moodle.com>
Mon, 30 Jan 2012 07:37:46 +0000 (15:37 +0800)
lib/portfolio/caller.php
lib/portfolio/constants.php
lib/portfolio/exceptions.php
lib/portfolio/exporter.php
lib/portfolio/formats.php
lib/portfolio/formats/leap2a/lib.php
lib/portfolio/forms.php
lib/portfolio/plugin.php
lib/portfoliolib.php
portfolio/add.php
portfolio/file.php

index 7990978..240aeb9 100644 (file)
@@ -1,86 +1,74 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * This file contains the base classes that are extended to create portfolio export functionality.
  *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * For places in moodle that want to
+ * add export functionality to subclass from {@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page}
  *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This file contains the base classes for places in moodle that want to
- * add export functionality to subclass from.
- * See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>, Martin Dougiamas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
-* base class for callers
-*
-* See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page
-* {@see also portfolio_module_caller_base}
-*/
+ * Base class for callers
+ *
+ * {@link See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page}
+ * {@see also portfolio_module_caller_base}
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 abstract class portfolio_caller_base {
 
-    /**
-    * stdclass object
-    * course that was active during the caller
-    */
+    /** @var stdClass course active during the call */
     protected $course;
 
-    /**
-    * named array of export config
-    * use{@link  set_export_config} and {@link get_export_config} to access
-    */
+    /** @var array configuration used for export. Use {@see  set_export_config} and {@see get_export_config} to access */
     protected $exportconfig = array();
 
-    /**
-    * stdclass object
-    * user currently exporting content
-    */
+    /** @var stdclass user currently exporting content */
     protected $user;
 
-    /**
-    * a reference to the exporter object
-    */
+    /** @var stdClass a reference to the exporter object */
     protected $exporter;
 
-    /**
-    * this can be overridden in subclasses constructors if they want
-    */
+    /** @var array can be optionally overridden by subclass constructors */
     protected $supportedformats;
 
-    /**
-    * set this for single file exports
-    */
+    /** @var stored_file single file exports configuration*/
     protected $singlefile;
 
-    /**
-    * set this for multi file exports
-    */
+    /** @var stored_file|object set this for multi file exports */
     protected $multifiles;
 
-    /**
-     * set this for generated-file exports
-     */
+    /** @var string set this for generated-file exports */
     protected $intendedmimetype;
 
+    /**
+     * Create portfolio_caller object
+     *
+     * @param array $callbackargs argument properties
+     */
     public function __construct($callbackargs) {
         $expected = call_user_func(array(get_class($this), 'expected_callbackargs'));
         foreach ($expected as $key => $required) {
@@ -96,51 +84,49 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * if this caller wants any additional config items
-    * they should be defined here.
-    *
-    * @param array $mform moodleform object (passed by reference) to add elements to
-    * @param object $instance subclass of portfolio_plugin_base
-    * @param integer $userid id of user exporting content
-    */
+     * If this caller wants any additional config items,
+     * they should be defined here.
+     *
+     * @param moodleform $mform passed by reference, add elements to it.
+     * @param portfolio_plugin_base $instance subclass of portfolio_plugin_base
+     */
     public function export_config_form(&$mform, $instance) {}
 
 
     /**
-    * whether this caller wants any additional
-    * config during export (eg options or metadata)
-    *
-    * @return boolean
-    */
+     * Whether this caller wants any additional
+     * config during export (eg options or metadata)
+     *
+     * @return bool
+     */
     public function has_export_config() {
         return false;
     }
 
     /**
-    * just like the moodle form validation function
-    * this is passed in the data array from the form
-    * and if a non empty array is returned, form processing will stop.
-    *
-    * @param array $data data from form.
-    * @return array keyvalue pairs - form element => error string
-    */
+     * Just like the moodle form validation function,
+     * this is passed in the data array from the form
+     * and if a non empty array is returned, form processing will stop.
+     *
+     * @param array $data data from form.
+     */
     public function export_config_validation($data) {}
 
     /**
-    * how long does this reasonably expect to take..
-    * should we offer the user the option to wait..
-    * this is deliberately nonstatic so it can take filesize into account
-    * the portfolio plugin can override this.
-    * (so for example even if a huge file is being sent,
-    * the download portfolio plugin doesn't care )
-    *
-    * @return string (see PORTFOLIO_TIME_* constants)
-    */
+     * How long does this reasonably expect to take..
+     * Should we offer the user the option to wait..?
+     * This is deliberately nonstatic so it can take filesize into account
+     * the portfolio plugin can override this.
+     * (so for example even if a huge file is being sent,
+     * the download portfolio plugin doesn't care )
+     */
     public abstract function expected_time();
 
     /**
-    * helper method to calculate expected time for multi or single file exports
-    */
+     * Helper method to calculate expected time for multi or single file exports
+     *
+     * @return string file time expectation
+     */
     public function expected_time_file() {
         if ($this->multifiles) {
             return portfolio_expected_time_file($this->multifiles);
@@ -152,25 +138,20 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * used for displaying the navigation during the export screens.
-    *
-    * this function must be implemented, but can really return anything.
-    * an Exporting.. string will be added on the end.
-    * @return array of $extranav and $cm
-    *
-    * to pass to build_navigation
-    *
-    */
+     * Function to build navigation
+     */
     public abstract function get_navigation();
 
     /**
-    *
-    */
+     * Helper function to get sha1
+     */
     public abstract function get_sha1();
 
     /**
-    * helper function to calculate the sha1 for multi or single file exports
-    */
+     * Helper function to calculate the sha1 for multi or single file exports
+     *
+     * @return string sha1 file exports
+     */
     public function get_sha1_file() {
         if (empty($this->singlefile) && empty($this->multifiles)) {
             throw new portfolio_caller_exception('invalidsha1file', 'portfolio', $this->get_return_url());
@@ -186,11 +167,15 @@ abstract class portfolio_caller_base {
         return sha1(implode('', $sha1s));
     }
 
-    /*
-    * generic getter for properties belonging to this instance
-    * <b>outside</b> the subclasses
-    * like name, visible etc.
-    */
+    /**
+     * Generic getter for properties belonging to this instance
+     * <b>outside</b> the subclasses
+     * like name, visible etc.
+     *
+     * @param string $field property's name
+     * @return mixed
+     * @throws portfolio_export_exception
+     */
     public function get($field) {
         if (property_exists($this, $field)) {
             return $this->{$field};
@@ -200,11 +185,15 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * generic setter for properties belonging to this instance
-    * <b>outside</b> the subclass
-    * like name, visible, etc.
-    *
-    */
+     * Generic setter for properties belonging to this instance
+     * <b>outside</b> the subclass
+     * like name, visible, etc.
+     *
+     * @param string $field property's name
+     * @param mixed $value property's value
+     * @return bool
+     * @throws moodle_exception
+     */
     public final function set($field, &$value) {
         if (property_exists($this, $field)) {
             $this->{$field} =& $value;
@@ -216,12 +205,12 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * stores the config generated at export time.
-    * subclasses can retrieve values using
-    * {@link get_export_config}
-    *
-    * @param array $config formdata
-    */
+     * Stores the config generated at export time.
+     * Subclasses can retrieve values using
+     * {@see get_export_config}
+     *
+     * @param array $config formdata
+     */
     public final function set_export_config($config) {
         $allowed = array_merge(
             array('wait', 'hidewait', 'format', 'hideformat'),
@@ -237,11 +226,12 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * returns a particular export config value.
-    * subclasses shouldn't need to override this
-    *
-    * @param string key the config item to fetch
-    */
+     * Returns a particular export config value.
+     * Subclasses shouldn't need to override this
+     *
+     * @param string $key the config item to fetch
+     * @return null|mixed of export configuration
+     */
     public final function get_export_config($key) {
         $allowed = array_merge(
             array('wait', 'hidewait', 'format', 'hideformat'),
@@ -258,47 +248,47 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * Similar to the other allowed_config functions
-    * if you need export config, you must provide
-    * a list of what the fields are.
-    *
-    * even if you want to store stuff during export
-    * without displaying a form to the user,
-    * you can use this.
-    *
-    * @return array array of allowed keys
-    */
+     * Similar to the other allowed_config functions
+     * if you need export config, you must provide
+     * a list of what the fields are.
+     * Even if you want to store stuff during export
+     * without displaying a form to the user,
+     * you can use this.
+     *
+     * @return array array of allowed keys
+     */
     public function get_allowed_export_config() {
         return array();
     }
 
     /**
-    * after the user submits their config
-    * they're given a confirm screen
-    * summarising what they've chosen.
-    *
-    * this function should return a table of nice strings => values
-    * of what they've chosen
-    * to be displayed in a table.
-    *
-    * @return array array of config items.
-    */
+     * After the user submits their config,
+     * they're given a confirm screen
+     * summarising what they've chosen.
+     * This function should return a table of nice strings => values
+     * of what they've chosen
+     * to be displayed in a table.
+     *
+     * @return bool
+     */
     public function get_export_summary() {
         return false;
     }
 
     /**
-    * called before the portfolio plugin gets control
-    * this function should copy all the files it wants to
-    * the temporary directory, using {@see copy_existing_file}
-    * or {@see write_new_file}
-    */
+     * Called before the portfolio plugin gets control.
+     * This function should copy all the files it wants to
+     * the temporary directory, using {@see copy_existing_file}
+     * or {@see write_new_file}
+     */
     public abstract function prepare_package();
 
     /**
-    * helper function to copy files into the temp area
-    * for single or multi file exports.
-    */
+     * Helper function to copy files into the temp area
+     * for single or multi file exports.
+     *
+     * @return stored_file|bool
+     */
     public function prepare_package_file() {
         if (empty($this->singlefile) && empty($this->multifiles)) {
             throw new portfolio_caller_exception('invalidpreparepackagefile', 'portfolio', $this->get_return_url());
@@ -312,15 +302,10 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * array of formats this caller supports
-    * the intersection of what this function returns
-    * and what the selected portfolio plugin supports
-    * will be used
-    * use the constants PORTFOLIO_FORMAT_*
-    *
-    * @return array list of formats
-    *
-    */
+     * Array of formats this caller supports.
+     *
+     * @return array list of formats
+     */
     public final function supported_formats() {
         $basic = $this->base_supported_formats();
         if (empty($this->supportedformats)) {
@@ -334,45 +319,51 @@ abstract class portfolio_caller_base {
         return portfolio_most_specific_formats($specific, $basic);
     }
 
+    /**
+     * Base supported formats
+     *
+     * @throws coding_exception
+     */
     public static function base_supported_formats() {
         throw new coding_exception('base_supported_formats() method needs to be overridden in each subclass of portfolio_caller_base');
     }
 
     /**
-    * this is the "return to where you were" url
-    *
-    * @return string url
-    */
+     * This is the "return to where you were" url
+     */
     public abstract function get_return_url();
 
     /**
-    * callback to do whatever capability checks required
-    * in the caller (called during the export process
-    */
+     * Callback to do whatever capability checks required
+     * in the caller (called during the export process
+     */
     public abstract function check_permissions();
 
     /**
-    * nice name to display to the user about this caller location
-    */
+     * Clean name to display to the user about this caller location
+     */
     public static function display_name() {
         throw new coding_exception('display_name() method needs to be overridden in each subclass of portfolio_caller_base');
     }
 
     /**
-    * return a string to put at the header summarising this export
-    * by default, just the display name (usually just 'assignment' or something unhelpful
-    *
-    * @return string
-    */
+     * Return a string to put at the header summarising this export.
+     * By default, it just display the name (usually just 'assignment' or something unhelpful
+     *
+     * @return string
+     */
     public function heading_summary() {
         return get_string('exportingcontentfrom', 'portfolio', $this->display_name());
     }
 
+    /**
+     * Load data
+     */
     public abstract function load_data();
 
     /**
-     * set up the required files for this export.
-     * this supports either passing files directly
+     * Set up the required files for this export.
+     * This supports either passing files directly
      * or passing area arguments directly through
      * to the files api using file_storage::get_area_files
      *
@@ -381,12 +372,7 @@ abstract class portfolio_caller_base {
      *                   - single stored_file object
      *                   - array of file ids or stored_file objects
      *                   - null
-     * @param int    $contextid   (optional), passed to {@link see file_storage::get_area_files}
-     * @param string $component   (optional), passed to {@link see file_storage::get_area_files}
-     * @param string $filearea    (optional), passed to {@link see file_storage::get_area_files}
-     * @param int    $itemid      (optional), passed to {@link see file_storage::get_area_files}
-     * @param string $sort        (optional), passed to {@link see file_storage::get_area_files}
-     * @param bool   $includedirs (optional), passed to {@link see file_storage::get_area_files}
+     * @return void
      */
     public function set_file_and_format_data($ids=null /* ..pass arguments to area files here. */) {
         $args = func_get_args();
@@ -426,10 +412,12 @@ abstract class portfolio_caller_base {
     }
 
     /**
-     * the button-location always knows best
+     * The button-location always knows best
      * what the formats are... so it should be trusted.
      *
+     * @todo MDL-31298 - re-analyze set_formats_from_button comment
      * @param array $formats array of PORTFOLIO_FORMAT_XX
+     * @return void
      */
     public function set_formats_from_button($formats) {
         $base = $this->base_supported_formats();
@@ -445,12 +433,11 @@ abstract class portfolio_caller_base {
     }
 
     /**
-     * adds a new format to the list of supported formats.
-     * handles removing conflicting and less specific
+     * Adds a new format to the list of supported formats.
+     * This functions also handles removing conflicting and less specific
      * formats at the same time.
      *
      * @param string $format one of PORTFOLIO_FORMAT_XX
-     *
      * @return void
      */
     protected function add_format($format) {
@@ -460,6 +447,11 @@ abstract class portfolio_caller_base {
         $this->supportedformats = portfolio_most_specific_formats(array($format), $this->supportedformats);
     }
 
+    /**
+     * Gets mimetype
+     *
+     * @return string
+     */
     public function get_mimetype() {
         if ($this->singlefile instanceof stored_file) {
             return $this->singlefile->get_mimetype();
@@ -469,15 +461,13 @@ abstract class portfolio_caller_base {
     }
 
     /**
-     * array of arguments the caller expects to be passed through to it
-     * this must be keyed on the argument name, and the array value is a boolean,
+     * Array of arguments the caller expects to be passed through to it.
+     * This must be keyed on the argument name, and the array value is a boolean,
      * whether it is required, or just optional
      * eg array(
      *     id            => true,
-     *     somethingelse => false,
+     *     somethingelse => false
      * )
-     *
-     * @return array
      */
     public static function expected_callbackargs() {
         throw new coding_exception('expected_callbackargs() method needs to be overridden in each subclass of portfolio_caller_base');
@@ -485,66 +475,68 @@ abstract class portfolio_caller_base {
 
 
     /**
-     * return the context for this export. used for $PAGE->set_context
+     * Return the context for this export. used for $PAGE->set_context
      *
-     * @return stdclass
+     * @param moodle_page $PAGE global page object
      */
     public abstract function set_context($PAGE);
 }
 
 /**
-* base class for module callers
-* this just implements a few of the abstract functions
-* from portfolio_caller_base so that caller authors
-* don't need to.
-*
-* See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page
-* {@see also portfolio_caller_base}
-*/
+ * Base class for module callers.
+ * This just implements a few of the abstract functions
+ * from portfolio_caller_base so that caller authors
+ * don't need to.
+ * {@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page}
+ * {@see also portfolio_caller_base}
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 abstract class portfolio_module_caller_base extends portfolio_caller_base {
 
-    /**
-    * coursemodule object
-    * set this in the constructor like
-    * $this->cm = get_coursemodule_from_instance('forum', $this->forum->id);
-    */
+    /** @var object coursemodule object. set this in the constructor like $this->cm = get_coursemodule_from_instance('forum', $this->forum->id); */
     protected $cm;
 
-    /**
-    *
-    * int cmid
-    */
+    /** @var int cmid */
     protected $id;
 
-    /**
-    * stdclass course object
-    */
+    /** @var stdclass course object */
     protected $course;
 
     /**
-    * navigation passed to print_header
-    * override this to do something more specific than the module view page
-    */
+     * Navigation passed to print_header.
+     * Override this to do something more specific than the module view page
+     *
+     * @return array
+     */
     public function get_navigation() {
         $extranav = array('name' => $this->cm->name, 'link' => $this->get_return_url());
         return array($extranav, $this->cm);
     }
 
     /**
-    * the url to return to after export or on cancel
-    * defaults to the module 'view' page
-    * override this if it's deeper inside the module
-    */
+     * The url to return to after export or on cancel.
+     * Defaults value is set to the module 'view' page.
+     * Override this if it's deeper inside the module.
+     *
+     * @return string
+     */
     public function get_return_url() {
         global $CFG;
         return $CFG->wwwroot . '/mod/' . $this->cm->modname . '/view.php?id=' . $this->cm->id;
     }
 
     /**
-    * override the parent get function
-    * to make sure when we're asked for a course
-    * we retrieve the object from the database as needed
-    */
+     * Override the parent get function
+     * to make sure when we're asked for a course,
+     * We retrieve the object from the database as needed.
+     *
+     * @param string $key the name of get function
+     * @return stdClass
+     */
     public function get($key) {
         if ($key != 'course') {
             return parent::get($key);
@@ -557,16 +549,20 @@ abstract class portfolio_module_caller_base extends portfolio_caller_base {
     }
 
     /**
-    * return a string to put at the header summarising this export
-    * by default, just the display name and the module instance name
-    * override this to do something more specific
-    */
+     * Return a string to put at the header summarising this export.
+     * by default, this function just display the name and module instance name.
+     * Override this to do something more specific
+     *
+     * @return string
+     */
     public function heading_summary() {
         return get_string('exportingcontentfrom', 'portfolio', $this->display_name() . ': ' . $this->cm->name);
     }
 
     /**
-     * overridden to return the course module context
+     * Overridden to return the course module context
+     *
+     * @param moodle_page $PAGE global PAGE
      */
     public function set_context($PAGE) {
         $PAGE->set_cm($this->cm);
index f7565b5..04e5965 100644 (file)
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file contains all the defined constants to do with portfolios.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>, Martin Dougiamas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
-// ************************************************** //
-// EXPORT STAGE CONSTANTS
-// ************************************************** //
+//EXPORT STAGE CONSTANTS
+
 
 /**
-* display a form to the user
-* this one might not be used if neither
-* the plugin, or the caller has any config.
-*/
+ * PORTFOLIO_STAGE_CONFIG - display a form to the user this one might not be
+ *                          used if neither the plugin, or the caller has any config.
+ */
 define('PORTFOLIO_STAGE_CONFIG', 1);
 
 /**
-* summarise the form and ask for confirmation
-* if we skipped PORTFOLIO_STAGE_CONFIG,
-* just confirm the send.
-*/
+ * PORTFOLIO_STAGE_CONFIRM - summarise the form and ask for confirmation
+ *                           if we skipped PORTFOLIO_STAGE_CONFIG,
+ *                           just confirm the send.
+ */
 define('PORTFOLIO_STAGE_CONFIRM', 2);
 
 /**
-* either queue the event and skip to PORTFOLIO_STAGE_FINISHED
-* or continue to PORTFOLIO_STAGE_PACKAGE
-*/
-
+ * PORTFOLIO_STAGE_QUEUEORWAIT - either queue the event and skip to PORTFOLIO_STAGE_FINISHED
+ */
 define('PORTFOLIO_STAGE_QUEUEORWAIT', 3);
 
 /**
-* package up the various bits
-* during this stage both the caller
-* and the plugin get their package methods called
-*/
+ * PORTFOLIO_STAGE_PACKAGE - package up the various bits during this stage both the caller
+ *                           and the plugin get their package methods called
+ */
 define('PORTFOLIO_STAGE_PACKAGE', 4);
 
-/*
-* the portfolio plugin must send the file
-*/
+/**
+ * PORTFOLIO_STAGE_SEND - the portfolio plugin must send the file
+ */
 define('PORTFOLIO_STAGE_SEND', 5);
 
 /**
-* cleanup the temporary area
-*/
+ * PORTFOLIO_STAGE_CLEANUP - cleanup the temporary area
+ */
 define('PORTFOLIO_STAGE_CLEANUP', 6);
 
 /**
-* display the "finished notification"
-*/
+ * PORTFOLIO_STAGE_FINISHED - display the "finished notification"
+ */
 define('PORTFOLIO_STAGE_FINISHED', 7);
 
 
 
-// ************************************************** //
+
 // EXPORT FORMAT CONSTANTS
-// these should always correspond to a string
-// in the portfolio module, called format_{$value}
-// ************************************************** //
+// These should always correspond to a string in the portfolio module, called format_{$value}
 
 
 /**
-* file - the most basic fallback format.
-* this should always be supported
-* in remote system.s
-*/
+ * PORTFOLIO_FORMAT_FILE - the most basic fallback format. this should always be supported
+ *                         in remote system.s
+ */
 define('PORTFOLIO_FORMAT_FILE', 'file');
 
 /**
-* moodle backup - the plugin needs to be able to write a complete backup
-* the caller need to be able to export the particular XML bits to insert
-* into moodle.xml (?and the file bits if necessary)
-*/
+ * PORTFOLIO_FORMAT_MBKP - the plugin needs to be able to write a complete backup
+ *                         the caller need to be able to export the particular XML bits to insert
+ *                         into moodle.xml (?and the file bits if necessary)
+ */
 define('PORTFOLIO_FORMAT_MBKP', 'mbkp');
 
 /**
-* richhtml - like html but with attachments.
-*/
+ * PORTFOLIO_FORMAT_RICHHTML - like html but with attachments.
+ */
 define('PORTFOLIO_FORMAT_RICHHTML', 'richhtml');
 
-
 /**
-* plainhtml - a single html representation - no attachments
-*/
+ * PORTFOLIO_FORMAT_PLAINHTML - a single html representation - no attachments
+ */
 define('PORTFOLIO_FORMAT_PLAINHTML', 'plainhtml');
 
 /**
-* image - subtype of file
-*/
+ * PORTFOLIO_FORMAT_IMAGE - subtype of file
+ */
 define('PORTFOLIO_FORMAT_IMAGE', 'image');
 
 /**
-* video - subtype of file
-*/
+ * PORTFOLIO_FORMAT_VIDEO - subtype of file
+ */
 define('PORTFOLIO_FORMAT_VIDEO', 'video');
 
 /**
-* text - subtype of file
-*/
+ * PORTFOLIO_FORMAT_TEXT - subtype of file
+ */
 define('PORTFOLIO_FORMAT_TEXT', 'text');
 
 /**
-* pdf - subtype of file
-*/
+ * PORTFOLIO_FORMAT_PDF - subtype of file
+ */
 define('PORTFOLIO_FORMAT_PDF', 'pdf');
 
 /**
-* document - subtype of file
-*/
+ * PORTFOLIO_FORMAT_DOCUMENT - subtype of file
+ */
 define('PORTFOLIO_FORMAT_DOCUMENT', 'document');
 
 /**
-* document - subtype of file
-*/
+ * PORTFOLIO_FORMAT_SPREADSHEET - subtype of file
+ */
 define('PORTFOLIO_FORMAT_SPREADSHEET', 'spreadsheet');
 
 /**
-* document - subtype of file
-*/
+ * PORTFOLIO_FORMAT_PRESENTATION - subtype of file
+ */
 define('PORTFOLIO_FORMAT_PRESENTATION', 'presentation');
 
 /**
- * abstract - just used to say, "we support all these"
+ * PORTFOLIO_FORMAT_RICH - just used to say, "we support all these"
  */
 define('PORTFOLIO_FORMAT_RICH', 'rich');
 
 /**
- * leap2a http://wiki.cetis.ac.uk/LEAP_2.0
- * supported by mahara and and others
+ * PORTFOLIO_FORMAT_LEAP2A - supported by mahara and and others {http://wiki.cetis.ac.uk/LEAP_2.0}
  */
 define('PORTFOLIO_FORMAT_LEAP2A', 'leap2a');
 
-// ************************************************** //
-//  EXPORT TIME LEVELS
-// these should correspond to a string
-// in the portfolio module, called time_{$value}
-// ************************************************** //
-
+// EXPORT TIME LEVELS
+// These should correspond to a string in the portfolio module, called time_{$value}
 
 /**
-* no delay. don't even offer the user the option
-* of not waiting for the transfer
-*/
+ * PORTFOLIO_TIME_LOW - no delay. don't even offer the user the option
+ *                      of not waiting for the transfer
+ */
 define('PORTFOLIO_TIME_LOW', 'low');
 
 /**
-* a small delay. user can still easily opt to
-* watch this transfer and wait.
-*/
+ * PORTFOLIO_TIME_MODERATE - a small delay. user can still easily opt to
+ *                           watch this transfer and wait.
+ */
 define('PORTFOLIO_TIME_MODERATE', 'moderate');
 
 /**
-* slow. the user really should not be given the option
-* to choose this.
-*/
+ * PORTFOLIO_TIME_HIGH - slow. the user really should not be given the option
+ *                       to choose this.
+ */
 define('PORTFOLIO_TIME_HIGH', 'high');
 
 /**
-* very slow, or immediate transfers not supported
-*/
+ * PORTFOLIO_TIME_FORCEQUEUE - very slow, or immediate transfers not supported
+ */
 define('PORTFOLIO_TIME_FORCEQUEUE', 'queue');
 
-// ************************************************** //
-// BUTTON FORMATS
-// available ways to add the portfolio export to a page
-// ************************************************** //
+ // BUTTON FORMATS
+ // Available ways to add the portfolio export to a page
 
 /**
-* a whole form, containing a drop down menu (where necessary)
-* and a submit button
-*/
+ * PORTFOLIO_ADD_FULL_FORM - a whole form, containing a drop down menu (where necessary)
+ *                           and a submit button
+ */
 define('PORTFOLIO_ADD_FULL_FORM', 1);
 
 
 /**
-* a whole form, containing a drop down menu (where necessary)
-* but has an icon instead of a button to submit
-*/
+ * PORTFOLIO_ADD_ICON_FORM - a whole form, containing a drop down menu (where necessary)
+ *                           but has an icon instead of a button to submit
+ */
 define('PORTFOLIO_ADD_ICON_FORM', 2);
 
 /**
-* just an icon with a link around it (yuk, as will result in a long url
-* only use where necessary)
-*/
+ * PORTFOLIO_ADD_ICON_LINK - just an icon with a link around it (yuk, as will result in a long url
+ *                           only use where necessary)
+ */
 define('PORTFOLIO_ADD_ICON_LINK', 3);
 
 /**
-* just some text with a link around it (yuk, as will result in a long url
-* only use where necessary)
-*/
+ * PORTFOLIO_ADD_TEXT_LINK - just some text with a link around it (yuk, as will result in a long url
+ * only use where necessary)
+ */
 define('PORTFOLIO_ADD_TEXT_LINK', 4);
 
 /**
- * hacky way to turn the button class into a url to redirect to
- * this replaces the old portfolio_fake_add_url function
+ * PORTFOLIO_ADD_FAKE_URL - hacky way to turn the button class into a url to redirect to
+ *                          this replaces the old portfolio_fake_add_url function
  */
 define('PORTFOLIO_ADD_FAKE_URL', 5);
index d39e6d5..e6fbac6 100644 (file)
@@ -1,52 +1,59 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file contains all the portfolio exception classes.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,  Martin Dougiamas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
-* top level portfolio exception.
-* sometimes caught and rethrown as {@see portfolio_export_exception}
-*/
+ * Top level portfolio exception.
+ * Sometimes caught and re-thrown as {@see portfolio_export_exception}
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_exception extends moodle_exception {}
 
 /**
-* exception to throw during an export - will clean up session and tempdata
-*/
+ * Exception to throw during an export - will clean up session and tempdata
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_export_exception extends portfolio_exception {
 
     /**
-    * constructor.
-    * @param object $exporter instance of portfolio_exporter (will handle null case)
-    * @param string $errorcode language string key
-    * @param string $module language string module (optional, defaults to moodle)
-    * @param string $continue url to continue to (optional, defaults to wwwroot)
-    * @param mixed $a language string data (optional, defaults to  null)
-    */
+     * Constructor.
+     *
+     * @param portfolio_exporter $exporter instance of portfolio_exporter (will handle null case)
+     * @param string $errorcode language string key
+     * @param string $module language string module (optional, defaults to moodle)
+     * @param string $continue url to continue to (optional, defaults to wwwroot)
+     * @param object $a language string data (optional, defaults to  null)
+     */
     public function __construct($exporter, $errorcode, $module=null, $continue=null, $a=null) {
         global $CFG;
         // This static variable is necessary because sometimes the code below
@@ -82,23 +89,43 @@ class portfolio_export_exception extends portfolio_exception {
 }
 
 /**
-* exception for callers to throw when they have a problem.
-* usually caught and rethrown as {@see portfolio_export_exception}
-*/
+ * Exception for callers to throw when they have a problem.
+ * Usually caught and rethrown as {@see portfolio_export_exception}
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_caller_exception extends portfolio_exception {}
 
 /**
-* exception for portfolio plugins to throw when they have a problem.
-* usually caught and rethrown as {@see portfolio_export_exception}
-*/
+ * Exception for portfolio plugins to throw when they have a problem.
+ * Usually caught and rethrown as {@see portfolio_export_exception}
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_plugin_exception extends portfolio_exception {}
 
 /**
-* exception for interacting with the button class
-*/
+ * Exception for interacting with the button class
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_button_exception extends portfolio_exception {}
 
 /**
- * leap2a exception - for invalid api calls
+ * Leap2a exception - for invalid api calls
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class portfolio_format_leap2a_exception extends portfolio_exception {}
index 9a836bc..02c1b00 100644 (file)
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file contains the class definition for the exporter object.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ *            Martin Dougiamas  <http://dougiamas.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
-* The class that handles the various stages of the actual export
-* and the communication between the caller and the portfolio plugin.
-* this is stored in the database between page requests in serialized base64 encoded form
-* also contains helper methods for the plugin and caller to use (at the end of the file)
-* {@see get_base_filearea} - where to write files to
-* {@see write_new_file} - write some content to a file in the export filearea
-* {@see copy_existing_file} - copy an existing file into the export filearea
-* {@see get_tempfiles} - return list of all files in the export filearea
-*/
+ * The class that handles the various stages of the actual export
+ * and the communication between the caller and the portfolio plugin.
+ * this is stored in the database between page requests in serialized base64 encoded form
+ * also contains helper methods for the plugin and caller to use (at the end of the file)
+ * {@see get_base_filearea} - where to write files to
+ * {@see write_new_file} - write some content to a file in the export filearea
+ * {@see copy_existing_file} - copy an existing file into the export filearea
+ * {@see get_tempfiles} - return list of all files in the export filearea
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ *            Martin Dougiamas  <http://dougiamas.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_exporter {
 
-    /**
-    * the caller object used during the export
-    */
+    /** @var portfolio_caller_base the caller object used during the export */
     private $caller;
 
-    /** the portfolio plugin instanced used during the export
-    */
+    /** @var portfolio_plugin_base the portfolio plugin instanced used during the export */
     private $instance;
 
-    /**
-    * if there has been no config form displayed to the user
-    */
+    /** @var bool if there has been no config form displayed to the user */
     private $noexportconfig;
 
     /**
-    * the user currently exporting content
-    * always $USER, but more conveniently placed here
-    */
+     * @var stdClass the user currently exporting content always $USER,
+     *               but more conveniently placed here
+     */
     private $user;
 
-    /** the file to include that contains the class defintion
-    * of the portfolio instance plugin
-    * used to re-waken the object after sleep
-    */
+    /**
+     * @var string the file to include that contains the class defintion of
+     *             the portfolio instance plugin used to re-waken the object after sleep
+     */
     public $instancefile;
 
     /**
-    * the file to include that contains the class definition
-    * of the caller object
-    * used to re-waken the object after sleep
-    */
+     * @var string the file to include that contains the class definition of
+     *             the caller object used to re-waken the object after sleep
+     */
     public $callerfile;
 
-    /**
-    * the current stage of the export
-    */
+    /** @var int the current stage of the export */
     private $stage;
 
-    /**
-    * whether something (usually the portfolio plugin)
-    * has forced queuing
-    */
+    /** @var bool whether something (usually the portfolio plugin) has forced queuing */
     private $forcequeue;
 
     /**
-    * id of this export
-    * matches record in portfolio_tempdata table
-    * and used for itemid for file storage.
-    */
+     * @var int id of this export matches record in portfolio_tempdata table
+     *          and used for itemid for file storage.
+     */
     private $id;
 
-    /**
-    * array of stages that have had the portfolio plugin already steal control from them
-    */
+    /** @var array of stages that have had the portfolio plugin already steal control from them */
     private $alreadystolen;
 
     /**
-    * files that the exporter has written to this temp area
-    * keep track of this in case of duplicates within one export
-    * see MDL-16390
-    */
+     * @var stored_file files that the exporter has written to this temp area keep track of
+     *                  this in case of duplicates within one export see MDL-16390
+     */
     private $newfilehashes;
 
     /**
-    * selected exportformat
-    * this is also set in export_config in the portfolio and caller classes
-    */
+     * @var string selected exportformat this is also set in
+     *             export_config in the portfolio and caller classes
+     */
     private $format;
 
-    /**
-     * queued - this is set after the event is triggered
-     */
+    /** @var bool queued - this is set after the event is triggered */
     private $queued = false;
 
-    /**
-     * expiry time - set the first time the object is saved out
-     */
+    /** @var int expiry time - set the first time the object is saved out */
     private $expirytime;
 
     /**
-     * deleted - this is set during the cleanup routine
-     * so that subsequent save() calls can detect it
+     * @var bool deleted - this is set during the cleanup routine so
+     *           that subsequent save() calls can detect it
      */
     private $deleted = false;
 
     /**
-    * construct a new exporter for use
-    *
-    * @param portfolio_plugin_base subclass $instance portfolio instance (passed by reference)
-    * @param portfolio_caller_base subclass $caller portfolio caller (passed by reference)
-    * @param string $callerfile path to callerfile (relative to dataroot)
-    */
+     * Construct a new exporter for use
+     *
+     * @param portfolio_plugin_base $instance portfolio instance (passed by reference)
+     * @param portfolio_caller_base $caller portfolio caller (passed by reference)
+     * @param string $callerfile path to callerfile (relative to dataroot)
+     */
     public function __construct(&$instance, &$caller, $callerfile) {
         $this->instance =& $instance;
         $this->caller =& $caller;
@@ -146,11 +130,13 @@ class portfolio_exporter {
         $this->newfilehashes = array();
     }
 
-    /*
-    * generic getter for properties belonging to this instance
-    * <b>outside</b> the subclasses
-    * like name, visible etc.
-    */
+    /**
+     * Generic getter for properties belonging to this instance
+     * <b>outside</b> the subclasses like name, visible etc.
+     *
+     * @param string $field property's name
+     * @return portfolio_format|mixed
+     */
     public function get($field) {
         if ($field == 'format') {
             return portfolio_format_object($this->format);
@@ -165,10 +151,14 @@ class portfolio_exporter {
     }
 
     /**
-    * generic setter for properties belonging to this instance
-    * <b>outside</b> the subclass
-    * like name, visible, etc.
-    */
+     * Generic setter for properties belonging to this instance
+     * <b>outside</b> the subclass like name, visible, etc.
+     *
+     * @param string $field property's name
+     * @param mixed $value property's value
+     * @return bool
+     * @throws portfolio_export_exception
+     */
     public function set($field, &$value) {
         if (property_exists($this, $field)) {
             $this->{$field} =& $value;
@@ -185,23 +175,22 @@ class portfolio_exporter {
     }
 
     /**
-    * sets this export to force queued
-    * sometimes plugins need to set this randomly
-    * if an external system changes its mind
-    * about what's supported
-    */
+     * Sets this export to force queued.
+     * Sometimes plugins need to set this randomly
+     * if an external system changes its mind
+     * about what's supported
+     */
     public function set_forcequeue() {
         $this->forcequeue = true;
     }
 
     /**
-    * process the given stage calling whatever functions are necessary
-    *
-    * @param int $stage (see PORTFOLIO_STAGE_* constants)
-    * @param boolean $alreadystolen used to avoid letting plugins steal control twice.
-    *
-    * @return boolean whether or not to process the next stage. this is important as the function is called recursively.
-    */
+     * Process the given stage calling whatever functions are necessary
+     *
+     * @param int $stage (see PORTFOLIO_STAGE_* constants)
+     * @param bool $alreadystolen used to avoid letting plugins steal control twice.
+     * @return bool whether or not to process the next stage. this is important as the function is called recursively.
+     */
     public function process_stage($stage, $alreadystolen=false) {
         $this->set('stage', $stage);
         if ($alreadystolen) {
@@ -259,28 +248,28 @@ class portfolio_exporter {
     }
 
     /**
-    * helper function to return the portfolio instance
-    *
-    * @return  portfolio_plugin_base subclass
-    */
+     * Helper function to return the portfolio instance
+     *
+     * @return portfolio_plugin_base subclass
+     */
     public function instance() {
         return $this->instance;
     }
 
     /**
-    * helper function to return the caller object
-    *
-    * @return portfolio_caller_base subclass
-    */
+     * Helper function to return the caller object
+     *
+     * @return portfolio_caller_base subclass
+     */
     public function caller() {
         return $this->caller;
     }
 
     /**
-    * processes the 'config' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'config' stage of the export
+     *
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_config() {
         global $OUTPUT, $CFG;
         $pluginobj = $callerobj = null;
@@ -368,10 +357,10 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'confirm' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'confirm' stage of the export
+     *
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_confirm() {
         global $CFG, $DB, $OUTPUT;
 
@@ -433,10 +422,10 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'queueornext' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'queueornext' stage of the export
+     *
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_queueorwait() {
         $wait = $this->instance->get_export_config('wait');
         if (empty($wait)) {
@@ -448,10 +437,11 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'package' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'package' stage of the export
+     *
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     * @throws portfolio_export_exception
+     */
     public function process_stage_package() {
         // now we've agreed on a format,
         // the caller is given control to package it up however it wants
@@ -477,12 +467,12 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'cleanup' stage of the export
-    *
-    * @param boolean $pullok normally cleanup is deferred for pull plugins until after the file is requested from portfolio/file.php
-    *                        if you want to clean up earlier, pass true here (defaults to false)
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'cleanup' stage of the export
+     *
+     * @param bool $pullok normally cleanup is deferred for pull plugins until after the file is requested from portfolio/file.php
+     *                        if you want to clean up earlier, pass true here (defaults to false)
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_cleanup($pullok=false) {
         global $CFG, $DB;
 
@@ -501,10 +491,10 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'send' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'send' stage of the export
+     *
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_send() {
         // send the file
         try {
@@ -523,10 +513,11 @@ class portfolio_exporter {
     }
 
     /**
-    * log the transfer
-    * this should only be called after the file has been sent
-    * either via push, or sent from a pull request.
-    */
+     * Log the transfer
+     *
+     * this should only be called after the file has been sent
+     * either via push, or sent from a pull request.
+     */
     public function log_transfer() {
         global $DB;
         $l = array(
@@ -544,8 +535,10 @@ class portfolio_exporter {
     }
 
     /**
-     * in some cases (mahara) we need to update this after the log has been done
+     * In some cases (mahara) we need to update this after the log has been done
      * because of MDL-20872
+     *
+     * @param string $url link to be recorded to portfolio log
      */
     public function update_log_url($url) {
         global $DB;
@@ -553,10 +546,11 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'finish' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'finish' stage of the export
+     *
+     * @param bool $queued let the process to be queued
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_finished($queued=false) {
         global $OUTPUT;
         $returnurl = $this->caller->get_return_url();
@@ -578,10 +572,12 @@ class portfolio_exporter {
 
 
     /**
-    * local print header function to be reused across the export
-    *
-    * @param string $headerstring full language string
-    */
+     * Local print header function to be reused across the export
+     *
+     * @param string $headingstr full language string
+     * @param bool $summary (optional) to print summary, default is set to true
+     * @return void
+     */
     public function print_header($headingstr, $summary=true) {
         global $OUTPUT, $PAGE;
         $titlestr = get_string('exporting', 'portfolio');
@@ -609,9 +605,13 @@ class portfolio_exporter {
     }
 
     /**
-    * cancels a potfolio request and cleans up the tempdata
-    * and redirects the user back to where they started
-    */
+     * Cancels a potfolio request and cleans up the tempdata
+     * and redirects the user back to where they started
+     *
+     * @param bool $logreturn options to return to porfolio log or caller return page
+     * @return void
+     * @uses exit
+     */
     public function cancel_request($logreturn=false) {
         global $CFG;
         if (!isset($this)) {
@@ -626,8 +626,10 @@ class portfolio_exporter {
     }
 
     /**
-    * writes out the contents of this object and all its data to the portfolio_tempdata table and sets the 'id' field.
-    */
+     * Writes out the contents of this object and all its data to the portfolio_tempdata table and sets the 'id' field.
+     *
+     * @return void
+     */
     public function save() {
         global $DB;
         if (empty($this->id)) {
@@ -654,13 +656,12 @@ class portfolio_exporter {
     }
 
     /**
-    * rewakens the data from the database given the id
-    * makes sure to load the required files with the class definitions
-    *
-    * @param int $id id of data
-    *
-    * @return portfolio_exporter
-    */
+     * Rewakens the data from the database given the id.
+     * Makes sure to load the required files with the class definitions
+     *
+     * @param int $id id of data
+     * @return portfolio_exporter
+     */
     public static function rewaken_object($id) {
         global $DB, $CFG;
         require_once($CFG->libdir . '/filelib.php');
@@ -692,12 +693,13 @@ class portfolio_exporter {
     }
 
     /**
-    * helper function to create the beginnings of a file_record object
-    * to create a new file in the portfolio_temporary working directory
-    * use {@see write_new_file} or {@see copy_existing_file} externally
-    *
-    * @param string $name filename of new record
-    */
+     * Helper function to create the beginnings of a file_record object
+     * to create a new file in the portfolio_temporary working directory.
+     * Use {@see write_new_file} or {@see copy_existing_file} externally
+     *
+     * @param string $name filename of new record
+     * @return object
+     */
     private function new_file_record_base($name) {
         return (object)array_merge($this->get_base_filearea(), array(
             'filepath' => '/',
@@ -706,15 +708,12 @@ class portfolio_exporter {
     }
 
     /**
-    * verifies a rewoken object
-    *
-    * checks to make sure it belongs to the same user and session as is currently in use.
-    *
-    * @param boolean $readonly if we're reawakening this for a user to just display in the log view, don't verify the sessionkey
-    *                          when continuing transfers, you must pass false here.
-    *
-    * @throws portfolio_exception
-    */
+     * Verifies a rewoken object.
+     * Checks to make sure it belongs to the same user and session as is currently in use.
+     *
+     * @param bool $readonly if we're reawakening this for a user to just display in the log view, don't verify the sessionkey
+     * @throws portfolio_exception
+     */
     public function verify_rewaken($readonly=false) {
         global $USER, $CFG;
         if ($this->get('user')->id != $USER->id) { // make sure it belongs to the right user
@@ -735,13 +734,13 @@ class portfolio_exporter {
         }
     }
     /**
-    * copies a file from somewhere else in moodle
-    * to the portfolio temporary working directory
-    * associated with this export
-    *
-    * @param $oldfile stored_file object
-    * @return stored_file new file object
-    */
+     * Copies a file from somewhere else in moodle
+     * to the portfolio temporary working directory
+     * associated with this export
+     *
+     * @param stored_file $oldfile existing stored file object
+     * @return stored_file|bool new file object
+     */
     public function copy_existing_file($oldfile) {
         if (array_key_exists($oldfile->get_contenthash(), $this->newfilehashes)) {
             return $this->newfilehashes[$oldfile->get_contenthash()];
@@ -761,15 +760,15 @@ class portfolio_exporter {
     }
 
     /**
-    * writes out some content to a file in the
-    * portfolio temporary working directory
-    * associated with this export
-    *
-    * @param string $content content to write
-    * @param string $name filename to use
-    * @param bool $maifest whether this is the main file or an secondary file (eg attachment)
-    * @return stored_file new file object
-    */
+     * Writes out some content to a file
+     * in the portfolio temporary working directory
+     * associated with this export.
+     *
+     * @param string $content content to write
+     * @param string $name filename to use
+     * @param bool $manifest whether this is the main file or an secondary file (eg attachment)
+     * @return stored_file
+     */
     public function write_new_file($content, $name, $manifest=true) {
         $fs = get_file_storage();
         $file_record = $this->new_file_record_base($name);
@@ -780,13 +779,12 @@ class portfolio_exporter {
     }
 
     /**
-    * zips all files in the temporary directory
-    *
-    * @param string $filename name of resulting zipfile (optional, defaults to portfolio-export.zip
-    * @param string $filepath subpath in the filearea (optional, defaults to final)
-    *
-    * @return stored_file resulting stored_file object
-    */
+     * Zips all files in the temporary directory
+     *
+     * @param string $filename name of resulting zipfile (optional, defaults to portfolio-export.zip)
+     * @param string $filepath subpath in the filearea (optional, defaults to final)
+     * @return stored_file|bool resulting stored_file object, or false
+     */
     public function zip_tempfiles($filename='portfolio-export.zip', $filepath='/final/') {
         $zipper = new zip_packer();
 
@@ -799,12 +797,13 @@ class portfolio_exporter {
     }
 
     /**
-    * returns an arary of files in the temporary working directory
-    * for this export
-    * always use this instead of the files api directly
-    *
-    * @return array of stored_file objects keyed by name
-    */
+     * Returns an arary of files in the temporary working directory
+     * for this export.
+     * Always use this instead of the files api directly
+     *
+     * @param string $skipfile name of the file to be skipped
+     * @return array of stored_file objects keyed by name
+     */
     public function get_tempfiles($skipfile='portfolio-export.zip') {
         $fs = get_file_storage();
         $files = $fs->get_area_files(SYSCONTEXTID, 'portfolio', 'exporter', $this->id, '', false);
@@ -822,14 +821,14 @@ class portfolio_exporter {
     }
 
     /**
-    * returns the context, filearea, and itemid
-    * parts of a filearea (not filepath) to be used by
-    * plugins if they want to do things like zip up the contents of
-    * the temp area to here, or something that can't be done just using
-    * write_new_file,  copy_existing_file or get_tempfiles
-    *
-    * @return array contextid, filearea, itemid are the keys.
-    */
+     * Returns the context, filearea, and itemid.
+     * Parts of a filearea (not filepath) to be used by
+     * plugins if they want to do things like zip up the contents of
+     * the temp area to here, or something that can't be done just using
+     * write_new_file, copy_existing_file or get_tempfiles
+     *
+     * @return array contextid, filearea, itemid are the keys.
+     */
     public function get_base_filearea() {
         return array(
             'contextid' => SYSCONTEXTID,
@@ -839,11 +838,13 @@ class portfolio_exporter {
         );
     }
 
-    /** wrapper function to print a friendly error to users
-    *
-    * this is generally caused by them hitting an expired transfer
-    * through the usage of the backbutton
-    */
+    /**
+     * Wrapper function to print a friendly error to users
+     * This is generally caused by them hitting an expired transfer
+     * through the usage of the backbutton
+     *
+     * @uses exit
+     */
     public static function print_expired_export() {
         global $CFG, $OUTPUT, $PAGE;
         $title = get_string('exportexpired', 'portfolio');
@@ -857,6 +858,13 @@ class portfolio_exporter {
         exit;
     }
 
+    /**
+     * Wrapper function to print a friendly error to users
+     *
+     * @param stdClass $log portfolio_log object
+     * @param portfolio_plugin_base $instance portfolio instance
+     * @uses exit
+     */
     public static function print_cleaned_export($log, $instance=null) {
         global $CFG, $OUTPUT, $PAGE;
         if (empty($instance) || !$instance instanceof portfolio_plugin_base) {
@@ -874,6 +882,13 @@ class portfolio_exporter {
         exit;
     }
 
+    /**
+     * Wrapper function to print continue and/or return link
+     *
+     * @param string $returnurl link to previos page
+     * @param string $continueurl continue to next page
+     * @param array $extras (optional) other links to be display.
+     */
     public static function print_finish_info($returnurl, $continueurl, $extras=null) {
         if ($returnurl) {
             echo '<a href="' . $returnurl . '">' . get_string('returntowhereyouwere', 'portfolio') . '</a><br />';
index c462daa..e38acd7 100644 (file)
@@ -1,75 +1,90 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file contains all the class definitions of the export formats.
  * They are implemented in php classes rather than just a simpler hash
  * Because it provides an easy way to do subtyping using php inheritance.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
+ *                 Martin Dougiamas <http://dougiamas.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
- * base class to inherit from
- * do not use this anywhere in supported_formats
+ * Base class to inherit from.
+ * Do not use this anywhere in supported_formats
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
+ *                 Martin Dougiamas <http://dougiamas.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
  */
 abstract class portfolio_format {
 
     /**
-     * array of mimetypes this format supports
+     * Array of mimetypes this format supports
+     *
+     * @throws coding_exception
      */
     public static function mimetypes() {
         throw new coding_exception('mimetypes() method needs to be overridden in each subclass of portfolio_format');
     }
 
     /**
-     * for multipart formats, eg html with attachments,
-     * we need to have a directory to place associated files in
-     * inside the zip file. this is the name of that directory
+     * For multipart formats, eg html with attachments,
+     * we need to have a directory to place associated files from
+     * inside the zip file. This is the name of that directory
+     *
+     * @throws coding_exception
      */
     public static function get_file_directory() {
         throw new coding_exception('get_file_directory() method needs to be overridden in each subclass of portfolio_format');
     }
 
     /**
-     * given a file, return a snippet of markup in whatever format
+     * Given a file, return a snippet of markup in whatever format
      * to link to that file.
-     * usually involves the path given by {@link get_file_directory}
-     * this is not supported in subclasses of portfolio_format_file
+     * Usually involves the path given by {@see get_file_directory}.
+     * This is not supported in subclasses of portfolio_format_file
      * since they're all just single files.
      *
-     * @param stored_file $file
-     * @param array       $options array of options to pass. can contain:
+     * @param stored_file $file file information object
+     * @param array $options array of options to pass. can contain:
      *              attributes => hash of existing html attributes (eg title, height, width, etc)
-     *                    and whatever the sub class adds into this list
      *
-     * @return string some html or xml or whatever
+     * @throws coding_exception
      */
     public static function file_output($file, $options=null) {
         throw new coding_exception('file_output() method needs to be overridden in each subclass of portfolio_format');
     }
 
+    /**
+     * Create portfolio tag
+     *
+     * @param stored_file $file file information object
+     * @param string $path file path
+     * @param array $attributes portfolio attributes
+     * @return string
+     */
     public static function make_tag($file, $path, $attributes) {
         $srcattr = 'href';
         $tag     = 'a';
@@ -97,23 +112,21 @@ abstract class portfolio_format {
     }
 
     /**
-     * whether this format conflicts with the given format
-     * this is used for the case where an export location
+     * Whether this format conflicts with the given format.
+     * This is used for the case where an export location
      * "generally" supports something like FORMAT_PLAINHTML
-     * but then in a specific export case, must add attachments
-     * which means that FORMAT_RICHHTML is supported in that case
+     * but then in a specific export case, must add attachments,
+     * which means that FORMAT_RICHHTML is supported in that case,
      * which implies removing support for FORMAT_PLAINHTML.
      * Note that conflicts don't have to be bi-directional
      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
      * but not the other way around) and things within the class hierarchy
      * are resolved automatically anyway.
-     *
      * This is really just between subclasses of format_rich
      * and subclasses of format_file.
      *
      * @param string $format one of the FORMAT_XX constants
-     *
-     * @return boolean
+     * @return bool
      */
     public static function conflicts($format) {
         return false;
@@ -121,34 +134,86 @@ abstract class portfolio_format {
 }
 
 /**
-* the most basic type - pretty much everything is a subtype
-*/
+ * The most basic type - pretty much everything is a subtype
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach <penny@catalyst.net.nz>, Martin Dougiamas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_file extends portfolio_format {
 
+    /**
+     * Array of mimetypes this format supports
+     *
+     * @return array
+     */
     public static function mimetypes() {
         return array();
     }
 
+    /**
+     * For multipart formats, eg html with attachments,
+     * we need to have a directory to place associated files from
+     * inside the zip file. This is the name of that directory
+     *
+     * @return bool
+     */
     public static function get_file_directory() {
         return false;
     }
 
+    /**
+     * Given a file, return a snippet of markup in whatever format
+     * to link to that file.
+     * Usually involves the path given by {@see get_file_directory}.
+     * This is not supported in subclasses of portfolio_format_file
+     * since they're all just single files.
+     *
+     * @param stored_file $file informations object
+     * @param array $options array of options to pass. can contain:
+     *              attributes => hash of existing html attributes (eg title, height, width, etc)
+     */
     public static function file_output($file, $options=null) {
         throw new portfolio_exception('fileoutputnotsupported', 'portfolio');
     }
 }
 
 /**
-* image format, subtype of file.
-*/
+ * Image format, subtype of file.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_image extends portfolio_format_file {
     /**
-     * return all mimetypes that use image.gif (eg all images)
+     * Return all mimetypes that use image.gif (eg all images)
+     *
+     * @return string
      */
     public static function mimetypes() {
         return mimeinfo_from_icon('type', 'image', true);
     }
 
+    /**
+     * Whether this format conflicts with the given format.
+     * This is used for the case where an export location
+     * "generally" supports something like FORMAT_PLAINHTML
+     * but then in a specific export case, must add attachments,
+     * which means that FORMAT_RICHHTML is supported in that case,
+     * which implies removing support for FORMAT_PLAINHTML.
+     * Note that conflicts don't have to be bi-directional
+     * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
+     * but not the other way around) and things within the class hierarchy
+     * are resolved automatically anyway.
+     * This is really just between subclasses of format_rich
+     * and subclasses of format_file.
+     *
+     * @param string $format one of the FORMAT_XX constants
+     * @return bool
+     */
     public static function conflicts($format) {
         return ($format == PORTFOLIO_FORMAT_RICHHTML
             || $format == PORTFOLIO_FORMAT_PLAINHTML);
@@ -156,16 +221,42 @@ class portfolio_format_image extends portfolio_format_file {
 }
 
 /**
-* html format - could be used for an external cms or something
-*
-* in case we want to be really specific.
-*/
+ * HTML format
+ * Could be used for an external cms or something in case we want to be really specific.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_plainhtml extends portfolio_format_file {
 
+    /**
+     * Return html mimetype
+     *
+     * @return array
+     */
     public static function mimetypes() {
         return array('text/html');
     }
 
+    /**
+     * Whether this format conflicts with the given format.
+     * This is used for the case where an export location
+     * "generally" supports something like FORMAT_PLAINHTML
+     * but then in a specific export case, must add attachments,
+     * which means that FORMAT_RICHHTML is supported in that case,
+     * which implies removing support for FORMAT_PLAINHTML.
+     * Note that conflicts don't have to be bi-directional
+     * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
+     * but not the other way around) and things within the class hierarchy
+     * are resolved automatically anyway.
+     * This is really just between subclasses of format_rich
+     * and subclasses of format_file.
+     *
+     * @param string $format one of the FORMAT_XX constants
+     * @return bool
+     */
     public static function conflicts($format) {
         return ($format == PORTFOLIO_FORMAT_RICHHTML
             || $format == PORTFOLIO_FORMAT_FILE);
@@ -173,11 +264,21 @@ class portfolio_format_plainhtml extends portfolio_format_file {
 }
 
 /**
-* video format, subtype of file.
-*
-* for portfolio plugins that support videos specifically
-*/
+ * Video format
+ * For portfolio plugins that support videos specifically
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_video extends portfolio_format_file {
+
+     /**
+      * Return video mimetypes
+      *
+      * @return array
+      */
     public static function mimetypes() {
         return array_merge(
             mimeinfo_from_icon('type', 'video', true),
@@ -187,14 +288,43 @@ class portfolio_format_video extends portfolio_format_file {
 }
 
 /**
-* class for plain text format.. not sure why we would need this yet
-* but since resource module wants to export it... we can
-*/
+ * Class for plain text format.
+ * Not sure why we would need this yet,
+ * but since resource module wants to export it... we can
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_text extends portfolio_format_file {
+
+    /**
+     * Return plain text mimetypes
+     *
+     * @return array
+     */
     public static function mimetypes() {
         return array('text/plain');
     }
 
+    /**
+     * Whether this format conflicts with the given format.
+     * This is used for the case where an export location
+     * "generally" supports something like FORMAT_PLAINHTML
+     * but then in a specific export case, must add attachments,
+     * which means that FORMAT_RICHHTML is supported in that case,
+     * which implies removing support for FORMAT_PLAINHTML.
+     * Note that conflicts don't have to be bi-directional
+     * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
+     * but not the other way around) and things within the class hierarchy
+     * are resolved automatically anyway.
+     * This is really just between subclasses of format_rich
+     * and subclasses of format_file.
+     *
+     * @param string $format one of the FORMAT_XX constants
+     * @return bool
+     */
     public static function conflicts($format ) {
         return ($format == PORTFOLIO_FORMAT_PLAINHTML
             || $format == PORTFOLIO_FORMAT_RICHHTML);
@@ -202,11 +332,21 @@ class portfolio_format_text extends portfolio_format_file {
 }
 
 /**
- * base class for rich formats.
- * these are multipart - eg things with attachments
+ * Base class for rich formats.
+ * These are multipart - eg things with attachments
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class portfolio_format_rich extends portfolio_format {
 
+    /**
+     * Return rich text mimetypes
+     *
+     * @return array
+     */
     public static function mimetypes() {
         return array();
     }
@@ -214,13 +354,40 @@ abstract class portfolio_format_rich extends portfolio_format {
 }
 
 /**
- * most commonly used rich format - richhtml - html with attachments
+ * Richhtml - html with attachments.
+ * The most commonly used rich format
  * eg inline images
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class portfolio_format_richhtml extends portfolio_format_rich {
+
+    /**
+     * For multipart formats, eg html with attachments,
+     * we need to have a directory to place associated files from
+     * inside the zip file. this is the name of that directory
+     *
+     * @return string
+     */
     public static function get_file_directory() {
         return 'site_files/';
     }
+
+    /**
+     * Given a file, return a snippet of markup in whatever format
+     * to link to that file.
+     * Usually involves the path given by {@see get_file_directory}.
+     * This is not supported in subclasses of portfolio_format_file
+     * since they're all just single files.
+     *
+     * @param stored_file $file information for existing file
+     * @param array $options array of options to pass. can contain:
+     *              attributes => hash of existing html attributes (eg title, height, width, etc)
+     * @return string
+     */
     public static function file_output($file, $options=null) {
         $path = self::get_file_directory() . $file->get_filename();
         $attributes = array();
@@ -229,28 +396,68 @@ class portfolio_format_richhtml extends portfolio_format_rich {
         }
         return self::make_tag($file, $path, $attributes);
     }
+
+    /**
+     * Whether this format conflicts with the given format.
+     * This is used for the case where an export location
+     * "generally" supports something like FORMAT_PLAINHTML
+     * but then in a specific export case, must add attachments,
+     * which means that FORMAT_RICHHTML is supported in that case,
+     * which implies removing support for FORMAT_PLAINHTML.
+     * Note that conflicts don't have to be bi-directional
+     * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
+     * but not the other way around) and things within the class hierarchy
+     * are resolved automatically anyway.
+     * This is really just between subclasses of format_rich
+     * and subclasses of format_file.
+     *
+     * @todo MDL-31305 - revisit the conflict with file, since we zip here
+     * @param string $format one of the FORMAT_XX constants
+     * @return bool
+     */
     public static function conflicts($format) { // TODO revisit the conflict with file, since we zip here
         return ($format == PORTFOLIO_FORMAT_PLAINHTML || $format == PORTFOLIO_FORMAT_FILE);
     }
 
 }
 
+/**
+ * Class used for leap2a format
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_leap2a extends portfolio_format_rich {
 
+    /**
+     * For multipart formats, eg html with attachments,
+     * we need to have a directory to place associated files from
+     * inside the zip file. this is the name of that directory
+     *
+     * @return string
+     */
     public static function get_file_directory() {
         return 'files/';
     }
 
+    /**
+     * Return the file prefix
+     *
+     * @return string
+     */
     public static function file_id_prefix() {
         return 'storedfile';
     }
 
     /**
-     * return the link to a file
+     * Return the link to a file
      *
-     * @param stored_file $file
-     * @param array       $options can contain the same as normal, with the addition of:
-     *             entry => whether the file is a LEAP2A entry or just a bundled file (default true)
+     * @param stored_file $file information for existing file
+     * @param array $options array of options to pass. can contain:
+     *              attributes => hash of existing html attributes (eg title, height, width, etc)
+     * @return string
      */
     public static function file_output($file, $options=null) {
         $id = '';
@@ -273,6 +480,12 @@ class portfolio_format_leap2a extends portfolio_format_rich {
         return self::make_tag($file, $path, $attributes);
     }
 
+    /**
+     * Generate portfolio_format_leap2a
+     *
+     * @param stdclass $user user information object
+     * @return portfolio_format_leap2a_writer
+     */
     public static function leap2a_writer(stdclass $user=null) {
         global $CFG;
         if (empty($user)) {
@@ -283,35 +496,58 @@ class portfolio_format_leap2a extends portfolio_format_rich {
         return new portfolio_format_leap2a_writer($user);
     }
 
+    /**
+     * Return the manifest name
+     *
+     * @return string
+     */
     public static function manifest_name() {
         return 'leap2a.xml';
     }
 }
 
 
-/**
-* later.... a moodle plugin might support this.
-* it's commented out in portfolio_supported_formats so cannot currently be used.
-*/
+// later.... a moodle plugin might support this.
+// it's commented out in portfolio_supported_formats so cannot currently be used.
 //class portfolio_format_mbkp extends portfolio_format_rich {}
 
 /**
-* 'PDF format', subtype of file.
-*
-* for portfolio plugins that support PDFs specifically
-*/
+ * 'PDF format', subtype of file.
+ * For portfolio plugins that support PDFs specifically.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Dan Poltawski
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_pdf extends portfolio_format_file {
+
+    /**
+     * Return pdf mimetypes
+     *
+     * @return array
+     */
     public static function mimetypes() {
         return array('application/pdf');
     }
 }
 
 /**
-* 'Document format', subtype of file.
-*
-* for portfolio plugins that support documents specifically
-*/
+ * 'Document format', subtype of file.
+ * For portfolio plugins that support documents specifically.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Dan Poltawski
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_document extends portfolio_format_file {
+
+    /**
+     * Return documents mimetypes
+     *
+     * @return array of documents mimetypes
+     */
     public static function mimetypes() {
         return array_merge(
             array('text/plain', 'text/rtf'),
@@ -323,11 +559,21 @@ class portfolio_format_document extends portfolio_format_file {
 }
 
 /**
-* 'Spreadsheet format', subtype of file.
-*
-* for portfolio plugins that support spreadsheets specifically
-*/
+ * 'Spreadsheet format', subtype of file.
+ * For portfolio plugins that support spreadsheets specifically.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Dan Poltawski
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_spreadsheet extends portfolio_format_file {
+
+    /**
+     * Return spreadsheet spreadsheet mimetypes
+     *
+     * @return array of documents mimetypes
+     */
     public static function mimetypes() {
         return array_merge(
             mimeinfo_from_icon('type', 'excel', true),
@@ -338,11 +584,21 @@ class portfolio_format_spreadsheet extends portfolio_format_file {
 }
 
 /**
-* 'Presentation format', subtype of file.
-*
-* for portfolio plugins that support presentation specifically
-*/
+ * 'Presentation format', subtype of file.
+ * For portfolio plugins that support presentation specifically.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Dan Poltawski
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_presentation extends portfolio_format_file {
+
+    /**
+     * Return presentation documents mimetypes
+     *
+     * @return array presentation document mimetypes
+     */
     public static function mimetypes() {
         return mimeinfo_from_icon('type', 'powerpoint', true);
     }
index f705b67..57e8a89 100644 (file)
@@ -1,37 +1,33 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * This file contains the LEAP2a writer used by portfolio_format_leap2a
  *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@liip.ch>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
+ * @package core_portfolio
+ * @copyright 2009 Penny Leach (penny@liip.ch), Martin Dougiamas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  *
- * This file contains the LEAP2a writer used by portfolio_format_leap2a
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
- * object to encapsulate the writing of leap2a.
- * should be used like:
- *
+ * Object to encapsulate the writing of leap2a.
+ * Should be used like:
  * $writer = portfolio_format_leap2a::leap2a_writer($USER);
  * $entry = new portfolio_format_leap2a_entry('forumpost6', $title, 'leap2', 'somecontent')
  * $entry->add_link('something', 'has_part')->add_link('somethingelse', 'has_part');
@@ -39,26 +35,34 @@ defined('MOODLE_INTERNAL') || die();
  * $writer->add_entry($entry);
  * $xmlstr = $writer->to_xml();
  *
- * @TODO find a way to ensure that all referenced files are included
+ * @todo MDL-31287 - find a way to ensure that all referenced files are included
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class portfolio_format_leap2a_writer {
 
-    /** the domdocument object used to create elements */
+    /** @var DomDocument the domdocument object used to create elements */
     private $dom;
-    /** the top level feed element */
+
+    /** @var DOMElement the top level feed element */
     private $feed;
-    /** the user exporting data */
+
+    /** @var stdClass the user exporting data */
     private $user;
-    /** the id of the feed - this is unique to the user and date and used for portfolio ns as well as feed id */
+
+    /** @var string the id of the feed - this is unique to the user and date and used for portfolio ns as well as feed id */
     private $id;
-    /** the entries for the feed - keyed on id */
+
+    /** @var array the entries for the feed - keyed on id */
     private $entries = array();
 
     /**
-     * constructor - usually generated from portfolio_format_leap2a::leap2a_writer($USER);
+     * Constructor - usually generated from portfolio_format_leap2a::leap2a_writer($USER);
      *
+     * @todo MDL-31302 - add exporter and format
      * @param stdclass $user the user exporting (almost always $USER)
-     *
      */
     public function __construct(stdclass $user) { // todo something else - exporter, format, etc
         global $CFG;
@@ -98,9 +102,10 @@ class portfolio_format_leap2a_writer {
     }
 
     /**
-     * adds a entry to the feed ready to be exported
+     * Adds a entry to the feed ready to be exported
      *
-     * @param portfolio_format_leap2a_entry $entry the entry to add
+     * @param portfolio_format_leap2a_entry $entry new feed entry to add
+     * @return portfolio_format_leap2a_entry
      */
     public function add_entry(portfolio_format_leap2a_entry $entry) {
         if (array_key_exists($entry->id, $this->entries)) {
@@ -113,11 +118,11 @@ class portfolio_format_leap2a_writer {
     }
 
     /**
-     * make an entry that has previously been added into the feed into a selection.
+     * Select an entry that has previously been added into the feed
      *
-     * @param mixed $selectionentry the entry to make a selection (id or entry object)
+     * @param portfolio_format_leap2a_entry|string $selectionentry the entry to make a selection (id or entry object)
      * @param array $ids array of ids this selection includes
-     * @param string $selectiontype http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories/selection_type
+     * @param string $selectiontype for selection type, see: http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories/selection_type
      */
     public function make_selection($selectionentry, $ids, $selectiontype) {
         $selectionid = null;
@@ -144,9 +149,9 @@ class portfolio_format_leap2a_writer {
     }
 
     /**
-     * helper function to link some stored_files into the feed and link them to a particular entry
+     * Helper function to link some stored_files into the feed and link them to a particular entry
      *
-     * @param portfolio_format_leap2a_entry $entry the entry to link the files into
+     * @param portfolio_format_leap2a_entry $entry feed object
      * @param array $files array of stored_files to link
      */
     public function link_files($entry, $files) {
@@ -159,7 +164,7 @@ class portfolio_format_leap2a_writer {
     }
 
     /**
-     * validate the feed and all entries
+     * Validate the feed and all entries
      */
     private function validate() {
         foreach ($this->entries as $entry) {
@@ -183,10 +188,10 @@ class portfolio_format_leap2a_writer {
     }
 
     /**
-     * return the entire feed as a string
-     * calls validate() first on everything
+     * Return the entire feed as a string.
+     * Then, it calls for validation
      *
-     * @return string
+     * @return string feeds' content in xml
      */
     public function to_xml() {
         $this->validate();
@@ -199,45 +204,57 @@ class portfolio_format_leap2a_writer {
 }
 
 /**
- * this class represents a single leap2a entry.
- * you can create these directly and then add them to the main leap feed object
+ * This class represents a single leap2a entry.
+ * You can create these directly and then add them to the main leap feed object
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class portfolio_format_leap2a_entry {
 
-    /** entry id  - something like forumpost6, must be unique to the feed **/
+    /** @var string entry id  - something like forumpost6, must be unique to the feed */
     public $id;
-    /** title of the entry **/
+
+    /** @var string title of the entry */
     public $title;
-    /** leap2a entry type **/
+
+    /** @var string leap2a entry type */
     public $type;
-    /** optional author (only if different to feed author) **/
+
+    /** @var string optional author (only if different to feed author) */
     public $author;
-    /** summary - for split long content **/
+
+    /** @var string summary - for split long content */
     public $summary;
-    /** main content of the entry. can be html,text,or xhtml. for a stored_file, use portfolio_format_leap2a_file **/
+
+    /** @var mixed main content of the entry. can be html,text,or xhtml. for a stored_file, use portfolio_format_leap2a_file **/
     public $content;
-    /** updated date - unix timestamp */
+
+    /** @var int updated date - unix timestamp */
     public $updated;
-    /** published date (ctime) - unix timestamp */
+
+    /** @var int published date (ctime) - unix timestamp */
     public $published;
 
-    /** the required fields for a leap2a entry */
+    /** @var array the required fields for a leap2a entry */
     private $requiredfields = array( 'id', 'title', 'type');
 
-    /** extra fields which usually should be set (except author) but are not required */
+    /** @var array extra fields which usually should be set (except author) but are not required */
     private $optionalfields = array('author', 'updated', 'published', 'content', 'summary');
 
-    /** links from this entry to other entries */
+    /** @var array links from this entry to other entries */
     public $links       = array();
 
-    /** attachments to this entry */
+    /** @var array attachments to this entry */
     public $attachments = array();
 
-    /** categories for this entry */
+    /** @var array categories for this entry */
     private $categories = array();
 
     /**
-     * constructor.  All arguments are required (and will be validated)
+     * Constructor.  All arguments are required (and will be validated)
      * http://wiki.cetis.ac.uk/2009-03/LEAP2A_types
      *
      * @param string $id unique id of this entry.
@@ -256,8 +273,12 @@ class portfolio_format_leap2a_entry {
     }
 
     /**
-     * override __set to do proper dispatching for different things
-     * only allows the optional and required leap2a entry fields to be set
+     * Override __set to do proper dispatching for different things.
+     * Only allows the optional and required leap2a entry fields to be set
+     *
+     * @param string $field property's name
+     * @param mixed $value property's value
+     * @return mixed
      */
     public function __set($field, $value) {
         // detect the case where content is being set to be a file directly
@@ -272,9 +293,11 @@ class portfolio_format_leap2a_entry {
 
 
     /**
-     * validate this entry.
-     * at the moment this just makes sure required fields exist
+     * Validate this entry.
+     * At the moment this just makes sure required fields exist
      * but it could also check things against a list, for example
+     *
+     * @todo MDL-31303 - add category with a scheme 'selection_type'
      */
     public function validate() {
         foreach ($this->requiredfields as $key) {
@@ -291,17 +314,17 @@ class portfolio_format_leap2a_entry {
     }
 
     /**
-     * add a link from this entry to another one
-     * these will be collated at the end of the export (during to_xml)
+     * Add a link from this entry to another one.
+     * These will be collated at the end of the export (during to_xml)
      * and validated at that point. This function does no validation
-     * http://wiki.cetis.ac.uk/2009-03/LEAP2A_relationships
+     * {@link http://wiki.cetis.ac.uk/2009-03/LEAP2A_relationships}
      *
-     * @param mixed $otherentry portfolio_format_leap2a_entry or its id
+     * @param portfolio_format_leap2a_entry|string $otherentry portfolio_format_leap2a_entry or its id
      * @param string $reltype (no leap2: ns required)
-     *
-     * @return the current entry object. This is so that these calls can be chained
-     * eg $entry->add_link('something6', 'has_part')->add_link('something7', 'has_part');
-     *
+     * @param string $displayorder (optional)
+     * @return portfolio_format_leap2a_entry the current entry object. This is so that these calls can be chained
+     *                                       eg $entry->add_link('something6', 'has_part')->add_link('something7',
+     *                                       'has_part');
      */
     public function add_link($otherentry, $reltype, $displayorder=null) {
         if ($otherentry instanceof portfolio_format_leap2a_entry) {
@@ -321,15 +344,14 @@ class portfolio_format_leap2a_entry {
     }
 
     /**
-     * add a category to this entry
-     * http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories
+     * Add a category to this entry
+     * {@link http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories}
+     * "tags" should just pass a term here and no scheme or label.
+     * They will be automatically normalised if they have spaces.
      *
      * @param string $term eg 'Offline'
      * @param string $scheme (optional) eg resource_type
      * @param string $label (optional) eg File
-     *
-     * "tags" should just pass a term here and no scheme or label.
-     * they will be automatically normalised if they have spaces.
      */
     public function add_category($term, $scheme=null, $label=null) {
         // "normalise" terms and set their label if they have spaces
@@ -351,8 +373,8 @@ class portfolio_format_leap2a_entry {
      * This is handled by the main writer object.
      *
      * @param DomDocument $dom use this to create elements
-     *
-     * @return DomElement
+     * @param stdClass $feedauthor object of author(user) info
+     * @return DOMDocument
      */
     public function to_dom(DomDocument $dom, $feedauthor) {
         $entry = $dom->createElement('entry');
@@ -413,16 +435,16 @@ class portfolio_format_leap2a_entry {
     }
 
     /**
-     * try to load whatever is in $content into xhtml and add it to the dom.
-     * failing that, load the html, escape it, and set it as the body of the tag
-     * either way it sets the type attribute of the top level element
-     * moodle should always provide xhtml content, but user-defined content can't be trusted
+     * Try to load whatever is in $content into xhtml and add it to the dom.
+     * Failing that, load the html, escape it, and set it as the body of the tag.
+     * Either way it sets the type attribute of the top level element.
+     * Moodle should always provide xhtml content, but user-defined content can't be trusted
      *
+     * @todo MDL-31304 - convert <html><body> </body></html> to xml
      * @param DomDocument $dom the dom doc to use
      * @param string $tagname usually 'content' or 'summary'
      * @param string $content the content to use, either xhtml or html.
-     *
-     * @return DomElement
+     * @return DomDocument
      */
     private function create_xhtmlish_element(DomDocument $dom, $tagname, $content) {
         $topel = $dom->createElement($tagname);
@@ -455,22 +477,29 @@ class portfolio_format_leap2a_entry {
     }
 
     /**
-     * hook function for subclasses to add extra links (like for files)
+     * Hook function for subclasses to add extra links (like for files)
      */
     protected function add_extra_links() {}
 }
 
-
 /**
- * subclass of entry, purely for dealing with files
+ * Subclass of entry, purely for dealing with files
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class portfolio_format_leap2a_file extends portfolio_format_leap2a_entry {
 
+    /** @var file_stored for the dealing file */
     protected $referencedfile;
 
     /**
-     * overridden constructor to set up the file.
+     * Overridden constructor to set up the file.
      *
+     * @param string $title title of the entry
+     * @param stored_file $file file storage instance
      */
     public function __construct($title, stored_file $file) {
         $id = portfolio_format_leap2a::file_id_prefix() . $file->get_id();
@@ -482,7 +511,10 @@ class portfolio_format_leap2a_file extends portfolio_format_leap2a_entry {
     }
 
     /**
-     * implement the hook to add extra links to attach the file in an enclosure
+     * Implement the hook to add extra links to attach the file in an enclosure
+     *
+     * @param DomDocument $dom feed object
+     * @param DomDocument $entry feed added link
      */
     protected function add_extra_links($dom, $entry) {
         $link = $dom->createElement('link');
index db7880c..db93ef2 100644 (file)
@@ -1,29 +1,26 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file contains all the form definitions used by the portfolio code.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
+ *            Martin Dougiamas (http://dougiamas.com)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
@@ -32,17 +29,24 @@ defined('MOODLE_INTERNAL') || die();
 require_once ($CFG->libdir.'/formslib.php');
 
 /**
-* During-export config form.
-*
-* This is the form that is actually used while exporting.
-* Plugins and callers don't get to define their own class
-* as we have to handle form elements from both places
-* See the docs here for more information:
-* http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_export_config
-* http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page#has_export_config
-*/
+ * During-export config form.
+ * This is the form that is actually used while exporting.
+ * Plugins and callers don't get to define their own class
+ * as we have to handle form elements from both places
+ * See the docs here for more information:
+ * http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_export_config
+ * http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page#has_export_config
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 final class portfolio_export_form extends moodleform {
 
+    /**
+     * prepare form
+     */
     public function definition() {
 
         $mform =& $this->_form;
@@ -96,6 +100,12 @@ final class portfolio_export_form extends moodleform {
         $this->add_action_buttons(true, get_string('next'));
     }
 
+    /**
+     * Validate portfolio export form
+     *
+     * @param stdClass $data portfolio information from form data
+     * @return array
+     */
     public function validation($data) {
 
         $errors = array();
@@ -117,20 +127,36 @@ final class portfolio_export_form extends moodleform {
 }
 
 /**
-* Admin config form
-*
-* This form is extendable by plugins who want the admin to be able to configure more than just the name of the instance.
-* This is NOT done by subclassing this class, see the docs for portfolio_plugin_base for more information:
-* http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_admin_config
-*/
+ * Admin config form.
+ * This form is extendable by plugins who want the admin to be able to configure more than just the name of the instance.
+ * This is NOT done by subclassing this class, see the docs for portfolio_plugin_base for more information:
+ * {@link http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_admin_config}
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 final class portfolio_admin_form extends moodleform {
 
+    /** @var object to hold porfolio instance configuration */
     protected $instance;
+
+    /** @var string plugin name*/
     protected $plugin;
+
+    /** @var string portfolio plugin name*/
     protected $portfolio;
+
+    /** @var string plugin availability*/
     protected $action;
+
+    /** @var int portfolio plugin visibility*/
     protected $visible;
 
+    /**
+     * prepare form
+     */
     public function definition() {
         global $CFG;
         $this->plugin = $this->_customdata['plugin'];
@@ -194,6 +220,12 @@ final class portfolio_admin_form extends moodleform {
         $this->add_action_buttons(true, get_string('save', 'portfolio'));
     }
 
+    /**
+     * Validate admin config form
+     *
+     * @param stdObject $data form data
+     * @return array
+     */
     public function validation($data) {
         global $DB;
 
@@ -217,18 +249,28 @@ final class portfolio_admin_form extends moodleform {
 }
 
 /**
-* User config form.
-*
-* This is the form for letting the user configure an instance of a plugin.
-* In order to extend this, you don't subclass this in the plugin..
-* see the docs in portfolio_plugin_base for more information:
-* http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_user_config
-*/
+ * User config form.
+ * This is the form for letting the user configure an instance of a plugin.
+ * In order to extend this, you don't subclass this in the plugin..
+ * see the docs in portfolio_plugin_base for more information:
+ * {@link http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_user_config}
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 final class portfolio_user_form extends moodleform {
 
+    /** @var object  user porfolio instance */
     protected $instance;
+
+    /** @var int hold user id */
     protected $userid;
 
+    /**
+     * prepare form
+     */
     public function definition() {
         $this->instance = $this->_customdata['instance'];
         $this->userid = $this->_customdata['userid'];
@@ -246,6 +288,11 @@ final class portfolio_user_form extends moodleform {
         $this->add_action_buttons(true, get_string('save', 'portfolio'));
     }
 
+    /**
+     * User user config form.
+     *
+     * @param stdClass $data form data
+     */
     public function validation($data) {
 
         $errors = $this->instance->user_config_validation($data);
@@ -255,15 +302,23 @@ final class portfolio_user_form extends moodleform {
 
 
 /**
-* Form that just contains the dropdown menu of available instances
-*
-* This is not used by portfolio_add_button, but on the first step of the export
-* if the plugin instance has not yet been selected.
-*/
+ * Form that just contains the dropdown menu of available instances.
+ * This is not used by portfolio_add_button, but on the first step of the export,
+ * if the plugin instance has not yet been selected.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_instance_select extends moodleform {
 
+    /** @var portfolio_caller_base plugin instance */
     private $caller;
 
+    /**
+     * The required basic elements to the form.
+     */
     function definition() {
         $this->caller = $this->_customdata['caller'];
         $options = $this->_customdata['options'];
index a7b6265..592d606 100644 (file)
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file contains the base classes for portfolio plugins to inherit from:
+ *
  * portfolio_plugin_pull_base and portfolio_plugin_push_base
  * which both in turn inherit from portfolio_plugin_base.
- * See http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin
+ * {@link http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin}
+ *
+ * @package    core_portfolio
+ * @copyright  2008 Penny Leach <penny@catalyst.net.nz>,
+ *             Martin Dougiamas <http://dougiamas.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
-* the base class for portfolio plugins
-* all plugins must subclass this
-* either via {@see portfolio_plugin_pull_base} or {@see portfolio_plugin_push_base}
-*/
+ * The base class for portfolio plugins.
+ * All plugins must subclass this
+ * either via {@see portfolio_plugin_pull_base} or {@see portfolio_plugin_push_base}
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 abstract class portfolio_plugin_base {
 
-    /**
-    * whether this object needs writing out to the database
-    * @var boolean $dirty
-    */
+    /** @var bool whether this object needs writing out to the database */
     protected $dirty;
 
-    /**
-    * id of instance
-    * @var integer $id
-    */
+    /** @var integer id of instance */
     protected $id;
 
-    /**
-    * name of instance
-    * @var string $name
-    */
+    /** @var string name of instance */
     protected $name;
 
-    /**
-    * plugin this instance belongs to
-    * @var string $plugin
-    */
+    /** @var string plugin this instance belongs to */
     protected $plugin;
 
-    /**
-    * whether this instance is visible or not
-    * @var boolean $visible
-    */
+    /** @var bool whether this instance is visible or not */
     protected $visible;
 
-    /**
-    * named array
-    * admin configured config
-    * use {@link set_config} and {@get_config} to access
-    */
+    /** @var array admin configured config use {@link set_config} and {@get_config} to access */
     protected $config;
 
-    /**
-    *
-    * user config cache
-    * named array of named arrays
-    * keyed on userid and then on config field => value
-    * use {@link get_user_config} and {@link set_user_config} to access.
-    */
+    /** @var array user config cache. keyed on userid and then on config field => value use {@link get_user_config} and {@link set_user_config} to access. */
     protected $userconfig;
 
-    /**
-    * named array
-    * export config during export
-    * use {@link get_export_config} and {@link set export_config} to access.
-    */
+    /** @var array export config during export use {@link get_export_config} and {@link set export_config} to access. */
     protected $exportconfig;
 
-    /**
-    * stdclass object
-    * user currently exporting data
-    */
+    /** @var stdClass user currently exporting data */
     protected $user;
 
-    /**
-    * a reference to the exporter object
-    */
+    /** @var stdClass a reference to the exporter object */
     protected $exporter;
 
     /**
-    * array of formats this portfolio supports
-    * the intersection of what this function returns
-    * and what the caller supports will be used
-    * use the constants PORTFOLIO_FORMAT_*
-    *
-    * @return array list of formats
-    */
+     * Array of formats this portfolio supports
+     * the intersection of what this function returns
+     * and what the caller supports will be used.
+     * Use the constants PORTFOLIO_FORMAT_*
+     *
+     * @return array list of formats
+     */
     public function supported_formats() {
         return array(PORTFOLIO_FORMAT_FILE, PORTFOLIO_FORMAT_RICH);
     }
 
     /**
-    * override this if you are supporting the 'file' type (or a subformat)
-    * but have restrictions on mimetypes
-    *
-    * @return boolean
-    */
+     * Override this if you are supporting the 'file' type (or a subformat)
+     * but have restrictions on mimetypes
+     *
+     * @param string $mimetype file type or subformat
+     * @return bool
+     */
     public static function file_mime_check($mimetype) {
         return true;
     }
 
 
     /**
-    * how long does this reasonably expect to take..
-    * should we offer the user the option to wait..
-    * this is deliberately nonstatic so it can take filesize into account
-    *
-    * @param string $callertime - what the caller thinks
-    *                             the portfolio plugin instance
-    *                             is given the final say
-    *                             because it might be (for example) download.
-    * @return string (see PORTFOLIO_TIME_* constants)
-    */
+     * How long does this reasonably expect to take..
+     * Should we offer the user the option to wait..
+     * This is deliberately nonstatic so it can take filesize into account
+     *
+     * @param string $callertime - what the caller thinks
+     *                             the portfolio plugin instance
+     *                             is given the final say
+     *                             because it might be (for example) download.
+     */
     public abstract function expected_time($callertime);
 
     /**
-    * is this plugin push or pill.
-    * if push, cleanup will be called directly after send_package
-    * if not, cleanup will be called after portfolio/file.php is requested
-    *
-    * @return boolean
-    */
+     * Is this plugin push or pull.
+     * If push, cleanup will be called directly after send_package
+     * If not, cleanup will be called after portfolio/file.php is requested
+     */
     public abstract function is_push();
 
     /**
-     * returns the user-friendly name for this plugin
-     * usually just get_string('pluginname', 'portfolio_something')
-     *
-     * @return string
+     * Returns the user-friendly name for this plugin.
+     * Usually just get_string('pluginname', 'portfolio_something')
      */
     public static function get_name() {
         throw new coding_exception('get_name() method needs to be overridden in each subclass of portfolio_plugin_base');
     }
 
     /**
-    * check sanity of plugin
-    * if this function returns something non empty, ALL instances of your plugin
-    * will be set to invisble and not be able to be set back until it's fixed
-    *
-    * @return mixed - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok
-    */
+     * Check sanity of plugin.
+     * If this function returns something non empty, ALL instances of your plugin
+     * will be set to invisble and not be able to be set back until it's fixed
+     *
+     * @return string|int|bool - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok
+     */
     public static function plugin_sanity_check() {
         return 0;
     }
 
     /**
-    * check sanity of instances
-    * if this function returns something non empty, the instance will be
-    * set to invislbe and not be able to be set back until it's fixed.
-    *
-    * @return mixed - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok
-    */
+     * Check sanity of instances.
+     * If this function returns something non empty, the instance will be
+     * set to invislbe and not be able to be set back until it's fixed.
+     *
+     * @return int|string|bool - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok
+     */
     public function instance_sanity_check() {
         return 0;
     }
 
     /**
-    * does this plugin need any configuration by the administrator?
-    *
-    * if you override this to return true,
-    * you <b>must</b> implement {@see admin_config_form}
-    */
+     * Does this plugin need any configuration by the administrator?
+     * If you override this to return true,
+     * you <b>must</b> implement {@see admin_config_form}
+     *
+     * @return bool
+     */
     public static function has_admin_config() {
         return false;
     }
 
     /**
-    * can this plugin be configured by the user in their profile?
-    *
-    * if you override this to return true,
-    * you <b>must</b> implement {@see user_config_form}
-    */
+     * Can this plugin be configured by the user in their profile?
+     * If you override this to return true,
+     * you <b>must</b> implement {@see user_config_form}
+     *
+     * @return bool
+     */
     public function has_user_config() {
         return false;
     }
 
     /**
-    * does this plugin need configuration during export time?
-    *
-    * if you override this to return true,
-    * you <b>must</b> implement {@see export_config_form}
-    */
+     * Does this plugin need configuration during export time?
+     * If you override this to return true,
+     * you <b>must</b> implement {@see export_config_form}
+     *
+     * @return bool
+     */
     public function has_export_config() {
         return false;
     }
 
     /**
-    * just like the moodle form validation function
-    * this is passed in the data array from the form
-    * and if a non empty array is returned, form processing will stop.
-    *
-    * @param array $data data from form.
-    * @return array keyvalue pairs - form element => error string
-    */
+     * Just like the moodle form validation function.
+     * This is passed in the data array from the form
+     * and if a non empty array is returned, form processing will stop.
+     *
+     * @param array $data data from form.
+     */
     public function export_config_validation(array $data) {}
 
     /**
-    * just like the moodle form validation function
-    * this is passed in the data array from the form
-    * and if a non empty array is returned, form processing will stop.
-    *
-    * @param array $data data from form.
-    * @return array keyvalue pairs - form element => error string
-    */
+     * Just like the moodle form validation function.
+     * This is passed in the data array from the form
+     * and if a non empty array is returned, form processing will stop.
+     *
+     * @param array $data data from form.
+     */
     public function user_config_validation(array $data) {}
 
     /**
-    * sets the export time config from the moodle form.
-    * you can also use this to set export config that
-    * isn't actually controlled by the user
-    * eg things that your subclasses want to keep in state
-    * across the export.
-    * keys must be in {@see get_allowed_export_config}
-    *
-    * this is deliberately not final (see boxnet plugin)
-    *
-    * @param array $config named array of config items to set.
-    */
+     * Sets the export time config from the moodle form.
+     * You can also use this to set export config that
+     * isn't actually controlled by the user.
+     * Eg: things that your subclasses want to keep in state
+     * across the export.
+     * Keys must be in {@see get_allowed_export_config}
+     * This is deliberately not final (see boxnet plugin)
+     *
+     * @param array $config named array of config items to set.
+     */
     public function set_export_config($config) {
         $allowed = array_merge(
             array('wait', 'hidewait', 'format', 'hideformat'),
@@ -256,14 +221,12 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    * gets an export time config value.
-    * subclasses should not override this.
-    *
-    * @param string key field to fetch
-    *
-    * @return string config value
-    *
-    */
+     * Gets an export time config value.
+     * Subclasses should not override this.
+     *
+     * @param string $key field to fetch
+     * @return null|string config value
+     */
     public final function get_export_config($key) {
         $allowed = array_merge(
             array('hidewait', 'wait', 'format', 'hideformat'),
@@ -280,179 +243,175 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    * after the user submits their config
-    * they're given a confirm screen
-    * summarising what they've chosen.
-    *
-    * this function should return a table of nice strings => values
-    * of what they've chosen
-    * to be displayed in a table.
-    *
-    * @return array array of config items.
-    */
+     * After the user submits their config,
+     * they're given a confirm screen
+     * summarising what they've chosen.
+     * This function should return a table of nice strings => values
+     * of what they've chosen
+     * to be displayed in a table.
+     *
+     * @return bool
+     */
     public function get_export_summary() {
         return false;
     }
 
     /**
-    * called after the caller has finished having control
-    * of its prepare_package function.
-    * this function should read all the files from the portfolio
-    * working file area and zip them and send them or whatever it wants.
-    * {@see get_tempfiles} to get the list of files.
-    *
-    */
+     * Called after the caller has finished having control
+     * of its prepare_package function.
+     * This function should read all the files from the portfolio
+     * working file area and zip them and send them or whatever it wants.
+     * {@see get_tempfiles} to get the list of files.
+     *
+     */
     public abstract function prepare_package();
 
     /**
-    * this is the function that is responsible for sending
-    * the package to the remote system,
-    * or whatever request is necessary to initiate the transfer.
-    *
-    * @return boolean success
-    */
+     * This is the function that is responsible for sending
+     * the package to the remote system,
+     * or whatever request is necessary to initiate the transfer.
+     *
+     * @return bool success
+     */
     public abstract function send_package();
 
 
     /**
-    * once everything is done and the user
-    * has the finish page displayed to them
-    * the base class takes care of printing them
-    * "return to where you are" or "continue to portfolio" links
-    * this function allows for exta finish options from the plugin
-    *
-    * @return array named array of links => titles
-    */
+     * Once everything is done and the user
+     * has the finish page displayed to them.
+     * The base class takes care of printing them
+     * "return to where you are" or "continue to portfolio" links.
+     * This function allows for exta finish options from the plugin
+     *
+     * @return bool
+     */
     public function get_extra_finish_options() {
         return false;
     }
 
     /**
-    * the url for the user to continue to their portfolio
-    * during the lifecycle of the request
-    *
-    * @return string url or false.
-    */
+     * The url for the user to continue to their portfolio
+     * during the lifecycle of the request
+     */
     public abstract function get_interactive_continue_url();
 
     /**
-     * the url to save in the log as the continue url
-     * this is passed through resolve_static_continue_url()
+     * The url to save in the log as the continue url.
+     * This is passed through resolve_static_continue_url()
      * at display time to the user.
+     *
+     * @return string
      */
     public function get_static_continue_url() {
         return $this->get_interactive_continue_url();
     }
 
     /**
-     * override this function if you need to add something on to the url
-     * for post-export continues (eg from the log page)
-     * mahara does this, for example, to start a jump session
+     * Override this function if you need to add something on to the url
+     * for post-export continues (eg from the log page).
+     * Mahara does this, for example, to start a jump session.
+     *
+     * @param string $url static continue url
+     * @return string
      */
     public function resolve_static_continue_url($url) {
         return $url;
     }
 
     /**
-    * mform to display to the user in their profile
-    * if your plugin can't be configured by the user,
-    * (see {@link has_user_config})
-    * don't bother overriding this function
-    *
-    * @param moodleform $mform passed by reference, add elements to it
-    */
+     * mform to display to the user in their profile
+     * if your plugin can't be configured by the user,
+     * (see {@see has_user_config}).
+     * Don't bother overriding this function
+     *
+     * @param moodleform $mform passed by reference, add elements to it
+     */
     public function user_config_form(&$mform) {}
 
     /**
-    * mform to display to the admin configuring the plugin.
-    * if your plugin can't be configured by the admin,
-    * (see {@link} has_admin_config)
-    * don't bother overriding this function
-    *
-    * this function can be called statically or non statically,
-    * depending on whether it's creating a new instance (statically),
-    * or editing an existing one (non statically)
-    *
-    * @param moodleform $mform passed by reference, add elements to it.
-    */
+     * mform to display to the admin configuring the plugin.
+     * If your plugin can't be configured by the admin,
+     * (@see has_admin_config).
+     * Don't bother overriding this function.
+     * This function can be called statically or non statically,
+     * depending on whether it's creating a new instance (statically),
+     * or editing an existing one (non statically)
+     *
+     * @param moodleform $mform passed by reference, add elements to it.
+     */
     public function admin_config_form(&$mform) {}
 
     /**
-    * just like the moodle form validation function
-    * this is passed in the data array from the form
-    * and if a non empty array is returned, form processing will stop.
-    *
-    * @param array $data data from form.
-    * @return array keyvalue pairs - form element => error string
-    */
+     * Just like the moodle form validation function,
+     * this is passed in the data array from the form
+     * and if a non empty array is returned, form processing will stop.
+     *
+     * @param array $data data from form.
+     */
     public function admin_config_validation($data) {}
+
     /**
-    * mform to display to the user exporting data using this plugin.
-    * if your plugin doesn't need user input at this time,
-    * (see {@link has_export_config}
-    * don't bother overrideing this function
-    *
-    * @param moodleform $mform passed by reference, add elements to it.
-    */
+     * mform to display to the user exporting data using this plugin.
+     * If your plugin doesn't need user input at this time,
+     * (see {@see has_export_config}.
+     * Don't bother overrideing this function
+     *
+     * @param moodleform $mform passed by reference, add elements to it.
+     */
     public function export_config_form(&$mform) {}
 
     /**
-    * override this if your plugin doesn't allow multiple instances
-    *
-    * @return boolean
-    */
+     * Override this if your plugin doesn't allow multiple instances
+     *
+     * @return bool
+     */
     public static function allows_multiple_instances() {
         return true;
     }
 
     /**
-    *
-    * If at any point the caller wants to steal control
-    * it can, by returning something that isn't false
-    * in this function
-    * The controller will redirect to whatever url
-    * this function returns.
-    * Afterwards, you can redirect back to portfolio/add.php?postcontrol=1
-    * and {@link post_control} is called before the rest of the processing
-    * for the stage is done
-    *
-    * @param int stage to steal control *before* (see constants PARAM_STAGE_*}
-    *
-    * @return boolean or string url
-    */
+     * If at any point the caller wants to steal control,
+     * it can, by returning something that isn't false
+     * in this function
+     * The controller will redirect to whatever url
+     * this function returns.
+     * Afterwards, you can redirect back to portfolio/add.php?postcontrol=1
+     * and {@see post_control} is called before the rest of the processing
+     * for the stage is done,
+     *
+     * @param int $stage to steal control *before* (see constants PARAM_STAGE_*}
+     * @return bool
+     */
     public function steal_control($stage) {
         return false;
     }
 
     /**
-    * after a plugin has elected to steal control,
-    * and control returns to portfolio/add.php|postcontrol=1,
-    * this function is called, and passed the stage that was stolen control from
-    * and the request (get and post but not cookie) parameters
-    * this is useful for external systems that need to redirect the user back
-    * with some extra data in the url (like auth tokens etc)
-    * for an example implementation, see boxnet portfolio plugin.
-    *
-    * @param int $stage the stage before control was stolen
-    * @param array $params a merge of $_GET and $_POST
-    *
-    */
-
+     * After a plugin has elected to steal control,
+     * and control returns to portfolio/add.php|postcontrol=1,
+     * this function is called, and passed the stage that was stolen control from
+     * and the request (get and post but not cookie) parameters.
+     * This is useful for external systems that need to redirect the user back
+     * with some extra data in the url (like auth tokens etc)
+     * for an example implementation, see boxnet portfolio plugin.
+     *
+     * @param int $stage the stage before control was stolen
+     * @param array $params a merge of $_GET and $_POST
+     */
     public function post_control($stage, $params) { }
 
     /**
-    * this function creates a new instance of a plugin
-    * saves it in the database, saves the config
-    * and returns it.
-    * you shouldn't need to override it
-    * unless you're doing something really funky
-    *
-    * @param string $plugin portfolio plugin to create
-    * @param string $name name of new instance
-    * @param array $config what the admin config form returned
-    *
-    * @return object subclass of portfolio_plugin_base
-    */
+     * This function creates a new instance of a plugin
+     * saves it in the database, saves the config
+     * and returns it.
+     * You shouldn't need to override it
+     * unless you're doing something really funky
+     *
+     * @param string $plugin portfolio plugin to create
+     * @param string $name name of new instance
+     * @param array $config what the admin config form returned
+     * @return object subclass of portfolio_plugin_base
+     */
     public static function create_instance($plugin, $name, $config) {
         global $DB, $CFG;
         $new = (object)array(
@@ -475,15 +434,14 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    * construct a plugin instance
-    * subclasses should not need  to override this unless they're doing something special
-    * and should call parent::__construct afterwards
-    *
-    * @param int $instanceid id of plugin instance to construct
-    * @param mixed $record stdclass object or named array - use this i you already have the record to avoid another query
-    *
-    * @return object subclass of portfolio_plugin_base
-    */
+     * Construct a plugin instance.
+     * Subclasses should not need to override this unless they're doing something special
+     * and should call parent::__construct afterwards.
+     *
+     * @param int $instanceid id of plugin instance to construct
+     * @param mixed $record stdclass object or named array - use this if you already have the record to avoid another query
+     * @return portfolio_plugin_base
+     */
     public function __construct($instanceid, $record=null) {
         global $DB;
         if (!$record) {
@@ -507,50 +465,50 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-     * called after __construct - allows plugins to perform initialisation tasks
+     * Called after __construct - allows plugins to perform initialisation tasks
      * without having to override the constructor.
      */
     protected function init() { }
 
     /**
-    * a list of fields that can be configured per instance.
-    * this is used for the save handlers of the config form
-    * and as checks in set_config and get_config
-    *
-    * @return array array of strings (config item names)
-    */
+     * A list of fields that can be configured per instance.
+     * This is used for the save handlers of the config form
+     * and as checks in set_config and get_config.
+     *
+     * @return array array of strings (config item names)
+     */
     public static function get_allowed_config() {
         return array();
     }
 
     /**
-    * a list of fields that can be configured by the user.
-    * this is used for the save handlers in the config form
-    * and as checks in set_user_config and get_user_config.
-    *
-    * @return array array of strings (config field names)
-    */
+     * A list of fields that can be configured by the user.
+     * This is used for the save handlers in the config form
+     * and as checks in set_user_config and get_user_config.
+     *
+     * @return array array of strings (config field names)
+     */
     public function get_allowed_user_config() {
         return array();
     }
 
     /**
-    * a list of fields that can be configured by the user.
-    * this is used for the save handlers in the config form
-    * and as checks in set_export_config and get_export_config.
-    *
-    * @return array array of strings (config field names)
-    */
+     * A list of fields that can be configured by the user.
+     * This is used for the save handlers in the config form
+     * and as checks in set_export_config and get_export_config.
+     *
+     * @return array array of strings (config field names)
+     */
     public function get_allowed_export_config() {
         return array();
     }
 
     /**
-    * saves (or updates) the config stored in portfolio_instance_config.
-    * you shouldn't need to override this unless you're doing something funky.
-    *
-    * @param array $config array of config items.
-    */
+     * Saves (or updates) the config stored in portfolio_instance_config.
+     * You shouldn't need to override this unless you're doing something funky.
+     *
+     * @param array $config array of config items.
+     */
     public final function set_config($config) {
         global $DB;
         foreach ($config as $key => $value) {
@@ -577,12 +535,11 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    * gets the value of a particular config item
-    *
-    * @param string $key key to fetch
-    *
-    * @return string the corresponding value
-    */
+     * Gets the value of a particular config item
+     *
+     * @param string $key key to fetch
+     * @return null|mixed the corresponding value
+     */
     public final function get_config($key) {
         if (!in_array($key, $this->get_allowed_config())) {
             $a = (object)array('property' => $key, 'class' => get_class($this));
@@ -595,14 +552,13 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    * get the value of a config item for a particular user
-    *
-    * @param string $key key to fetch
-    * @param integer $userid id of user (defaults to current)
-    *
-    * @return string the corresponding value
-    *
-    */
+     * Get the value of a config item for a particular user.
+     *
+     * @param string $key key to fetch
+     * @param int $userid id of user (defaults to current)
+     * @return string the corresponding value
+     *
+     */
     public final function get_user_config($key, $userid=0) {
         global $DB;
 
@@ -630,13 +586,12 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    *
-    * sets config options for a given user
-    *
-    * @param mixed $config array or stdclass containing key/value pairs to set
-    * @param integer $userid userid to set config for (defaults to current)
-    *
-    */
+     * Sets config options for a given user.
+     *
+     * @param array $config array containing key/value pairs to set
+     * @param int $userid userid to set config for (defaults to current)
+     *
+     */
     public final function set_user_config($config, $userid=0) {
         global $DB;
 
@@ -665,11 +620,13 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    * generic getter for properties belonging to this instance
-    * <b>outside</b> the subclasses
-    * like name, visible etc.
-    *
-    */
+     * Generic getter for properties belonging to this instance
+     * <b>outside</b> the subclasses
+     * like name, visible etc.
+     *
+     * @param string $field property name
+     * @return array|string|int|boolean value of the field
+     */
     public final function get($field) {
         if (property_exists($this, $field)) {
             return $this->{$field};
@@ -679,11 +636,14 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    * generic setter for properties belonging to this instance
-    * <b>outside</b> the subclass
-    * like name, visible, etc.
-    *
-    */
+     * Generic setter for properties belonging to this instance
+     * <b>outside</b> the subclass
+     * like name, visible, etc.
+     *
+     * @param string $field property's name
+     * @param string $value property's value
+     * @return bool
+     */
     public final function set($field, $value) {
         if (property_exists($this, $field)) {
             $this->{$field} =& $value;
@@ -699,11 +659,13 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    * saves stuff that's been stored in the object to the database
-    * you shouldn't need to override this
-    * unless you're doing something really funky.
-    * and if so, call parent::save when you're done.
-    */
+     * Saves stuff that's been stored in the object to the database.
+     * You shouldn't need to override this
+     * unless you're doing something really funky.
+     * and if so, call parent::save when you're done.
+     *
+     * @return bool
+     */
     public function save() {
         global $DB;
         if (!$this->dirty) {
@@ -719,10 +681,12 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    * deletes everything from the database about this plugin instance.
-    * you shouldn't need to override this unless you're storing stuff
-    * in your own tables.  and if so, call parent::delete when you're done.
-    */
+     * Deletes everything from the database about this plugin instance.
+     * You shouldn't need to override this unless you're storing stuff
+     * in your own tables.  and if so, call parent::delete when you're done.
+     *
+     * @return bool
+     */
     public function delete() {
         global $DB;
         $DB->delete_records('portfolio_instance_config', array('instance' => $this->get('id')));
@@ -734,91 +698,114 @@ abstract class portfolio_plugin_base {
     }
 
     /**
-    * perform any required cleanup functions
-    */
+     * Perform any required cleanup functions
+     *
+     * @return bool
+     */
     public function cleanup() {
         return true;
     }
 
     /**
-     * whether this plugin supports multiple exports in the same session
+     * Whether this plugin supports multiple exports in the same session
      * most plugins should handle this, but some that require a redirect for authentication
      * and then don't support dynamically constructed urls to return to (eg box.net)
      * need to override this to return false.
-     * this means that moodle will prevent multiple exports of this *type* of plugin
+     * This means that moodle will prevent multiple exports of this *type* of plugin
      * occurring in the same session.
      *
-     * @return boolean
+     * @return bool
      */
     public static function allows_multiple_exports() {
         return true;
     }
 
     /**
-    * return a string to put at the header summarising this export
-    * by default, just the plugin instance name
-    *
-    * @return string
-    */
+     * Return a string to put at the header summarising this export
+     * by default, just the plugin instance name
+     *
+     * @return string
+     */
     public function heading_summary() {
         return get_string('exportingcontentto', 'portfolio', $this->name);
     }
 }
 
 /**
-* class to inherit from for 'push' type plugins
-* eg those that send the file via a HTTP post or whatever
-*/
+ * Class to inherit from for 'push' type plugins
+ * Eg: those that send the file via a HTTP post or whatever
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 abstract class portfolio_plugin_push_base extends portfolio_plugin_base {
 
+    /**
+     * Get the capability to push
+     *
+     * @return bool
+     */
     public function is_push() {
         return true;
     }
 }
 
 /**
-* class to inherit from for 'pull' type plugins
-* eg those that write a file and wait for the remote system to request it
-* from portfolio/file.php
-* if you're using this you must do $this->set('file', $file) so that it can be served.
-*/
+ * Class to inherit from for 'pull' type plugins.
+ * Eg: those that write a file and wait for the remote system to request it
+ * from portfolio/file.php.
+ * If you're using this you must do $this->set('file', $file) so that it can be served.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 abstract class portfolio_plugin_pull_base extends portfolio_plugin_base {
 
+    /** @var stdclass single file */
     protected $file;
 
+    /**
+     * return the enablelity to push
+     *
+     * @return bool
+     */
     public function is_push() {
         return false;
     }
 
     /**
-    * the base part of the download file url to pull files from
-    * your plugin might need to add &foo=bar on the end
-    * {@see verify_file_request_params}
-    *
-    * @return string the url
-    */
+     * The base part of the download file url to pull files from
+     * your plugin might need to add &foo=bar on the end
+     * {@see verify_file_request_params}
+     *
+     * @return string the url
+     */
     public function get_base_file_url() {
         global $CFG;
         return $CFG->wwwroot . '/portfolio/file.php?id=' . $this->exporter->get('id');
     }
 
     /**
-    * before sending the file when the pull is requested, verify the request parameters
-    * these might include a token of some sort of whatever
-    *
-    * @param array request parameters (POST wins over GET)
-    */
+     * Before sending the file when the pull is requested, verify the request parameters.
+     * These might include a token of some sort of whatever
+     *
+     * @param array $params request parameters (POST wins over GET)
+     */
     public abstract function verify_file_request_params($params);
 
     /**
-    * called from portfolio/file.php
-    * this function sends the stored file out to the browser
-    * the default is to just use send_stored_file,
-    * but other implementations might do something different
-    * for example, send back the file base64 encoded and encrypted
-    * mahara does this but in the response to an xmlrpc request
-    * rather than through file.php
-    */
+     * Called from portfolio/file.php.
+     * This function sends the stored file out to the browser.
+     * The default is to just use send_stored_file,
+     * but other implementations might do something different,
+     * for example, send back the file base64 encoded and encrypted
+     * mahara does this but in the response to an xmlrpc request
+     * rather than through file.php
+     */
     public function send_file() {
         $file = $this->get('file');
         if (!($file instanceof stored_file)) {
index 22f4544..dbb8498 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * This file contains all global functions to do with manipulating portfolios
- * everything else that is logically namespaced by class is in its own file
+ * This file contains all global functions to do with manipulating portfolios.
+ *
+ * Everything else that is logically namespaced by class is in its own file
  * in lib/portfolio/ directory.
  *
  * Major Contributors
  *     - Penny Leach <penny@catalyst.net.nz>
  *
- * @package    core
- * @subpackage portfolio
+ * @package core_portfolio
+ * @category portfolio
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
@@ -52,54 +53,63 @@ require_once($CFG->libdir . '/portfolio/caller.php');
 
 
 /**
- * use this to add a portfolio button or icon or form to a page
- *
+ * Use this to add a portfolio button or icon or form to a page.
  * These class methods do not check permissions. the caller must check permissions first.
  * Later, during the export process, the caller class is instantiated and the check_permissions method is called
  * If you are exporting a single file, you should always call set_format_by_file($file)
- *
  * This class can be used like this:
  * <code>
  * $button = new portfolio_add_button();
  * $button->set_callback_options('name_of_caller_class', array('id' => 6), '/your/mod/lib.php');
  * $button->render(PORTFOLIO_ADD_FULL_FORM, get_string('addeverythingtoportfolio', 'yourmodule'));
  * </code>
- *
  * or like this:
  * <code>
  * $button = new portfolio_add_button(array('callbackclass' => 'name_of_caller_class', 'callbackargs' => array('id' => 6), 'callbackfile' => '/your/mod/lib.php'));
  * $somehtml .= $button->to_html(PORTFOLIO_ADD_TEXT_LINK);
  * </code>
+ *{@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page} for more information
  *
- * See {@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page} for more information
- *
- * @package    moodlecore
- * @subpackage portfolio
+ * @package core_portfolio
+ * @category portfolio
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
-*/
+ */
 class portfolio_add_button {
 
+    /** @var string the name of the callback functions */
     private $callbackclass;
+
+    /** @var array can be an array of arguments to pass back to the callback functions (passed by reference)*/
     private $callbackargs;
+
+    /** @var string caller file */
     private $callbackfile;
+
+    /** @var array array of more specific formats (eg based on mime detection) */
     private $formats;
+
+    /** @var array array of portfolio instances */
     private $instances;
-    private $file; // for single-file exports
-    private $intendedmimetype; // for writing specific types of files
+
+    /** @var stored_file for single-file exports */
+    private $file;
+
+    /** @var string for writing specific types of files*/
+    private $intendedmimetype;
 
     /**
-    * constructor. either pass the options here or set them using the helper methods.
-    * generally the code will be clearer if you use the helper methods.
-    *
-    * @param array $options keyed array of options:
-    *                       key 'callbackclass': name of the caller class (eg forum_portfolio_caller')
-    *                       key 'callbackargs': the array of callback arguments your caller class wants passed to it in the constructor
-    *                       key 'callbackfile': the file containing the class definition of your caller class.
-    *                       See set_callback_options for more information on these three.
-    *                       key 'formats': an array of PORTFOLIO_FORMATS this caller will support
-    *                       See set_formats or set_format_by_file for more information on this.
-    */
+     * Constructor. Either pass the options here or set them using the helper methods.
+     * Generally the code will be clearer if you use the helper methods.
+     *
+     * @param array $options keyed array of options:
+     *                       key 'callbackclass': name of the caller class (eg forum_portfolio_caller')
+     *                       key 'callbackargs': the array of callback arguments your caller class wants passed to it in the constructor
+     *                       key 'callbackfile': the file containing the class definition of your caller class.
+     *                       See set_callback_options for more information on these three.
+     *                       key 'formats': an array of PORTFOLIO_FORMATS this caller will support
+     *                       See set_formats or set_format_by_file for more information on this.
+     */
     public function __construct($options=null) {
         global $SESSION, $CFG;
 
@@ -120,19 +130,21 @@ class portfolio_add_button {
         }
     }
 
-    /*
-    * @param string $class   name of the class containing the callback functions
-    *                        activity modules should ALWAYS use their name_portfolio_caller
-    *                        other locations must use something unique
-    * @param mixed $argarray this can be an array or hash of arguments to pass
-    *                        back to the callback functions (passed by reference)
-    *                        these MUST be primatives to be added as hidden form fields.
-    *                        and the values get cleaned to PARAM_ALPHAEXT or PARAM_NUMBER or PARAM_PATH
-    * @param string $file    this can be autodetected if it's in the same file as your caller,
-    *                        but often, the caller is a script.php and the class in a lib.php
-    *                        so you can pass it here if necessary.
-    *                        this path should be relative (ie, not include) dirroot, eg '/mod/forum/lib.php'
-    */
+    /**
+     * Function to set the callback options
+     *
+     * @param string $class   Name of the class containing the callback functions
+     *                        activity modules should ALWAYS use their name_portfolio_caller
+     *                        other locations must use something unique
+     * @param array $argarray This can be an array or hash of arguments to pass
+     *                        back to the callback functions (passed by reference)
+     *                        these MUST be primatives to be added as hidden form fields.
+     *                        and the values get cleaned to PARAM_ALPHAEXT or PARAM_NUMBER or PARAM_PATH
+     * @param string $file    This can be autodetected if it's in the same file as your caller,
+     *                        but often, the caller is a script.php and the class in a lib.php
+     *                        so you can pass it here if necessary.
+     *                        This path should be relative (ie, not include) dirroot, eg '/mod/forum/lib.php'
+     */
     public function set_callback_options($class, array $argarray, $file=null) {
         global $CFG;
         if (empty($file)) {
@@ -161,19 +173,19 @@ class portfolio_add_button {
         $this->callbackargs = $argarray;
     }
 
-    /*
-    * sets the available export formats for this content
-    * this function will also poll the static function in the caller class
-    * and make sure we're not overriding a format that has nothing to do with mimetypes
-    * eg if you pass IMAGE here but the caller can export LEAP2A it will keep LEAP2A as well.
-    * see portfolio_most_specific_formats for more information
-    *
-    * @param array $formats if the calling code knows better than the static method on the calling class (base_supported_formats)
-    *                       eg, if it's going to be a single file, or if you know it's HTML, you can pass it here instead
-    *                       this is almost always the case so you should always use this.
-    *                       {@see portfolio_format_from_mimetype} for how to get the appropriate formats to pass here for uploaded files.
-    *                       or just call set_format_by_file instead
-    */
+    /**
+     * Sets the available export formats for this content.
+     * This function will also poll the static function in the caller class
+     * and make sure we're not overriding a format that has nothing to do with mimetypes.
+     * Eg: if you pass IMAGE here but the caller can export LEAP2A it will keep LEAP2A as well.
+     * {@see portfolio_most_specific_formats for more information}
+     *
+     * @param array $formats if the calling code knows better than the static method on the calling class (base_supported_formats).
+     *                       Eg: if it's going to be a single file, or if you know it's HTML, you can pass it here instead.
+     *                       This is almost always the case so it should be use all the times
+     *                       {@see portfolio_format_from_mimetype} for how to get the appropriate formats to pass here for uploaded files.
+     *                       or just call set_format_by_file instead
+     */
     public function set_formats($formats=null) {
         if (is_string($formats)) {
             $formats = array($formats);
@@ -189,7 +201,7 @@ class portfolio_add_button {
     }
 
     /**
-     * reset formats to the default
+     * Reset formats to the default,
      * which is usually what base_supported_formats returns
      */
     public function reset_formats() {
@@ -198,13 +210,13 @@ class portfolio_add_button {
 
 
     /**
-     * if we already know we have exactly one file,
+     * If we already know we have exactly one file,
      * bypass set_formats and just pass the file
      * so we can detect the formats by mimetype.
      *
-     * @param stored_file $file         file to set the format from
-     * @param mixed       $extraformats any additional formats other than by mimetype
-     *                                  eg leap2a etc
+     * @param stored_file $file file to set the format from
+     * @param array $extraformats any additional formats other than by mimetype
+     *                            eg leap2a etc
      */
     public function set_format_by_file(stored_file $file, $extraformats=null) {
         $this->file = $file;
@@ -218,12 +230,12 @@ class portfolio_add_button {
     }
 
     /**
-     * correllary to set_format_by_file, but this is used when we don't yet have a stored_file
+     * Correllary this is use to set_format_by_file, but it is also used when there is no stored_file and
      * when we're writing out a new type of file (like csv or pdf)
      *
      * @param string $extn the file extension we intend to generate
-     * @param mixed        $extraformats any additional formats other than by mimetype
-     *                                  eg leap2a etc
+     * @param array  $extraformats any additional formats other than by mimetype
+     *                             eg leap2a etc
      */
     public function set_format_by_intended_file($extn, $extraformats=null) {
         $mimetype = mimeinfo('type', 'something. ' . $extn);
@@ -237,28 +249,29 @@ class portfolio_add_button {
         $this->set_formats(array_merge(array($fileformat), $extraformats));
     }
 
-    /*
-    * echo the form/button/icon/text link to the page
-    *
-    * @param int $format format to display the button or form or icon or link.
-    *                    See constants PORTFOLIO_ADD_XXX for more info.
-    *                    optional, defaults to PORTFOLIO_ADD_FULL_FORM
-    * @param str $addstr string to use for the button or icon alt text or link text.
-    *                    this is whole string, not key. optional, defaults to 'Export to portfolio';
-    */
+    /**
+     * Echo the form/button/icon/text link to the page
+     *
+     * @param int $format format to display the button or form or icon or link.
+     *                    See constants PORTFOLIO_ADD_XXX for more info.
+     *                    optional, defaults to PORTFOLIO_ADD_FULL_FORM
+     * @param string $addstr string to use for the button or icon alt text or link text.
+     *                       this is whole string, not key. optional, defaults to 'Export to portfolio';
+     */
     public function render($format=null, $addstr=null) {
         echo $this->to_html($format, $addstr);
     }
 
-    /*
-    * returns the form/button/icon/text link as html
-    *
-    * @param int $format format to display the button or form or icon or link.
-    *                    See constants PORTFOLIO_ADD_XXX for more info.
-    *                    optional, defaults to PORTFOLIO_ADD_FULL_FORM
-    * @param str $addstr string to use for the button or icon alt text or link text.
-    *                    this is whole string, not key.  optional, defaults to 'Add to portfolio';
-    */
+    /**
+     * Returns the form/button/icon/text link as html
+     *
+     * @param int $format format to display the button or form or icon or link.
+     *                    See constants PORTFOLIO_ADD_XXX for more info.
+     *                    Optional, defaults to PORTFOLIO_ADD_FULL_FORM
+     * @param string $addstr string to use for the button or icon alt text or link text.
+     *                       This is whole string, not key.  optional, defaults to 'Add to portfolio';
+     * @return void|string
+     */
     public function to_html($format=null, $addstr=null) {
         global $CFG, $COURSE, $OUTPUT, $USER;
         if (!$this->is_renderable()) {
@@ -366,10 +379,12 @@ class portfolio_add_button {
     }
 
     /**
-    * does some internal checks
-    * these are not errors, just situations
-    * where it's not appropriate to add the button
-    */
+     * Perform some internal checks.
+     * These are not errors, just situations
+     * where it's not appropriate to add the button
+     *
+     * @return bool
+     */
     private function is_renderable() {
         global $CFG;
         if (empty($CFG->enableportfolios)) {
@@ -388,6 +403,7 @@ class portfolio_add_button {
 
     /**
      * Getter for $format property
+     *
      * @return array
      */
     public function get_formats() {
@@ -396,6 +412,7 @@ class portfolio_add_button {
 
     /**
      * Getter for $callbackargs property
+     *
      * @return array
      */
     public function get_callbackargs() {
@@ -404,7 +421,8 @@ class portfolio_add_button {
 
     /**
      * Getter for $callbackfile property
-     * @return array
+     *
+     * @return string
      */
     public function get_callbackfile() {
         return $this->callbackfile;
@@ -412,7 +430,8 @@ class portfolio_add_button {
 
     /**
      * Getter for $callbackclass property
-     * @return array
+     *
+     * @return string
      */
     public function get_callbackclass() {
         return $this->callbackclass;
@@ -420,18 +439,17 @@ class portfolio_add_button {
 }
 
 /**
-* returns a drop menu with a list of available instances.
-*
-* @param array          $instances      array of portfolio plugin instance objects - the instances to put in the menu
-* @param array          $callerformats  array of PORTFOLIO_FORMAT_XXX constants - the formats the caller supports (this is used to filter plugins)
-* @param array          $callbackclass  the callback class name - used for debugging only for when there are no common formats
-* @param mimetype       $mimetype       if we already know we have exactly one file, or are going to write one, pass it here to do mime filtering.
-* @param string         $selectname     the name of the select element. Optional, defaults to instance.
-* @param boolean        $return         whether to print or return the output. Optional, defaults to print.
-* @param booealn        $returnarray    if returning, whether to return the HTML or the array of options. Optional, defaults to HTML.
-*
-* @return string the html, from <select> to </select> inclusive.
-*/
+ * Returns a drop menu with a list of available instances.
+ *
+ * @param array          $instances      array of portfolio plugin instance objects - the instances to put in the menu
+ * @param array          $callerformats  array of PORTFOLIO_FORMAT_XXX constants - the formats the caller supports (this is used to filter plugins)
+ * @param string         $callbackclass  the callback class name - used for debugging only for when there are no common formats
+ * @param string         $mimetype       if we already know we have exactly one file, or are going to write one, pass it here to do mime filtering.
+ * @param string         $selectname     the name of the select element. Optional, defaults to instance.
+ * @param bool           $return         whether to print or return the output. Optional, defaults to print.
+ * @param bool           $returnarray    if returning, whether to return the HTML or the array of options. Optional, defaults to HTML.
+ * @return void|array|string the html, from <select> to </select> inclusive.
+ */
 function portfolio_instance_select($instances, $callerformats, $callbackclass, $mimetype=null, $selectname='instance', $return=false, $returnarray=false) {
     global $CFG, $USER;
 
@@ -489,15 +507,13 @@ function portfolio_instance_select($instances, $callerformats, $callbackclass, $
 }
 
 /**
-* return all portfolio instances
-*
-* @todo check capabilities here - see MDL-15768
-*
-* @param boolean visibleonly Don't include hidden instances. Defaults to true and will be overridden to true if the next parameter is true
-* @param boolean useronly    Check the visibility preferences and permissions of the logged in user. Defaults to true.
-*
-* @return array of portfolio instances (full objects, not just database records)
-*/
+ * Return all portfolio instances
+ *
+ * @todo MDL-15768 - check capabilities here
+ * @param bool $visibleonly Don't include hidden instances. Defaults to true and will be overridden to true if the next parameter is true
+ * @param bool $useronly    Check the visibility preferences and permissions of the logged in user. Defaults to true.
+ * @return array of portfolio instances (full objects, not just database records)
+ */
 function portfolio_instances($visibleonly=true, $useronly=true) {
 
     global $DB, $USER;
@@ -526,14 +542,13 @@ function portfolio_instances($visibleonly=true, $useronly=true) {
 }
 
 /**
-* Supported formats currently in use.
-*
-* Canonical place for a list of all formats
-* that portfolio plugins and callers
-* can use for exporting content
-*
-* @return keyed array of all the available export formats (constant => classname)
-*/
+ * Supported formats currently in use.
+ * Canonical place for a list of all formats
+ * that portfolio plugins and callers
+ * can use for exporting content
+ *
+ * @return array keyed array of all the available export formats (constant => classname)
+ */
 function portfolio_supported_formats() {
     return array(
         PORTFOLIO_FORMAT_FILE         => 'portfolio_format_file',
@@ -553,19 +568,17 @@ function portfolio_supported_formats() {
 }
 
 /**
-* Deduce export format from file mimetype
-*
-* This function returns the revelant portfolio export format
-* which is used to determine which portfolio plugins can be used
-* for exporting this content
-* according to the given mime type
-* this only works when exporting exactly <b>one</b> file, or generating a new one
-* (like a pdf or csv export)
-*
-* @param string $mimetype (usually $file->get_mimetype())
-*
-* @return string the format constant (see PORTFOLIO_FORMAT_XXX constants)
-*/
+ * Deduce export format from file mimetype
+ * This function returns the revelant portfolio export format
+ * which is used to determine which portfolio plugins can be used
+ * for exporting this content
+ * according to the given mime type
+ * this only works when exporting exactly <b>one</b> file, or generating a new one
+ * (like a pdf or csv export)
+ *
+ * @param string $mimetype (usually $file->get_mimetype())
+ * @return string the format constant (see PORTFOLIO_FORMAT_XXX constants)
+ */
 function portfolio_format_from_mimetype($mimetype) {
     global $CFG;
     static $alreadymatched;
@@ -593,15 +606,15 @@ function portfolio_format_from_mimetype($mimetype) {
 }
 
 /**
-* Intersection of plugin formats and caller formats
-*
-* Walks both the caller formats and portfolio plugin formats
-* and looks for matches (walking the hierarchy as well)
-* and returns the intersection
-*
-* @param array $callerformats formats the caller supports
-* @param array $pluginformats formats the portfolio plugin supports
-*/
+ * Intersection of plugin formats and caller formats.
+ * Walks both the caller formats and portfolio plugin formats
+ * and looks for matches (walking the hierarchy as well)
+ * and returns the intersection
+ *
+ * @param array $callerformats formats the caller supports
+ * @param array $pluginformats formats the portfolio plugin supports
+ * @return array
+ */
 function portfolio_supported_formats_intersect($callerformats, $pluginformats) {
     global $CFG;
     $allformats = portfolio_supported_formats();
@@ -632,10 +645,9 @@ function portfolio_supported_formats_intersect($callerformats, $pluginformats) {
 }
 
 /**
- * tiny helper to figure out whether a portfolio format is abstract
+ * Tiny helper to figure out whether a portfolio format is abstract
  *
  * @param string $format the format to test
- *
  * @retun bool
  */
 function portfolio_format_is_abstract($format) {
@@ -657,17 +669,16 @@ function portfolio_format_is_abstract($format) {
 }
 
 /**
-* return the combination of the two arrays of formats with duplicates in terms of specificity removed
-* and also removes conflicting formats
-* use case: a module is exporting a single file, so the general formats would be FILE and MBKP
-*           while the specific formats would be the specific subclass of FILE based on mime (say IMAGE)
-*           and this function would return IMAGE and MBKP
-*
-* @param array $specificformats array of more specific formats (eg based on mime detection)
-* @param array $generalformats  array of more general formats (usually more supported)
-*
-* @return array merged formats with dups removed
-*/
+ * Return the combination of the two arrays of formats with duplicates in terms of specificity removed
+ * and also removes conflicting formats.
+ * Use case: a module is exporting a single file, so the general formats would be FILE and MBKP
+ *           while the specific formats would be the specific subclass of FILE based on mime (say IMAGE)
+ *           and this function would return IMAGE and MBKP
+ *
+ * @param array $specificformats array of more specific formats (eg based on mime detection)
+ * @param array $generalformats  array of more general formats (usually more supported)
+ * @return array merged formats with dups removed
+ */
 function portfolio_most_specific_formats($specificformats, $generalformats) {
     global $CFG;
     $allformats = portfolio_supported_formats();
@@ -729,12 +740,11 @@ function portfolio_most_specific_formats($specificformats, $generalformats) {
 }
 
 /**
-* helper function to return a format object from the constant
-*
-* @param string $name the constant PORTFOLIO_FORMAT_XXX
-*
-* @return portfolio_format object
-*/
+ * Helper function to return a format object from the constant
+ *
+ * @param string $name the constant PORTFOLIO_FORMAT_XXX
+ * @return portfolio_format
+ */
 function portfolio_format_object($name) {
     global $CFG;
     require_once($CFG->libdir . '/portfolio/formats.php');
@@ -743,15 +753,14 @@ function portfolio_format_object($name) {
 }
 
 /**
-* helper function to return an instance of a plugin (with config loaded)
-*
-* @param int   $instance id of instance
-* @param array $record   database row that corresponds to this instance
-*                        this is passed to avoid unnecessary lookups
-*                        Optional, and the record will be retrieved if null.
-*
-* @return subclass of portfolio_plugin_base
-*/
+ * Helper function to return an instance of a plugin (with config loaded)
+ *
+ * @param int   $instanceid id of instance
+ * @param object $record database row that corresponds to this instance
+ *                       this is passed to avoid unnecessary lookups
+ *                       Optional, and the record will be retrieved if null.
+ * @return object of portfolio_plugin_XXX
+ */
 function portfolio_instance($instanceid, $record=null) {
     global $DB, $CFG;
 
@@ -769,15 +778,15 @@ function portfolio_instance($instanceid, $record=null) {
 }
 
 /**
-* Helper function to call a static function on a portfolio plugin class
-*
-* This will figure out the classname and require the right file and call the function.
-* you can send a variable number of arguments to this function after the first two
-* and they will be passed on to the function you wish to call.
-*
-* @param string $plugin   name of plugin
-* @param string $function function to call
-*/
+ * Helper function to call a static function on a portfolio plugin class.
+ * This will figure out the classname and require the right file and call the function.
+ * You can send a variable number of arguments to this function after the first two
+ * and they will be passed on to the function you wish to call.
+ *
+ * @param string $plugin   name of plugin
+ * @param string $function function to call
+ * @return mixed
+ */
 function portfolio_static_function($plugin, $function) {
     global $CFG;
 
@@ -804,13 +813,11 @@ function portfolio_static_function($plugin, $function) {
 }
 
 /**
-* helper function to check all the plugins for sanity and set any insane ones to invisible.
-*
-* @param array $plugins to check (if null, defaults to all)
-*               one string will work too for a single plugin.
-*
-* @return array array of insane instances (keys= id, values = reasons (keys for plugin lang)
-*/
+ * Helper function to check all the plugins for sanity and set any insane ones to invisible.
+ *
+ * @param array $plugins array of supported plugin types
+ * @return array array of insane instances (keys= id, values = reasons (keys for plugin lang)
+ */
 function portfolio_plugin_sanity_check($plugins=null) {
     global $DB;
     if (is_string($plugins)) {
@@ -836,13 +843,11 @@ function portfolio_plugin_sanity_check($plugins=null) {
 }
 
 /**
-* helper function to check all the instances for sanity and set any insane ones to invisible.
-*
-* @param array $instances to check (if null, defaults to all)
-*              one instance or id will work too
-*
-* @return array array of insane instances (keys= id, values = reasons (keys for plugin lang)
-*/
+ * Helper function to check all the instances for sanity and set any insane ones to invisible.
+ *
+ * @param array $instances array of plugin instances
+ * @return array array of insane instances (keys= id, values = reasons (keys for plugin lang)
+ */
 function portfolio_instance_sanity_check($instances=null) {
     global $DB;
     if (empty($instances)) {
@@ -877,12 +882,13 @@ function portfolio_instance_sanity_check($instances=null) {
 }
 
 /**
-* helper function to display a table of plugins (or instances) and reasons for disabling
-*
-* @param array $insane array of insane plugins (key = plugin (or instance id), value = reason)
-* @param array $instances if reporting instances rather than whole plugins, pass the array (key = id, value = object) here
-*
-*/
+ * Helper function to display a table of plugins (or instances) and reasons for disabling
+ *
+ * @param array $insane array of portfolio plugin
+ * @param array $instances if reporting instances rather than whole plugins, pass the array (key = id, value = object) here
+ * @param bool $return option to deliver the report in html format or print it out directly to the page.
+ * @return void|string of portfolio report in html table format
+ */
 function portfolio_report_insane($insane, $instances=false, $return=false) {
     global $OUTPUT;
     if (empty($insane)) {
@@ -924,8 +930,11 @@ function portfolio_report_insane($insane, $instances=false, $return=false) {
 
 
 /**
-* event handler for the portfolio_send event
-*/
+ * Event handler for the portfolio_send event
+ *
+ * @param int $eventdata event id
+ * @return bool
+ */
 function portfolio_handle_event($eventdata) {
     global $CFG;
 
@@ -939,11 +948,11 @@ function portfolio_handle_event($eventdata) {
 }
 
 /**
-* main portfolio cronjob
-* currently just cleans up expired transfer records.
-*
-* @todo add hooks in the plugins - either per instance or per plugin
-*/
+ * Main portfolio cronjob.
+ * Currently just cleans up expired transfer records.
+ *
+ * @todo - MDL-15997 - Add hooks in the plugins - either per instance or per plugin
+ */
 function portfolio_cron() {
     global $DB, $CFG;
 
@@ -961,29 +970,24 @@ function portfolio_cron() {
 }
 
 /**
- * helper function to rethrow a caught portfolio_exception as an export exception
- *
- * used because when a portfolio_export exception is thrown the export is cancelled
- *
+ * Helper function to rethrow a caught portfolio_exception as an export exception.
+ * Used because when a portfolio_export exception is thrown the export is cancelled
  * throws portfolio_export_exceptiog
  *
  * @param portfolio_exporter $exporter  current exporter object
- * @param exception          $exception exception to rethrow
- *
- * @return void
+ * @param object             $exception exception to rethrow
  */
 function portfolio_export_rethrow_exception($exporter, $exception) {
     throw new portfolio_export_exception($exporter, $exception->errorcode, $exception->module, $exception->link, $exception->a);
 }
 
 /**
-* try and determine expected_time for purely file based exports
-* or exports that might include large file attachments.
-*
- * @global object
-* @param mixed $totest - either an array of stored_file objects or a single stored_file object
-* @return constant PORTFOLIO_TIME_XXX
-*/
+ * Try and determine expected_time for purely file based exports
+ * or exports that might include large file attachments.
+ *
+ * @param stored_file|array $totest - either an array of stored_file objects or a single stored_file object
+ * @return string PORTFOLIO_TIME_XXX
+ */
 function portfolio_expected_time_file($totest) {
     global $CFG;
     if ($totest instanceof stored_file) {
@@ -1023,9 +1027,11 @@ function portfolio_expected_time_file($totest) {
 
 
 /**
-* the default filesizes and threshold information for file based transfers
-* this shouldn't need to be used outside the admin pages and the portfolio code
-*/
+ * The default filesizes and threshold information for file based transfers.
+ * This shouldn't need to be used outside the admin pages and the portfolio code
+ *
+ * @return array
+ */
 function portfolio_filesize_info() {
     $filesizes = array();
     $sizelist = array(10240, 51200, 102400, 512000, 1048576, 2097152, 5242880, 10485760, 20971520, 52428800);
@@ -1040,13 +1046,12 @@ function portfolio_filesize_info() {
 }
 
 /**
-* try and determine expected_time for purely database based exports
-* or exports that might include large parts of a database
-*
- * @global object
-* @param integer $recordcount - number of records trying to export
-* @return constant PORTFOLIO_TIME_XXX
-*/
+ * Try and determine expected_time for purely database based exports
+ * or exports that might include large parts of a database.
+ *
+ * @param int $recordcount number of records trying to export
+ * @return string PORTFOLIO_TIME_XXX
+ */
 function portfolio_expected_time_db($recordcount) {
     global $CFG;
 
@@ -1065,7 +1070,10 @@ function portfolio_expected_time_db($recordcount) {
 }
 
 /**
- * @global object
+ * Function to send portfolio report to admins
+ *
+ * @param array $insane array of insane plugins
+ * @param array $instances (optional) if reporting instances rather than whole plugins
  */
 function portfolio_insane_notify_admins($insane, $instances=false) {
 
@@ -1121,6 +1129,12 @@ function portfolio_insane_notify_admins($insane, $instances=false) {
     }
 }
 
+/**
+ * Setup page export
+ *
+ * @param moodle_page $PAGE global variable from page object
+ * @param portfolio_caller_base $caller plugin type caller
+ */
 function portfolio_export_pagesetup($PAGE, $caller) {
     // set up the context so that build_navigation works nice
     $caller->set_context($PAGE);
@@ -1136,6 +1150,13 @@ function portfolio_export_pagesetup($PAGE, $caller) {
     $PAGE->navbar->add(get_string('exporting', 'portfolio'));
 }
 
+/**
+ * Get export type id
+ *
+ * @param string $type plugin type
+ * @param int $userid the user to check for
+ * @return mixed|bool
+ */
 function portfolio_export_type_to_id($type, $userid) {
     global $DB;
     $sql = 'SELECT t.id FROM {portfolio_tempdata} t JOIN {portfolio_instance} i ON t.instance = i.id WHERE t.userid = ? AND i.plugin = ?';
@@ -1143,14 +1164,13 @@ function portfolio_export_type_to_id($type, $userid) {
 }
 
 /**
- * return a list of current exports for the given user
- * this will not go through and call rewaken_object, because it's heavy
- * it's really just used to figure out what exports are currently happening.
- * this is useful for plugins that don't support multiple exports per session
+ * Return a list of current exports for the given user.
+ * This will not go through and call rewaken_object, because it's heavy.
+ * It's really just used to figure out what exports are currently happening.
+ * This is useful for plugins that don't support multiple exports per session
  *
- * @param int $userid  the user to check for
+ * @param int $userid the user to check for
  * @param string $type (optional) the portfolio plugin to filter by
- *
  * @return array
  */
 function portfolio_existing_exports($userid, $type=null) {
@@ -1168,6 +1188,9 @@ function portfolio_existing_exports($userid, $type=null) {
  * Return an array of existing exports by type for a given user.
  * This is much more lightweight than {@see existing_exports} because it only returns the types, rather than the whole serialised data
  * so can be used for checking availability of multiple plugins at the same time.
+ *
+ * @param int $userid the user to check for
+ * @return array
  */
 function portfolio_existing_exports_by_plugin($userid) {
     global $DB;
@@ -1177,8 +1200,7 @@ function portfolio_existing_exports_by_plugin($userid) {
 }
 
 /**
- * Return default common options for {@link format_text()} when preparing a content to be exported
- *
+ * Return default common options for {@link format_text()} when preparing a content to be exported.
  * It is important not to apply filters and not to clean the HTML in format_text()
  *
  * @return stdClass
@@ -1198,6 +1220,15 @@ function portfolio_format_text_options() {
 /**
  * callback function from {@link portfolio_rewrite_pluginfile_urls}
  * looks through preg_replace matches and replaces content with whatever the active portfolio export format says
+ *
+ * @param int $contextid module context id
+ * @param string $component module name (eg:mod_assignment)
+ * @param string $filearea normal file_area arguments
+ * @param int $itemid component item id
+ * @param portfolio_format $format exporter format type
+ * @param array $options extra options to pass through to the file_output function in the format (optional)
+ * @param array $matches internal matching
+ * @return object|array|string
  */
 function portfolio_rewrite_pluginfile_url_callback($contextid, $component, $filearea, $itemid, $format, $options, $matches) {
     $matches = $matches[0]; // no internal matching
@@ -1239,19 +1270,18 @@ function portfolio_rewrite_pluginfile_url_callback($contextid, $component, $file
 
 
 /**
- * go through all the @@PLUGINFILE@@ matches in some text,
+ * Go through all the @@PLUGINFILE@@ matches in some text,
  * extract the file information and pass it back to the portfolio export format
  * to regenerate the html to output
  *
- * @param string           $text the text to search through
- * @param int              $contextid normal file_area arguments
- * @param string           $component
- * @param string           $filearea  normal file_area arguments
- * @param int              $itemid    normal file_area arguments
- * @param portfolio_format $format    the portfolio export format
- * @param array            $options   extra options to pass through to the file_output function in the format (optional)
- *
- * @return string
+ * @param string $text the text to search through
+ * @param int $contextid normal file_area arguments
+ * @param string $component module name
+ * @param string $filearea normal file_area arguments
+ * @param int $itemid normal file_area arguments
+ * @param portfolio_format $format the portfolio export format
+ * @param array $options additional options to be included in the plugin file url (optional)
+ * @return mixed
  */
 function portfolio_rewrite_pluginfile_urls($text, $contextid, $component, $filearea, $itemid, $format, $options=null) {
     $pattern = '/(<[^<]*?="@@PLUGINFILE@@\/[^>]*?(?:\/>|>.*?<\/[^>]*?>))/';
index 696c32a..b3c3982 100644 (file)
@@ -1,29 +1,26 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    moodle
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file is the main controller to do with the portfolio export wizard.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
+ *            Martin Dougiamas <http://dougiamas.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL
  */
 require_once(dirname(dirname(__FILE__)) . '/config.php');
 
index b9dbd5e..dc80585 100644 (file)
@@ -1,31 +1,28 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    moodle
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * For portfolio plugins that are 'pull' - ie, send the request and then wait
  * for the remote system to request the file for moodle,
  * this is the script that serves up the export file to them.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
+ *            Martin Dougiamas <http://dougiamas.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 require_once(dirname(dirname(__FILE__)) . '/config.php');