MDL-50491 filters: deprectate old methods & improve comments

Two methods relating to the old way of doing format_text caching have
been deprecated.

filter/upgrade.txt

@@ -1,6 +1,12 @@
 This file describes API changes in core filter API and plugins,
 information provided here is intended especially for developers.
 
+=== 3.0 ===
+
+* Methods filter_manager::text_filtering_hash and moodle_text_filter::hash have been
+  deprecated. There were use by the old Moodle filtered text caching system
+  that was removed several releases ago.
+
 === 2.7 ===
 
 * Finally filter may use $PAGE and $OUTPUT, yay!

lib/filterlib.php

@@ -17,7 +17,7 @@
 /**
  * Library functions for managing text filter plugins.
  *
- * @package    core_filter
+ * @package   core
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -48,19 +48,18 @@ define('TEXTFILTER_EXCL_SEPARATOR', '-%-');
  *
  * This class is a singleton.
  *
- * @package    core_filter
  * @copyright  1999 onwards Martin Dougiamas  {@link http://moodle.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class filter_manager {
     /**
-     * @var array This list of active filters, by context, for filtering content.
+     * @var moodle_text_filter[][] This list of active filters, by context, for filtering content.
      * An array contextid => array of filter objects.
      */
     protected $textfilters = array();
 
     /**
-     * @var array This list of active filters, by context, for filtering strings.
+     * @var moodle_text_filter[][] This list of active filters, by context, for filtering strings.
      * An array contextid => array of filter objects.
      */
     protected $stringfilters = array();
@@ -68,14 +67,19 @@ class filter_manager {
     /** @var array Exploded version of $CFG->stringfilters. */
     protected $stringfilternames = array();
 
-    /** @var object Holds the singleton instance. */
+    /** @var filter_manager Holds the singleton instance. */
     protected static $singletoninstance;
 
+    /**
+     * Constructor. Protected. Use {@link instance()} instead.
+     */
     protected function __construct() {
         $this->stringfilternames = filter_get_string_filters();
     }
 
     /**
+     * Factory method. Use this to get the filter manager.
+     *
      * @return filter_manager the singleton instance.
      */
     public static function instance() {
@@ -112,7 +116,7 @@ class filter_manager {
     /**
      * Load all the filters required by this context.
      *
-     * @param object $context
+     * @param context $context the context.
      */
     protected function load_filters($context) {
         $filters = filter_get_active_in_context($context);
@@ -156,10 +160,10 @@ class filter_manager {
     }
 
     /**
-     * @todo Document this function
+     * Apply a list of filters to some content.
      * @param string $text
-     * @param array $filterchain
+     * @param moodle_text_filter[] $filterchain
-     * @param array $options options passed to the filters
+     * @param array $options options passed to the filters.
      * @return string $text
      */
     protected function apply_filter_chain($text, $filterchain, array $options = array()) {
@@ -170,9 +174,10 @@ class filter_manager {
     }
 
     /**
-     * @todo Document this function
+     * Get all the filters that apply to a given context for calls to format_text.
-     * @param object $context
+     *
-     * @return object A text filter
+     * @param context $context
+     * @return moodle_text_filter[] A text filter
      */
     protected function get_text_filters($context) {
         if (!isset($this->textfilters[$context->id])) {
@@ -182,9 +187,10 @@ class filter_manager {
     }
 
     /**
-     * @todo Document this function
+     * Get all the filters that apply to a given context for calls to format_string.
-     * @param object $context
+     *
-     * @return object A string filter
+     * @param context $context the context.
+     * @return moodle_text_filter[] A text filter
      */
     protected function get_string_filters($context) {
         if (!isset($this->stringfilters[$context->id])) {
@@ -197,7 +203,7 @@ class filter_manager {
      * Filter some text
      *
      * @param string $text The text to filter
-     * @param object $context
+     * @param context $context the context.
      * @param array $options options passed to the filters
      * @return string resulting text
      */
@@ -212,7 +218,7 @@ class filter_manager {
      * Filter a piece of string
      *
      * @param string $string The text to filter
-     * @param context $context
+     * @param context $context the context.
      * @return string resulting string
      */
     public function filter_string($string, $context) {
@@ -220,11 +226,14 @@ class filter_manager {
     }
 
     /**
-     * @todo Document this function
+     * @deprecated Since Moodle 3.0. This was used by the old text filtering system, but no more.
-     * @param context $context
+     * @param context $context the context.
-     * @return object A string filter
+     * @return string the hash.
      */
     public function text_filtering_hash($context) {
+        debugging('filter_manager::text_filtering_hash() is deprecated. ' .
+                'It was an internal part of the old format_text caching, ' .
+                'and should not have been called from other code.', DEBUG_DEVELOPER);
         $filters = $this->get_text_filters($context);
         $hashes = array();
         foreach ($filters as $filter) {
@@ -257,57 +266,48 @@ class filter_manager {
     }
 }
 
+
 /**
  * Filter manager subclass that does nothing. Having this simplifies the logic
  * of format_text, etc.
  *
- * @todo Document this class
- *
- * @package    core_filter
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class null_filter_manager {
-    /**
-     * @return string
-     */
     public function filter_text($text, $context, $options) {
         return $text;
     }
 
-    /**
-     * @return string
-     */
     public function filter_string($string, $context) {
         return $string;
     }
 
-    /**
-     * @return string
-     */
     public function text_filtering_hash() {
+        debugging('filter_manager::text_filtering_hash() is deprecated. ' .
+                'It was an internal part of the old format_text caching, ' .
+                'and should not have been called from other code.', DEBUG_DEVELOPER);
         return '';
     }
 }
 
+
 /**
- * Filter manager subclass that tacks how much work it does.
+ * Filter manager subclass that tracks how much work it does.
  *
- * @todo Document this class
- *
- * @package    core_filter
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class performance_measuring_filter_manager extends filter_manager {
-    /** @var int */
+    /** @var int number of filter objects created. */
     protected $filterscreated = 0;
+
+    /** @var int number of calls to filter_text. */
     protected $textsfiltered = 0;
+
+    /** @var int number of calls to filter_string. */
     protected $stringsfiltered = 0;
 
-    /**
-     * Unloads all filters and other cached information
-     */
     protected function unload_all_filters() {
         parent::unload_all_filters();
         $this->filterscreated = 0;
@@ -315,40 +315,24 @@ class performance_measuring_filter_manager extends filter_manager {
         $this->stringsfiltered = 0;
     }
 
-    /**
-     * @param string $filtername
-     * @param object $context
-     * @param mixed $localconfig
-     * @return mixed
-     */
     protected function make_filter_object($filtername, $context, $localconfig) {
         $this->filterscreated++;
         return parent::make_filter_object($filtername, $context, $localconfig);
     }
 
-    /**
-     * @param string $text
-     * @param object $context
-     * @param array $options options passed to the filters
-     * @return mixed
-     */
     public function filter_text($text, $context, array $options = array()) {
         $this->textsfiltered++;
         return parent::filter_text($text, $context, $options);
     }
 
-    /**
-     * @param string $string
-     * @param object $context
-     * @return mixed
-     */
     public function filter_string($string, $context) {
         $this->stringsfiltered++;
         return parent::filter_string($string, $context);
     }
 
     /**
-     * @return array
+     * Return performance information, in the form required by {@link get_performance_info()}.
+     * @return array the performance info.
      */
     public function get_performance_summary() {
         return array(array(
@@ -365,17 +349,18 @@ class performance_measuring_filter_manager extends filter_manager {
     }
 }
 
+
 /**
  * Base class for text filters. You just need to override this class and
  * implement the filter method.
  *
- * @package    core_filter
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class moodle_text_filter {
-    /** @var object The context we are in. */
+    /** @var context The context we are in. */
     protected $context;
+
     /** @var array Any local configuration for this filter in this context. */
     protected $localconfig;
 
@@ -391,9 +376,13 @@ abstract class moodle_text_filter {
     }
 
     /**
+     * @deprecated Since Moodle 3.0. This was used by the old text filtering system, but no more.
      * @return string The class name of the current class
      */
     public function hash() {
+        debugging('moodle_text_filter::hash() is deprecated. ' .
+                'It was an internal part of the old format_text caching, ' .
+                'and should not have been called from other code.', DEBUG_DEVELOPER);
         return __CLASS__;
     }
 
@@ -425,13 +414,12 @@ abstract class moodle_text_filter {
     public abstract function filter($text, array $options = array());
 }
 
+
 /**
  * This is just a little object to define a phrase and some instructions
  * for how to process it.  Filters can create an array of these to pass
  * to the filter_phrases function below.
  *
- * @package    core
- * @subpackage filter
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  **/