From: daniel <daniel.kinzler@wikimedia.de>
Date: Fri, 16 Oct 2015 18:03:33 +0000 (+0200)
Subject: Clarify that ParserOutput::getDisplayTitle() returns HTML.
X-Git-Tag: 1.31.0-rc.0~9371^2
X-Git-Url: http://git.cyclocoop.org/%28?a=commitdiff_plain;h=d0343297648456277cc3b8136e2658177bb9cc27;p=lhc%2Fweb%2Fwiklou.git

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 23a7de4825..8571cd79a9 100644
--- 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 3745238de8..37b45a67a6 100644
--- 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();