MDL-30989 portfolio: Fixed up phpdocs

lib/portfolio/caller.php

@@ -30,8 +30,8 @@
 /**
  * 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 @@ public final function set($field, &$value) {
     /**
      * 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 @@ public function get_export_summary() {
     /**
      * 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 @@ 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.
  * {@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

lib/portfolio/exceptions.php

@@ -26,7 +26,9 @@
 
 /**
  * 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 @@ public function __construct($exporter, $errorcode, $module=null, $continue=null,
 
 /**
  * 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

lib/portfolio/exporter.php

@@ -28,12 +28,13 @@
 /**
  * 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 @@ public static function rewaken_object($id) {
     /**
      * 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

lib/portfolio/formats.php

@@ -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 @@
 
 /**
  * Base class to inherit from.
+ *
  * Do not use this anywhere in supported_formats
  *
  * @package core_portfolio
@@ -63,9 +65,10 @@ public static function get_file_directory() {
     /**
      * 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 @@ public static function get_file_directory() {
     /**
      * 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 @@ public static function conflicts($format) {
 
 /**
  * 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 @@ public static function conflicts($format) {
 
 /**
  * Video format
+ *
  * For portfolio plugins that support videos specifically
  *
  * @package core_portfolio
@@ -289,6 +295,7 @@ public static function mimetypes() {
 
 /**
  * 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 @@ public static function conflicts($format ) {
 
 /**
  * Base class for rich formats.
+ *
  * These are multipart - eg things with attachments
  *
  * @package core_portfolio
@@ -355,6 +363,7 @@ public static function mimetypes() {
 
 /**
  * Richhtml - html with attachments.
+ *
  * The most commonly used rich format
  * eg inline images
  *
@@ -379,9 +388,10 @@ public static function get_file_directory() {
     /**
      * 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 @@ public static function manifest_name() {
 
 /**
  * 'PDF format', subtype of file.
+ *
  * For portfolio plugins that support PDFs specifically.
  *
  * @package core_portfolio
@@ -534,6 +545,7 @@ public static function mimetypes() {
 
 /**
  * 'Document format', subtype of file.
+ *
  * For portfolio plugins that support documents specifically.
  *
  * @package core_portfolio
@@ -560,6 +572,7 @@ public static function mimetypes() {
 
 /**
  * 'Spreadsheet format', subtype of file.
+ *
  * For portfolio plugins that support spreadsheets specifically.
  *
  * @package core_portfolio
@@ -585,6 +598,7 @@ public static function mimetypes() {
 
 /**
  * 'Presentation format', subtype of file.
+ *
  * For portfolio plugins that support presentation specifically.
  *
  * @package core_portfolio

lib/portfolio/formats/leap2a/lib.php

@@ -27,6 +27,7 @@
 
 /**
  * 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 @@ public function to_xml() {
 
 /**
  * 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

lib/portfolio/forms.php

@@ -30,6 +30,7 @@
 
 /**
  * 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 @@ public function validation($data) {
 
 /**
  * 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 @@ public function validation($data) {
 
 /**
  * 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 @@ public function validation($data) {
 
 /**
  * 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.
  *