Clarify that ParserOutput::getDisplayTitle() returns HTML.

This change only improves documentation, it does not touch code.

For reference:
* CoreParserFunctions::displaytitle generates HTML, with &, < and so on
property escaped. OutputPage::setPageTitle() treats the input as wikitext,
which works for both plain text and HTML.

* Wikibase calls ParserOutput::setDisplayTitle() with HTML including <span>
structures.

In the API action=query&prop=pageprops returns HTML. There doesn't seem to
be a good place to document that fact, though.

Change-Id: I043b26b82f066abe2830a81d3bc073543b3748d8

diff --git a/includes/EditPage.php b/includes/EditPage.php
index 23a7de4..8571cd7 100644 (file)
--- a/includes/EditPage.php
+++ b/includes/EditPage.php
@@ -2188,6 +2188,8 @@ class EditPage {
                }
 
                # Use the title defined by DISPLAYTITLE magic word when present
+               # NOTE: getDisplayTitle() returns HTML while getPrefixedText() returns plain text.
+               #       setPageTitle() treats the input as wikitext, which should be safe in either case.
                $displayTitle = isset( $this->mParserOutput ) ? $this->mParserOutput->getDisplayTitle() : false;
                if ( $displayTitle === false ) {
                        $displayTitle = $contextTitle->getPrefixedText();

diff --git a/includes/parser/ParserOutput.php b/includes/parser/ParserOutput.php
index 3745238..37b45a6 100644 (file)
--- a/includes/parser/ParserOutput.php
+++ b/includes/parser/ParserOutput.php
@@ -44,7 +44,7 @@ class ParserOutput extends CacheTime {
        public $mIndicators = array();
 
        /**
-        * @var string $mTitleText Title text of the chosen language variant
+        * @var string $mTitleText Title text of the chosen language variant, as HTML.
         */
        public $mTitleText;
 
@@ -700,9 +700,13 @@ class ParserOutput extends CacheTime {
 
        /**
         * Override the title to be used for display
-        * -- this is assumed to have been validated
+        *
+        * @note this is assumed to have been validated
         * (check equal normalisation, etc.)
         *
+        * @note this is expected to be safe HTML,
+        * ready to be served to the client.
+        *
         * @param string $text Desired title text
         */
        public function setDisplayTitle( $text ) {
@@ -711,9 +715,12 @@ class ParserOutput extends CacheTime {
        }
 
        /**
-        * Get the title to be used for display
+        * Get the title to be used for display.
+        *
+        * As per the contract of setDisplayTitle(), this is safe HTML,
+        * ready to be served to the client.
         *
-        * @return string
+        * @return string HTML
         */
        public function getDisplayTitle() {
                $t = $this->getTitleText();