MDL-30989 portfolio: Fixed up phpdocs
authorSam Hemelryk <sam@moodle.com>
Wed, 15 Feb 2012 02:33:06 +0000 (15:33 +1300)
committerSam Hemelryk <sam@moodle.com>
Wed, 15 Feb 2012 02:33:06 +0000 (15:33 +1300)
lib/portfolio/caller.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

index 240aeb9..1a3fd3e 100644 (file)
@@ -30,8 +30,8 @@ defined('MOODLE_INTERNAL') || die();
 /**
  * Base class for callers
  *
- * {@link See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page}
- * {@see also portfolio_module_caller_base}
+ * @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
@@ -43,7 +43,7 @@ abstract class portfolio_caller_base {
     /** @var stdClass course active during the call */
     protected $course;
 
-    /** @var array configuration used for export. Use {@see  set_export_config} and {@see get_export_config} to access */
+    /** @var array configuration used for export. Use set_export_config and get_export_config to access */
     protected $exportconfig = array();
 
     /** @var stdclass user currently exporting content */
@@ -207,7 +207,7 @@ abstract class portfolio_caller_base {
     /**
      * Stores the config generated at export time.
      * Subclasses can retrieve values using
-     * {@see get_export_config}
+     * @see get_export_config
      *
      * @param array $config formdata
      */
@@ -278,8 +278,11 @@ abstract class portfolio_caller_base {
     /**
      * 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}
+     * the temporary directory, using copy_existing_file
+     * or write_new_file
+     *
+     * @see copy_existing_file()
+     * @see write_new_file()
      */
     public abstract function prepare_package();
 
@@ -484,11 +487,12 @@ abstract class 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}
+ * @see also portfolio_caller_base
  *
  * @package core_portfolio
  * @category portfolio
index e6fbac6..ba2ca56 100644 (file)
@@ -26,7 +26,9 @@ defined('MOODLE_INTERNAL') || die();
 
 /**
  * Top level portfolio exception.
- * Sometimes caught and re-thrown as {@see portfolio_export_exception}
+ *
+ * Sometimes caught and re-thrown as portfolio_export_exception
+ * @see portfolio_export_exception
  *
  * @package core_portfolio
  * @category portfolio
@@ -90,7 +92,9 @@ 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}
+ *
+ * Usually caught and rethrown as portfolio_export_exception
+ * @see portfolio_export_exception
  *
  * @package core_portfolio
  * @category portfolio
@@ -101,7 +105,9 @@ 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}
+ *
+ * Usually caught and rethrown as portfolio_export_exception
+ * @see portfolio_export_exception
  *
  * @package core_portfolio
  * @category portfolio
index 02c1b00..81727f5 100644 (file)
@@ -28,12 +28,13 @@ 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
+ *
+ * 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
+ * @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
@@ -695,7 +696,9 @@ 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
+     * Use write_new_file or copy_existing_file externally
+     * @see write_new_file
+     * @see copy_existing_file
      *
      * @param string $name filename of new record
      * @return object
index e38acd7..56f6ece 100644 (file)
@@ -16,6 +16,7 @@
 
 /**
  * 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.
  *
@@ -29,6 +30,7 @@ defined('MOODLE_INTERNAL') || die();
 
 /**
  * Base class to inherit from.
+ *
  * Do not use this anywhere in supported_formats
  *
  * @package core_portfolio
@@ -63,9 +65,10 @@ abstract class portfolio_format {
     /**
      * 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}.
+     * Usually involves the path given by get_file_directory.
      * This is not supported in subclasses of portfolio_format_file
      * since they're all just single files.
+     * @see get_file_directory
      *
      * @param stored_file $file file information object
      * @param array $options array of options to pass. can contain:
@@ -166,9 +169,10 @@ class portfolio_format_file extends portfolio_format {
     /**
      * 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}.
+     * Usually involves the path given by get_file_directory.
      * This is not supported in subclasses of portfolio_format_file
      * since they're all just single files.
+     * @see get_file_directory
      *
      * @param stored_file $file informations object
      * @param array $options array of options to pass. can contain:
@@ -222,6 +226,7 @@ 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.
  *
  * @package core_portfolio
@@ -265,6 +270,7 @@ class portfolio_format_plainhtml extends portfolio_format_file {
 
 /**
  * Video format
+ *
  * For portfolio plugins that support videos specifically
  *
  * @package core_portfolio
@@ -289,6 +295,7 @@ 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
  *
@@ -333,6 +340,7 @@ class portfolio_format_text extends portfolio_format_file {
 
 /**
  * Base class for rich formats.
+ *
  * These are multipart - eg things with attachments
  *
  * @package core_portfolio
@@ -355,6 +363,7 @@ abstract class portfolio_format_rich extends portfolio_format {
 
 /**
  * Richhtml - html with attachments.
+ *
  * The most commonly used rich format
  * eg inline images
  *
@@ -379,9 +388,10 @@ class portfolio_format_richhtml extends portfolio_format_rich {
     /**
      * 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}.
+     * Usually involves the path given by get_file_directory.
      * This is not supported in subclasses of portfolio_format_file
      * since they're all just single files.
+     * @see get_file_directory
      *
      * @param stored_file $file information for existing file
      * @param array $options array of options to pass. can contain:
@@ -513,6 +523,7 @@ class portfolio_format_leap2a extends portfolio_format_rich {
 
 /**
  * 'PDF format', subtype of file.
+ *
  * For portfolio plugins that support PDFs specifically.
  *
  * @package core_portfolio
@@ -534,6 +545,7 @@ class portfolio_format_pdf extends portfolio_format_file {
 
 /**
  * 'Document format', subtype of file.
+ *
  * For portfolio plugins that support documents specifically.
  *
  * @package core_portfolio
@@ -560,6 +572,7 @@ class portfolio_format_document extends portfolio_format_file {
 
 /**
  * 'Spreadsheet format', subtype of file.
+ *
  * For portfolio plugins that support spreadsheets specifically.
  *
  * @package core_portfolio
@@ -585,6 +598,7 @@ class portfolio_format_spreadsheet extends portfolio_format_file {
 
 /**
  * 'Presentation format', subtype of file.
+ *
  * For portfolio plugins that support presentation specifically.
  *
  * @package core_portfolio
index 57e8a89..c1da6ab 100644 (file)
@@ -27,6 +27,7 @@ defined('MOODLE_INTERNAL') || die();
 
 /**
  * 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')
@@ -205,6 +206,7 @@ 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
  *
  * @package core_portfolio
index db93ef2..7a779fa 100644 (file)
@@ -30,6 +30,7 @@ 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
@@ -128,6 +129,7 @@ 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:
  * {@link http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_admin_config}
@@ -250,6 +252,7 @@ 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:
@@ -303,6 +306,7 @@ 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.
  *
index 592d606..d86d1ea 100644 (file)
@@ -31,8 +31,11 @@ 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}
+ * either via portfolio_plugin_pull_base or portfolio_plugin_push_base
+ * @see portfolio_plugin_pull_base
+ * @see portfolio_plugin_push_base
  *
  * @package core_portfolio
  * @category portfolio
@@ -147,7 +150,8 @@ abstract class portfolio_plugin_base {
     /**
      * 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}
+     * you <b>must</b> implement admin_config_form.
+     * @see admin_config_form
      *
      * @return bool
      */
@@ -158,7 +162,8 @@ abstract class portfolio_plugin_base {
     /**
      * 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}
+     * you <b>must</b> implement user_config_form
+     * @see user_config_form
      *
      * @return bool
      */
@@ -169,7 +174,8 @@ abstract class portfolio_plugin_base {
     /**
      * Does this plugin need configuration during export time?
      * If you override this to return true,
-     * you <b>must</b> implement {@see export_config_form}
+     * you <b>must</b> implement export_config_form.
+     * @see export_config_form
      *
      * @return bool
      */
@@ -201,8 +207,9 @@ abstract class portfolio_plugin_base {
      * 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}
+     * Keys must be in get_allowed_export_config
      * This is deliberately not final (see boxnet plugin)
+     * @see get_allowed_export_config
      *
      * @param array $config named array of config items to set.
      */
@@ -261,7 +268,8 @@ abstract class portfolio_plugin_base {
      * 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.
+     * get_tempfiles to get the list of files.
+     * @see get_tempfiles
      *
      */
     public abstract function prepare_package();
@@ -321,7 +329,7 @@ abstract class portfolio_plugin_base {
     /**
      * mform to display to the user in their profile
      * if your plugin can't be configured by the user,
-     * (see {@see has_user_config}).
+     * @see has_user_config.
      * Don't bother overriding this function
      *
      * @param moodleform $mform passed by reference, add elements to it
@@ -331,7 +339,7 @@ abstract class portfolio_plugin_base {
     /**
      * mform to display to the admin configuring the plugin.
      * If your plugin can't be configured by the admin,
-     * (@see has_admin_config).
+     * @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),
@@ -353,7 +361,7 @@ abstract class portfolio_plugin_base {
     /**
      * 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}.
+     * @see has_export_config.
      * Don't bother overrideing this function
      *
      * @param moodleform $mform passed by reference, add elements to it.
@@ -376,8 +384,9 @@ abstract class portfolio_plugin_base {
      * 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
+     * and post_control is called before the rest of the processing
      * for the stage is done,
+     * @see post_control
      *
      * @param int $stage to steal control *before* (see constants PARAM_STAGE_*}
      * @return bool
@@ -733,6 +742,7 @@ abstract class portfolio_plugin_base {
 
 /**
  * Class to inherit from for 'push' type plugins
+ *
  * Eg: those that send the file via a HTTP post or whatever
  *
  * @package core_portfolio
@@ -754,6 +764,7 @@ abstract class portfolio_plugin_push_base extends portfolio_plugin_base {
 
 /**
  * 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.
@@ -780,7 +791,7 @@ abstract class portfolio_plugin_pull_base extends portfolio_plugin_base {
     /**
      * 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}
+     * @see verify_file_request_params
      *
      * @return string the url
      */
index dbb8498..dc7473a 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -54,6 +53,7 @@ require_once($CFG->libdir . '/portfolio/caller.php');
 
 /**
  * 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)
@@ -178,12 +178,13 @@ class portfolio_add_button {
      * 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}
+     * @see portfolio_most_specific_formats for more information
+     * @see portfolio_format_from_mimetype
      *
      * @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.
+     *                       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) {
@@ -648,7 +649,7 @@ function portfolio_supported_formats_intersect($callerformats, $pluginformats) {
  * Tiny helper to figure out whether a portfolio format is abstract
  *
  * @param string $format the format to test
- * @retun bool
+ * @return bool
  */
 function portfolio_format_is_abstract($format) {
     if (class_exists($format)) {
@@ -1186,8 +1187,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
+ * This is much more lightweight than 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.
+ * @see existing_exports
  *
  * @param int $userid the user to check for
  * @return array