Document what ParserOutput::setProperty() is for

Change-Id: I88735b1ebc9b8423b4fbe7b196dfc914f95818fd

diff --git a/includes/parser/ParserOutput.php b/includes/parser/ParserOutput.php
index b6bcf63..28d07f1 100644 (file)
--- a/includes/parser/ParserOutput.php
+++ b/includes/parser/ParserOutput.php
@@ -346,7 +346,45 @@ class ParserOutput extends CacheTime {
        }
 
        /**
-        * Set a property to be cached in the DB
+        * Set a property to be stored in the page_props database table.
+        *
+        * page_props is a key value store indexed by the page ID. This allows
+        * the parser to set a property on a page which can then be quickly
+        * retrieved given the page ID or via a DB join when given the page
+        * title.
+        *
+        * setProperty() is thus used to propagate properties from the parsed
+        * page to request contexts other than a page view of the currently parsed
+        * article.
+        *
+        * Some applications examples:
+        *
+        *   * To implement hidden categories, hiding pages from category listings
+        *     by storing a property.
+        *
+        *   * Overriding the displayed article title.
+        *   @see ParserOutput::setDisplayTitle()
+        *
+        *   * To implement image tagging, for example displaying an icon on an
+        *     image thumbnail to indicate that it is listed for deletion on
+        *     Wikimedia Commons.
+        *     This is not actually implemented, yet but would be pretty cool.
+        *
+        * Do not use setProperty() to set a property which is only used in a
+        * context where the ParserOutput object itself is already available, for
+        * example a normal page view. There is no need to save such a property
+        * in the database since it the text is already parsed. You can just hook
+        * OutputPageParserOutput and get your data out of the ParserOutput object.
+        *
+        * If you are writing an extension where you want to set
+        * a property in the parser which is used by an OutputPageParserOutput hook,
+        * just use a custom variable within the ParserOutput object:
+        *
+        * @par Example:
+        * @code
+        *    $parser->getOutput()->my_ext_foo = '...';
+        * @endcode
+        *
         */
        public function setProperty( $name, $value ) {
                $this->mProperties[$name] = $value;