MDL-30989 portfolio: Fixed up phpdocs

2012-02-15 15:33:06 +13:00
parent 9e7ff1476c
commit 18cdcdbf89
8 changed files with 81 additions and 35 deletions
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
 *
@@ -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
     */
@@ -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