From 68064001299557613aee3c7bddc57251e4ceed3f Mon Sep 17 00:00:00 2001
From: =?utf8?q?Thiemo=20M=C3=A4ttig?= <thiemo.maettig@wikimedia.de>
Date: Mon, 3 Mar 2014 18:08:05 +0100
Subject: [PATCH] Added and updated Doxygen comments in content handler and
 diff namespaces

Reasons for touching this are:
* "@param type $var" were mixed in a lot of places. Both works but the
  MediaWiki coding conventions suggest that specific order.
* Things like String and Bool aren't objects and shouldn't be uppercase.
* Tried to fill missing types in "@param $var".
* Tried to fill missing descriptions in "@return type" when I could.
* Removed duplicate descriptions if a @see is sufficend.
* Removed useless descriptions ("isUsefull returns true if usefull").
* Removed useless @return void.
* Replaces mixed[] with array (does have the exact same meaning).
* Tried to find better replacements for "varargs", phpDocumentor
  suggest $var,...
* Order should be @since, @param, @throws, @return, @see. This is the
  order Doxygen renders this.

There is always more to do but I think this is already much better
than before. Please feel free to put more change sets on top of mine
or request more changes by adding comments.

Change-Id: I05262ce06caabf79f68772302524ac91bbead1c6
---
 includes/Message.php                          | 309 ++++++++++++------
 includes/content/AbstractContent.php          | 194 +++++------
 includes/content/Content.php                  | 113 ++++---
 includes/content/ContentHandler.php           | 182 ++++++-----
 includes/content/CssContent.php               |  19 +-
 includes/content/CssContentHandler.php        |  20 ++
 includes/content/JavaScriptContent.php        |  11 +-
 includes/content/JavaScriptContentHandler.php |  20 ++
 includes/content/MessageContent.php           |  55 ++--
 includes/content/TextContent.php              |  60 ++--
 includes/content/TextContentHandler.php       |  26 +-
 includes/content/WikitextContent.php          |  77 +++--
 includes/content/WikitextContentHandler.php   |  27 +-
 includes/diff/ArrayDiffFormatter.php          |   4 +-
 includes/diff/DairikiDiff.php                 | 110 ++++---
 includes/diff/DiffFormatter.php               |  45 ++-
 includes/diff/DifferenceEngine.php            |  76 +++--
 includes/diff/TableDiffFormatter.php          |  60 +++-
 includes/diff/UnifiedDiffFormatter.php        |  19 +-
 includes/diff/WikiDiff3.php                   |   3 +
 20 files changed, 881 insertions(+), 549 deletions(-)

diff --git a/includes/Message.php b/includes/Message.php
index dd22844dc3..7c9b095a29 100644
--- a/includes/Message.php
+++ b/includes/Message.php
@@ -157,9 +157,12 @@
  * @since 1.17
  */
 class Message {
+
 	/**
 	 * In which language to get this message. True, which is the default,
 	 * means the current interface language, false content language.
+	 *
+	 * @var bool
 	 */
 	protected $interface = true;
 
@@ -172,12 +175,12 @@ class Message {
 	protected $language = null;
 
 	/**
-	 * The message key.
+	 * @var string|string[] The message key or array of keys.
 	 */
 	protected $key;
 
 	/**
-	 * List of parameters which will be substituted into the message.
+	 * @var array List of parameters which will be substituted into the message.
 	 */
 	protected $parameters = array();
 
@@ -189,21 +192,23 @@ class Message {
 	 * * block-parse
 	 * * parse (default)
 	 * * plain
+	 *
+	 * @var string
 	 */
 	protected $format = 'parse';
 
 	/**
-	 * Whether database can be used.
+	 * @var bool Whether database can be used.
 	 */
 	protected $useDatabase = true;
 
 	/**
-	 * Title object to use as context
+	 * @var Title Title object to use as context.
 	 */
 	protected $title = null;
 
 	/**
-	 * Content object representing the message
+	 * @var Content Content object representing the message.
 	 */
 	protected $content = null;
 
@@ -213,11 +218,11 @@ class Message {
 	protected $message;
 
 	/**
-	 * Constructor.
 	 * @since 1.17
-	 * @param $key: message key, or array of message keys to try and use the first non-empty message for
-	 * @param array $params message parameters
-	 * @return Message: $this
+	 *
+	 * @param string|string[] $key Message key or array of message keys to try and use the first
+	 * non-empty message for.
+	 * @param array $params Message parameters.
 	 */
 	public function __construct( $key, $params = array() ) {
 		global $wgLang;
@@ -227,7 +232,7 @@ class Message {
 	}
 
 	/**
-	 * Returns the message key
+	 * Returns the message key or the first from an array of message keys.
 	 *
 	 * @since 1.21
 	 *
@@ -244,18 +249,18 @@ class Message {
 	}
 
 	/**
-	 * Returns the message parameters
+	 * Returns the message parameters.
 	 *
 	 * @since 1.21
 	 *
-	 * @return string[]
+	 * @return array
 	 */
 	public function getParams() {
 		return $this->parameters;
 	}
 
 	/**
-	 * Returns the message format
+	 * Returns the message format.
 	 *
 	 * @since 1.21
 	 *
@@ -269,10 +274,13 @@ class Message {
 	 * Factory function that is just wrapper for the real constructor. It is
 	 * intended to be used instead of the real constructor, because it allows
 	 * chaining method calls, while new objects don't.
+	 *
 	 * @since 1.17
-	 * @param string $key message key
-	 * @param Varargs: parameters as Strings
-	 * @return Message: $this
+	 *
+	 * @param string|string[] $key Message key or array of keys.
+	 * @param mixed [$param,...] Parameters as strings.
+	 *
+	 * @return Message
 	 */
 	public static function newFromKey( $key /*...*/ ) {
 		$params = func_get_args();
@@ -284,9 +292,13 @@ class Message {
 	 * Factory function accepting multiple message keys and returning a message instance
 	 * for the first message which is non-empty. If all messages are empty then an
 	 * instance of the first message key is returned.
+	 *
 	 * @since 1.18
-	 * @param Varargs: message keys (or first arg as an array of all the message keys)
-	 * @return Message: $this
+	 *
+	 * @param string|string[] [$keys,...] Message keys, or first argument as an array of all the
+	 * message keys.
+	 *
+	 * @return Message
 	 */
 	public static function newFallbackSequence( /*...*/ ) {
 		$keys = func_get_args();
@@ -304,9 +316,13 @@ class Message {
 
 	/**
 	 * Adds parameters to the parameter list of this message.
+	 *
 	 * @since 1.17
-	 * @param Varargs: parameters as Strings, or a single argument that is an array of Strings
-	 * @return Message: $this
+	 *
+	 * @param mixed [$params,...] Parameters as strings, or a single argument that is
+	 * an array of strings.
+	 *
+	 * @return Message $this
 	 */
 	public function params( /*...*/ ) {
 		$args = func_get_args();
@@ -323,9 +339,13 @@ class Message {
 	 * In other words the parsing process cannot access the contents
 	 * of this type of parameter, and you need to make sure it is
 	 * sanitized beforehand.  The parser will see "$n", instead.
+	 *
 	 * @since 1.17
-	 * @param Varargs: raw parameters as Strings (or single argument that is an array of raw parameters)
-	 * @return Message: $this
+	 *
+	 * @param mixed [$params,...] Raw parameters as strings, or a single argument that is
+	 * an array of raw parameters.
+	 *
+	 * @return Message $this
 	 */
 	public function rawParams( /*...*/ ) {
 		$params = func_get_args();
@@ -341,9 +361,13 @@ class Message {
 	/**
 	 * Add parameters that are numeric and will be passed through
 	 * Language::formatNum before substitution
+	 *
 	 * @since 1.18
-	 * @param Varargs: numeric parameters (or single argument that is array of numeric parameters)
-	 * @return Message: $this
+	 *
+	 * @param mixed [$param,...] Numeric parameters, or a single argument that is
+	 * an array of numeric parameters.
+	 *
+	 * @return Message $this
 	 */
 	public function numParams( /*...*/ ) {
 		$params = func_get_args();
@@ -359,9 +383,13 @@ class Message {
 	/**
 	 * Add parameters that are durations of time and will be passed through
 	 * Language::formatDuration before substitution
+	 *
 	 * @since 1.22
-	 * @param Varargs: numeric parameters (or single argument that is array of numeric parameters)
-	 * @return Message: $this
+	 *
+	 * @param int|int[] [$param,...] Duration parameters, or a single argument that is
+	 * an array of duration parameters.
+	 *
+	 * @return Message $this
 	 */
 	public function durationParams( /*...*/ ) {
 		$params = func_get_args();
@@ -377,9 +405,13 @@ class Message {
 	/**
 	 * Add parameters that are expiration times and will be passed through
 	 * Language::formatExpiry before substitution
+	 *
 	 * @since 1.22
-	 * @param Varargs: numeric parameters (or single argument that is array of numeric parameters)
-	 * @return Message: $this
+	 *
+	 * @param string|string[] [$param,...] Expiry parameters, or a single argument that is
+	 * an array of expiry parameters.
+	 *
+	 * @return Message $this
 	 */
 	public function expiryParams( /*...*/ ) {
 		$params = func_get_args();
@@ -395,9 +427,13 @@ class Message {
 	/**
 	 * Add parameters that are time periods and will be passed through
 	 * Language::formatTimePeriod before substitution
+	 *
 	 * @since 1.22
-	 * @param Varargs: numeric parameters (or single argument that is array of numeric parameters)
-	 * @return Message: $this
+	 *
+	 * @param number|number[] [$param,...] Time period parameters, or a single argument that is
+	 * an array of time period parameters.
+	 *
+	 * @return Message $this
 	 */
 	public function timeperiodParams( /*...*/ ) {
 		$params = func_get_args();
@@ -413,9 +449,13 @@ class Message {
 	/**
 	 * Add parameters that are file sizes and will be passed through
 	 * Language::formatSize before substitution
+	 *
 	 * @since 1.22
-	 * @param Varargs: numeric parameters (or single argument that is array of numeric parameters)
-	 * @return Message: $this
+	 *
+	 * @param int|int[] [$param,...] Size parameters, or a single argument that is
+	 * an array of size parameters.
+	 *
+	 * @return Message $this
 	 */
 	public function sizeParams( /*...*/ ) {
 		$params = func_get_args();
@@ -431,9 +471,13 @@ class Message {
 	/**
 	 * Add parameters that are bitrates and will be passed through
 	 * Language::formatBitrate before substitution
+	 *
 	 * @since 1.22
-	 * @param Varargs: numeric parameters (or single argument that is array of numeric parameters)
-	 * @return Message: $this
+	 *
+	 * @param int|int[] [$param,...] Bit rate parameters, or a single argument that is
+	 * an array of bit rate parameters.
+	 *
+	 * @return Message $this
 	 */
 	public function bitrateParams( /*...*/ ) {
 		$params = func_get_args();
@@ -448,9 +492,12 @@ class Message {
 
 	/**
 	 * Set the language and the title from a context object
+	 *
 	 * @since 1.19
+	 *
 	 * @param $context IContextSource
-	 * @return Message: $this
+	 *
+	 * @return Message $this
 	 */
 	public function setContext( IContextSource $context ) {
 		$this->inLanguage( $context->getLanguage() );
@@ -464,10 +511,13 @@ class Message {
 	 * Request the message in any language that is supported.
 	 * As a side effect interface message status is unconditionally
 	 * turned off.
+	 *
 	 * @since 1.17
-	 * @param $lang Mixed: language code or Language object.
+	 *
+	 * @param Language|string $lang Language code or Language object.
+	 *
+	 * @return Message $this
 	 * @throws MWException
-	 * @return Message: $this
 	 */
 	public function inLanguage( $lang ) {
 		if ( $lang instanceof Language || $lang instanceof StubUserLang ) {
@@ -489,9 +539,11 @@ class Message {
 	/**
 	 * Request the message in the wiki's content language,
 	 * unless it is disabled for this message.
+	 *
 	 * @since 1.17
 	 * @see $wgForceUIMsgAsContentMsg
-	 * @return Message: $this
+	 *
+	 * @return Message $this
 	 */
 	public function inContentLanguage() {
 		global $wgForceUIMsgAsContentMsg;
@@ -508,31 +560,40 @@ class Message {
 	/**
 	 * Allows manipulating the interface message flag directly.
 	 * Can be used to restore the flag after setting a language.
-	 * @param $value bool
-	 * @return Message: $this
+	 *
 	 * @since 1.20
+	 *
+	 * @param bool $interface
+	 *
+	 * @return Message $this
 	 */
-	public function setInterfaceMessageFlag( $value ) {
-		$this->interface = (bool)$value;
+	public function setInterfaceMessageFlag( $interface ) {
+		$this->interface = (bool)$interface;
 		return $this;
 	}
 
 	/**
 	 * Enable or disable database use.
+	 *
 	 * @since 1.17
-	 * @param $value Boolean
-	 * @return Message: $this
+	 *
+	 * @param bool $useDatabase
+	 *
+	 * @return Message $this
 	 */
-	public function useDatabase( $value ) {
-		$this->useDatabase = (bool)$value;
+	public function useDatabase( $useDatabase ) {
+		$this->useDatabase = (bool)$useDatabase;
 		return $this;
 	}
 
 	/**
 	 * Set the Title object to use as context when transforming the message
+	 *
 	 * @since 1.18
+	 *
 	 * @param $title Title object
-	 * @return Message: $this
+	 *
+	 * @return Message $this
 	 */
 	public function title( $title ) {
 		$this->title = $title;
@@ -541,6 +602,7 @@ class Message {
 
 	/**
 	 * Returns the message as a Content object.
+	 *
 	 * @return Content
 	 */
 	public function content() {
@@ -553,8 +615,10 @@ class Message {
 
 	/**
 	 * Returns the message parsed from wikitext to HTML.
+	 *
 	 * @since 1.17
-	 * @return String: HTML
+	 *
+	 * @return string HTML
 	 */
 	public function toString() {
 		$string = $this->fetchMessage();
@@ -605,8 +669,10 @@ class Message {
 	 * Magic method implementation of the above (for PHP >= 5.2.0), so we can do, eg:
 	 *     $foo = Message::get( $key );
 	 *     $string = "<abbr>$foo</abbr>";
+	 *
 	 * @since 1.18
-	 * @return String
+	 *
+	 * @return string
 	 */
 	public function __toString() {
 		// PHP doesn't allow __toString to throw exceptions and will
@@ -630,9 +696,11 @@ class Message {
 	}
 
 	/**
-	 * Fully parse the text from wikitext to HTML
+	 * Fully parse the text from wikitext to HTML.
+	 *
 	 * @since 1.17
-	 * @return String parsed HTML
+	 *
+	 * @return string Parsed HTML.
 	 */
 	public function parse() {
 		$this->format = 'parse';
@@ -641,8 +709,10 @@ class Message {
 
 	/**
 	 * Returns the message text. {{-transformation is done.
+	 *
 	 * @since 1.17
-	 * @return String: Unescaped message text.
+	 *
+	 * @return string Unescaped message text.
 	 */
 	public function text() {
 		$this->format = 'text';
@@ -651,8 +721,10 @@ class Message {
 
 	/**
 	 * Returns the message text as-is, only parameters are substituted.
+	 *
 	 * @since 1.17
-	 * @return String: Unescaped untransformed message text.
+	 *
+	 * @return string Unescaped untransformed message text.
 	 */
 	public function plain() {
 		$this->format = 'plain';
@@ -661,8 +733,10 @@ class Message {
 
 	/**
 	 * Returns the parsed message text which is always surrounded by a block element.
+	 *
 	 * @since 1.17
-	 * @return String: HTML
+	 *
+	 * @return string HTML
 	 */
 	public function parseAsBlock() {
 		$this->format = 'block-parse';
@@ -672,8 +746,10 @@ class Message {
 	/**
 	 * Returns the message text. {{-transformation is done and the result
 	 * is escaped excluding any raw parameters.
+	 *
 	 * @since 1.17
-	 * @return String: Escaped message text.
+	 *
+	 * @return string Escaped message text.
 	 */
 	public function escaped() {
 		$this->format = 'escaped';
@@ -682,8 +758,10 @@ class Message {
 
 	/**
 	 * Check whether a message key has been defined currently.
+	 *
 	 * @since 1.17
-	 * @return Bool: true if it is and false if not.
+	 *
+	 * @return bool
 	 */
 	public function exists() {
 		return $this->fetchMessage() !== false;
@@ -691,9 +769,11 @@ class Message {
 
 	/**
 	 * Check whether a message does not exist, or is an empty string
+	 *
 	 * @since 1.18
-	 * @return Bool: true if is is and false if not
 	 * @todo FIXME: Merge with isDisabled()?
+	 *
+	 * @return bool
 	 */
 	public function isBlank() {
 		$message = $this->fetchMessage();
@@ -701,9 +781,11 @@ class Message {
 	}
 
 	/**
-	 * Check whether a message does not exist, is an empty string, or is "-"
+	 * Check whether a message does not exist, is an empty string, or is "-".
+	 *
 	 * @since 1.18
-	 * @return Bool: true if it is and false if not
+	 *
+	 * @return bool
 	 */
 	public function isDisabled() {
 		$message = $this->fetchMessage();
@@ -712,72 +794,89 @@ class Message {
 
 	/**
 	 * @since 1.17
-	 * @param $value
-	 * @return array
+	 *
+	 * @param mixed $raw
+	 *
+	 * @return array Array with a single "raw" key.
 	 */
-	public static function rawParam( $value ) {
-		return array( 'raw' => $value );
+	public static function rawParam( $raw ) {
+		return array( 'raw' => $raw );
 	}
 
 	/**
 	 * @since 1.18
-	 * @param $value
-	 * @return array
+	 *
+	 * @param mixed $num
+	 *
+	 * @return array Array with a single "num" key.
 	 */
-	public static function numParam( $value ) {
-		return array( 'num' => $value );
+	public static function numParam( $num ) {
+		return array( 'num' => $num );
 	}
 
 	/**
 	 * @since 1.22
-	 * @param $value
-	 * @return array
+	 *
+	 * @param int $duration
+	 *
+	 * @return int[] Array with a single "duration" key.
 	 */
-	public static function durationParam( $value ) {
-		return array( 'duration' => $value );
+	public static function durationParam( $duration ) {
+		return array( 'duration' => $duration );
 	}
 
 	/**
 	 * @since 1.22
-	 * @param $value
-	 * @return array
+	 *
+	 * @param string $expiry
+	 *
+	 * @return string[] Array with a single "expiry" key.
 	 */
-	public static function expiryParam( $value ) {
-		return array( 'expiry' => $value );
+	public static function expiryParam( $expiry ) {
+		return array( 'expiry' => $expiry );
 	}
 
 	/**
 	 * @since 1.22
-	 * @param $value
-	 * @return array
+	 *
+	 * @param number $period
+	 *
+	 * @return number[] Array with a single "period" key.
 	 */
-	public static function timeperiodParam( $value ) {
-		return array( 'period' => $value );
+	public static function timeperiodParam( $period ) {
+		return array( 'period' => $period );
 	}
 
 	/**
 	 * @since 1.22
-	 * @param $value
-	 * @return array
+	 *
+	 * @param int $size
+	 *
+	 * @return int[] Array with a single "size" key.
 	 */
-	public static function sizeParam( $value ) {
-		return array( 'size' => $value );
+	public static function sizeParam( $size ) {
+		return array( 'size' => $size );
 	}
 
 	/**
 	 * @since 1.22
-	 * @param $value
-	 * @return array
+	 *
+	 * @param int $bitrate
+	 *
+	 * @return int[] Array with a single "bitrate" key.
 	 */
-	public static function bitrateParam( $value ) {
-		return array( 'bitrate' => $value );
+	public static function bitrateParam( $bitrate ) {
+		return array( 'bitrate' => $bitrate );
 	}
 
 	/**
 	 * Substitutes any parameters into the message text.
+	 *
 	 * @since 1.17
-	 * @param string $message the message text
-	 * @param string $type either before or after
+	 *
+	 * @param string $message The message text.
+	 * @param string $type Either "before" or "after".
+	 *
 	 * @return String
 	 */
 	protected function replaceParameters( $message, $type = 'before' ) {
@@ -794,9 +893,12 @@ class Message {
 
 	/**
 	 * Extracts the parameter type and preprocessed the value if needed.
+	 *
 	 * @since 1.18
-	 * @param string|array $param Parameter as defined in this class.
-	 * @return Tuple(type, value)
+	 *
+	 * @param mixed $param Parameter as defined in this class.
+	 *
+	 * @return array Array with the parameter type (either "before" or "after") and the value.
 	 */
 	protected function extractParam( $param ) {
 		if ( is_array( $param ) ) {
@@ -837,9 +939,12 @@ class Message {
 
 	/**
 	 * Wrapper for what ever method we use to parse wikitext.
+	 *
 	 * @since 1.17
-	 * @param string $string Wikitext message contents
-	 * @return string Wikitext parsed into HTML
+	 *
+	 * @param string $string Wikitext message contents.
+	 *
+	 * @return string Wikitext parsed into HTML.
 	 */
 	protected function parseText( $string ) {
 		$out = MessageCache::singleton()->parse( $string, $this->title, /*linestart*/true, $this->interface, $this->language );
@@ -848,8 +953,11 @@ class Message {
 
 	/**
 	 * Wrapper for what ever method we use to {{-transform wikitext.
+	 *
 	 * @since 1.17
-	 * @param string $string Wikitext message contents
+	 *
+	 * @param string $string Wikitext message contents.
+	 *
 	 * @return string Wikitext with {{-constructs replaced with their values.
 	 */
 	protected function transformText( $string ) {
@@ -857,10 +965,12 @@ class Message {
 	}
 
 	/**
-	 * Wrapper for what ever method we use to get message contents
+	 * Wrapper for what ever method we use to get message contents.
+	 *
 	 * @since 1.17
-	 * @throws MWException
+	 *
 	 * @return string
+	 * @throws MWException If message key array is empty.
 	 */
 	protected function fetchMessage() {
 		if ( !isset( $this->message ) ) {
@@ -899,13 +1009,15 @@ class Message {
  * @since 1.21
  */
 class RawMessage extends Message {
+
 	/**
 	 * Call the parent constructor, then store the key as
 	 * the message.
 	 *
-	 * @param string $key Message to use
-	 * @param array $params Parameters for the message
 	 * @see Message::__construct
+	 *
+	 * @param string|string[] $key Message to use.
+	 * @param array $params Parameters for the message.
 	 */
 	public function __construct( $key, $params = array() ) {
 		parent::__construct( $key, $params );
@@ -925,4 +1037,5 @@ class RawMessage extends Message {
 		}
 		return $this->message;
 	}
+
 }
diff --git a/includes/content/AbstractContent.php b/includes/content/AbstractContent.php
index e1b1f01926..f2f0c9d635 100644
--- a/includes/content/AbstractContent.php
+++ b/includes/content/AbstractContent.php
@@ -43,7 +43,7 @@ abstract class AbstractContent implements Content {
 	protected $model_id;
 
 	/**
-	 * @param string|null $modelId
+	 * @param string $modelId
 	 *
 	 * @since 1.21
 	 */
@@ -52,23 +52,21 @@ abstract class AbstractContent implements Content {
 	}
 
 	/**
-	 * @see Content::getModel
-	 *
 	 * @since 1.21
+	 *
+	 * @see Content::getModel
 	 */
 	public function getModel() {
 		return $this->model_id;
 	}
 
 	/**
-	 * Throws an MWException if $model_id is not the id of the content model
-	 * supported by this Content object.
-	 *
 	 * @since 1.21
 	 *
 	 * @param string $modelId The model to check
 	 *
-	 * @throws MWException
+	 * @throws MWException If the provided ID is not the ID of the content model supported by this
+	 * Content object.
 	 */
 	protected function checkModelID( $modelId ) {
 		if ( $modelId !== $this->model_id ) {
@@ -81,40 +79,40 @@ abstract class AbstractContent implements Content {
 	}
 
 	/**
-	 * @see Content::getContentHandler
-	 *
 	 * @since 1.21
+	 *
+	 * @see Content::getContentHandler
 	 */
 	public function getContentHandler() {
 		return ContentHandler::getForContent( $this );
 	}
 
 	/**
-	 * @see Content::getDefaultFormat
-	 *
 	 * @since 1.21
+	 *
+	 * @see Content::getDefaultFormat
 	 */
 	public function getDefaultFormat() {
 		return $this->getContentHandler()->getDefaultFormat();
 	}
 
 	/**
-	 * @see Content::getSupportedFormats
-	 *
 	 * @since 1.21
+	 *
+	 * @see Content::getSupportedFormats
 	 */
 	public function getSupportedFormats() {
 		return $this->getContentHandler()->getSupportedFormats();
 	}
 
 	/**
-	 * @see Content::isSupportedFormat
+	 * @since 1.21
 	 *
 	 * @param string $format
 	 *
-	 * @since 1.21
+	 * @return bool
 	 *
-	 * @return boolean
+	 * @see Content::isSupportedFormat
 	 */
 	public function isSupportedFormat( $format ) {
 		if ( !$format ) {
@@ -125,13 +123,11 @@ abstract class AbstractContent implements Content {
 	}
 
 	/**
-	 * Throws an MWException if $this->isSupportedFormat( $format ) does not
-	 * return true.
-	 *
 	 * @since 1.21
 	 *
-	 * @param string $format
-	 * @throws MWException
+	 * @param string $format The serialization format to check.
+	 *
+	 * @throws MWException If the format is not supported by this content handler.
 	 */
 	protected function checkFormat( $format ) {
 		if ( !$this->isSupportedFormat( $format ) ) {
@@ -143,48 +139,50 @@ abstract class AbstractContent implements Content {
 	}
 
 	/**
-	 * @see Content::serialize
-	 *
-	 * @param string|null $format
-	 *
 	 * @since 1.21
 	 *
+	 * @param string $format
+	 *
 	 * @return string
+	 *
+	 * @see Content::serialize
 	 */
 	public function serialize( $format = null ) {
 		return $this->getContentHandler()->serializeContent( $this, $format );
 	}
 
 	/**
-	 * @see Content::isEmpty
-	 *
 	 * @since 1.21
 	 *
-	 * @return boolean
+	 * @return bool
+	 *
+	 * @see Content::isEmpty
 	 */
 	public function isEmpty() {
 		return $this->getSize() === 0;
 	}
 
 	/**
-	 * @see Content::isValid
+	 * Subclasses may override this to implement (light weight) validation.
 	 *
 	 * @since 1.21
 	 *
-	 * @return boolean
+	 * @return bool Always true.
+	 *
+	 * @see Content::isValid
 	 */
 	public function isValid() {
 		return true;
 	}
 
 	/**
-	 * @see Content::equals
-	 *
 	 * @since 1.21
 	 *
-	 * @param Content|null $that
+	 * @param Content $that
 	 *
-	 * @return boolean
+	 * @return bool
+	 *
+	 * @see Content::equals
 	 */
 	public function equals( Content $that = null ) {
 		if ( is_null( $that ) ) {
@@ -214,26 +212,19 @@ abstract class AbstractContent implements Content {
 	 * Subclasses may override this to determine the secondary data updates more
 	 * efficiently, preferably without the need to generate a parser output object.
 	 *
-	 * @see Content::getSecondaryDataUpdates()
+	 * @since 1.21
 	 *
-	 * @param $title Title The context for determining the necessary updates
-	 * @param $old Content|null An optional Content object representing the
-	 *    previous content, i.e. the content being replaced by this Content
-	 *    object.
-	 * @param $recursive boolean Whether to include recursive updates (default:
-	 *    false).
-	 * @param $parserOutput ParserOutput|null Optional ParserOutput object.
-	 *    Provide if you have one handy, to avoid re-parsing of the content.
+	 * @param Title $title
+	 * @param Content $old
+	 * @param bool $recursive
+	 * @param ParserOutput $parserOutput
 	 *
-	 * @return Array. A list of DataUpdate objects for putting information
-	 *    about this content object somewhere.
+	 * @return DataUpdate[]
 	 *
-	 * @since 1.21
+	 * @see Content::getSecondaryDataUpdates()
 	 */
-	public function getSecondaryDataUpdates( Title $title,
-		Content $old = null,
-		$recursive = true, ParserOutput $parserOutput = null
-	) {
+	public function getSecondaryDataUpdates( Title $title, Content $old = null,
+		$recursive = true, ParserOutput $parserOutput = null ) {
 		if ( $parserOutput === null ) {
 			$parserOutput = $this->getParserOutput( $title, null, null, false );
 		}
@@ -242,9 +233,11 @@ abstract class AbstractContent implements Content {
 	}
 
 	/**
-	 * @see Content::getRedirectChain
-	 *
 	 * @since 1.21
+	 *
+	 * @return Title[]|null
+	 *
+	 * @see Content::getRedirectChain
 	 */
 	public function getRedirectChain() {
 		global $wgMaxRedirects;
@@ -277,19 +270,26 @@ abstract class AbstractContent implements Content {
 	}
 
 	/**
-	 * @see Content::getRedirectTarget
+	 * Subclasses that implement redirects should override this.
 	 *
 	 * @since 1.21
+	 *
+	 * @return null
+	 *
+	 * @see Content::getRedirectTarget
 	 */
 	public function getRedirectTarget() {
 		return null;
 	}
 
 	/**
-	 * @see Content::getUltimateRedirectTarget
-	 * @note: migrated here from Title::newFromRedirectRecurse
+	 * @note Migrated here from Title::newFromRedirectRecurse.
 	 *
 	 * @since 1.21
+	 *
+	 * @return Title|null
+	 *
+	 * @see Content::getUltimateRedirectTarget
 	 */
 	public function getUltimateRedirectTarget() {
 		$titles = $this->getRedirectChain();
@@ -298,80 +298,93 @@ abstract class AbstractContent implements Content {
 	}
 
 	/**
-	 * @see Content::isRedirect
-	 *
 	 * @since 1.21
 	 *
 	 * @return bool
+	 *
+	 * @see Content::isRedirect
 	 */
 	public function isRedirect() {
 		return $this->getRedirectTarget() !== null;
 	}
 
 	/**
-	 * @see Content::updateRedirect
-	 *
 	 * This default implementation always returns $this.
-	 *
-	 * @param Title $target
+	 * Subclasses that implement redirects should override this.
 	 *
 	 * @since 1.21
 	 *
+	 * @param Title $target
+	 *
 	 * @return Content $this
+	 *
+	 * @see Content::updateRedirect
 	 */
 	public function updateRedirect( Title $target ) {
 		return $this;
 	}
 
 	/**
-	 * @see Content::getSection
-	 *
 	 * @since 1.21
+	 *
+	 * @return null
+	 *
+	 * @see Content::getSection
 	 */
 	public function getSection( $sectionId ) {
 		return null;
 	}
 
 	/**
-	 * @see Content::replaceSection
-	 *
 	 * @since 1.21
+	 *
+	 * @return null
+	 *
+	 * @see Content::replaceSection
 	 */
 	public function replaceSection( $section, Content $with, $sectionTitle = '' ) {
 		return null;
 	}
 
 	/**
-	 * @see Content::preSaveTransform
-	 *
 	 * @since 1.21
+	 *
+	 * @return Content $this
+	 *
+	 * @see Content::preSaveTransform
 	 */
 	public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
 		return $this;
 	}
 
 	/**
-	 * @see Content::addSectionHeader
-	 *
 	 * @since 1.21
+	 *
+	 * @return Content $this
+	 *
+	 * @see Content::addSectionHeader
 	 */
 	public function addSectionHeader( $header ) {
 		return $this;
 	}
 
 	/**
-	 * @see Content::preloadTransform
-	 *
 	 * @since 1.21
+	 *
+	 * @return Content $this
+	 *
+	 * @see Content::preloadTransform
 	 */
 	public function preloadTransform( Title $title, ParserOptions $popts ) {
 		return $this;
 	}
 
 	/**
-	 * @see Content::prepareSave
-	 *
 	 * @since 1.21
+	 *
+	 * @return Status
+	 *
+	 * @see Content::prepareSave
 	 */
 	public function prepareSave( WikiPage $page, $flags, $baseRevId, User $user ) {
 		if ( $this->isValid() ) {
@@ -382,21 +395,16 @@ abstract class AbstractContent implements Content {
 	}
 
 	/**
-	 * @see Content::getDeletionUpdates
-	 *
 	 * @since 1.21
 	 *
-	 * @param $page WikiPage the deleted page
-	 * @param $parserOutput null|ParserOutput optional parser output object
-	 *    for efficient access to meta-information about the content object.
-	 *    Provide if you have one handy.
+	 * @param WikiPage $page
+	 * @param ParserOutput $parserOutput
 	 *
-	 * @return array A list of DataUpdate instances that will clean up the
-	 *    database after deletion.
+	 * @return LinksDeletionUpdate[]
+	 *
+	 * @see Content::getDeletionUpdates
 	 */
-	public function getDeletionUpdates( WikiPage $page,
-		ParserOutput $parserOutput = null
-	) {
+	public function getDeletionUpdates( WikiPage $page, ParserOutput $parserOutput = null ) {
 		return array(
 			new LinksDeletionUpdate( $page ),
 		);
@@ -406,30 +414,28 @@ abstract class AbstractContent implements Content {
 	 * This default implementation always returns false. Subclasses may override
 	 * this to supply matching logic.
 	 *
-	 * @see Content::matchMagicWord
-	 *
 	 * @since 1.21
 	 *
 	 * @param MagicWord $word
 	 *
-	 * @return bool
+	 * @return bool Always false.
+	 *
+	 * @see Content::matchMagicWord
 	 */
 	public function matchMagicWord( MagicWord $word ) {
 		return false;
 	}
 
 	/**
-	 * @see Content::convert()
-	 *
 	 * This base implementation calls the hook ConvertContent to enable custom conversions.
 	 * Subclasses may override this to implement conversion for "their" content model.
 	 *
-	 * @param string $toModel the desired content model, use the CONTENT_MODEL_XXX flags.
-	 * @param string $lossy flag, set to "lossy" to allow lossy conversion. If lossy conversion is
-	 * not allowed, full round-trip conversion is expected to work without losing information.
+	 * @param string $toModel
+	 * @param string $lossy
+	 *
+	 * @return Content|bool
 	 *
-	 * @return Content|bool A content object with the content model $toModel, or false if
-	 * that conversion is not supported.
+	 * @see Content::convert()
 	 */
 	public function convert( $toModel, $lossy = '' ) {
 		if ( $this->getModel() === $toModel ) {
diff --git a/includes/content/Content.php b/includes/content/Content.php
index 947e34819c..075635d330 100644
--- a/includes/content/Content.php
+++ b/includes/content/Content.php
@@ -32,6 +32,7 @@
  * @ingroup Content
  */
 interface Content {
+
 	/**
 	 * @since 1.21
 	 *
@@ -64,8 +65,9 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param int $maxLength Maximum length of the summary text
-	 * @return string The summary text
+	 * @param int $maxLength Maximum length of the summary text.
+	 *
+	 * @return string The summary text.
 	 */
 	public function getTextForSummary( $maxLength = 250 );
 
@@ -132,7 +134,7 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @return Array of supported serialization formats
+	 * @return string[] List of supported serialization formats
 	 */
 	public function getSupportedFormats();
 
@@ -147,7 +149,8 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param string $format The format to check
+	 * @param string $format The serialization format to check.
+	 *
 	 * @return bool Whether the format is supported
 	 */
 	public function isSupportedFormat( $format );
@@ -159,9 +162,9 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $format null|string The desired serialization format (or null for
-	 *    the default format).
-	 * @return string Serialized form of this Content object
+	 * @param string $format The desired serialization format, or null for the default format.
+	 *
+	 * @return string Serialized form of this Content object.
 	 */
 	public function serialize( $format = null );
 
@@ -184,7 +187,7 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @return boolean
+	 * @return bool
 	 */
 	public function isValid();
 
@@ -207,7 +210,8 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $that Content The Content object to compare to
+	 * @param Content $that The Content object to compare to.
+	 *
 	 * @return bool True if this Content object is equal to $that, false otherwise.
 	 */
 	public function equals( Content $that = null );
@@ -242,7 +246,8 @@ interface Content {
 	 * @param bool $hasLinks If it is known whether this content contains
 	 *    links, provide this information here, to avoid redundant parsing to
 	 *    find out.
-	 * @return boolean
+	 *
+	 * @return bool
 	 */
 	public function isCountable( $hasLinks = null );
 
@@ -256,10 +261,10 @@ interface Content {
 	 *       generated parser output, implementations of this method
 	 *       may call ParserOutput::recordOption() on the output object.
 	 *
-	 * @param $title Title The page title to use as a context for rendering
-	 * @param $revId null|int The revision being rendered (optional)
-	 * @param $options null|ParserOptions Any parser options
-	 * @param $generateHtml Boolean Whether to generate HTML (default: true). If false,
+	 * @param Title $title The page title to use as a context for rendering.
+	 * @param int $revId Optional revision ID being rendered.
+	 * @param ParserOptions $options Any parser options.
+	 * @param bool $generateHtml Whether to generate HTML (default: true). If false,
 	 *        the result of calling getText() on the ParserOutput object returned by
 	 *        this method is undefined.
 	 *
@@ -267,8 +272,7 @@ interface Content {
 	 *
 	 * @return ParserOutput
 	 */
-	public function getParserOutput( Title $title,
-		$revId = null,
+	public function getParserOutput( Title $title, $revId = null,
 		ParserOptions $options = null, $generateHtml = true );
 
 	// TODO: make RenderOutput and RenderOptions base classes
@@ -288,24 +292,22 @@ interface Content {
 	 * Subclasses may implement this to determine the necessary updates more
 	 * efficiently, or make use of information about the old content.
 	 *
-	 * @param $title Title The context for determining the necessary updates
-	 * @param $old Content|null An optional Content object representing the
+	 * @param Title $title The context for determining the necessary updates
+	 * @param Content $old An optional Content object representing the
 	 *    previous content, i.e. the content being replaced by this Content
 	 *    object.
-	 * @param $recursive boolean Whether to include recursive updates (default:
+	 * @param bool $recursive Whether to include recursive updates (default:
 	 *    false).
-	 * @param $parserOutput ParserOutput|null Optional ParserOutput object.
+	 * @param ParserOutput $parserOutput Optional ParserOutput object.
 	 *    Provide if you have one handy, to avoid re-parsing of the content.
 	 *
-	 * @return Array. A list of DataUpdate objects for putting information
+	 * @return DataUpdate[] A list of DataUpdate objects for putting information
 	 *    about this content object somewhere.
 	 *
 	 * @since 1.21
 	 */
-	public function getSecondaryDataUpdates( Title $title,
-		Content $old = null,
-		$recursive = true, ParserOutput $parserOutput = null
-	);
+	public function getSecondaryDataUpdates( Title $title, Content $old = null,
+		$recursive = true, ParserOutput $parserOutput = null );
 
 	/**
 	 * Construct the redirect destination from this content and return an
@@ -315,7 +317,7 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @return Array of Titles, with the destination last
+	 * @return Title[]|null List of Titles, with the destination last.
 	 */
 	public function getRedirectChain();
 
@@ -327,7 +329,7 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @return Title: The corresponding Title
+	 * @return Title|null The corresponding Title.
 	 */
 	public function getRedirectTarget();
 
@@ -344,7 +346,7 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @return Title
+	 * @return Title|null
 	 */
 	public function getUltimateRedirectTarget();
 
@@ -364,9 +366,9 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param Title $target the new redirect target
+	 * @param Title $target The new redirect target
 	 *
-	 * @return Content a new Content object with the updated redirect (or $this
+	 * @return Content A new Content object with the updated redirect (or $this
 	 *   if this Content object isn't a redirect)
 	 */
 	public function updateRedirect( Title $target );
@@ -380,7 +382,8 @@ interface Content {
 	 *    The ID "0" retrieves the section before the first heading, "1" the
 	 *    text between the first heading (included) and the second heading
 	 *    (excluded), etc.
-	 * @return Content|Boolean|null The section, or false if no such section
+	 *
+	 * @return Content|bool|null The section, or false if no such section
 	 *    exist, or null if sections are not supported.
 	 */
 	public function getSection( $sectionId );
@@ -391,10 +394,11 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $section null/false or a section number (0, 1, 2, T1, T2...), or "new"
-	 * @param $with Content: new content of the section
-	 * @param string $sectionTitle new section's subject, only if $section is 'new'
-	 * @return string Complete article text, or null if error
+	 * @param mixed $section Null/false or a section number (0, 1, 2, T1, T2...), or "new"
+	 * @param Content $with New content of the section
+	 * @param string $sectionTitle New section's subject, only if $section is 'new'
+	 *
+	 * @return string|null Complete article text, or null if error
 	 */
 	public function replaceSection( $section, Content $with, $sectionTitle = '' );
 
@@ -404,9 +408,10 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $title Title
-	 * @param $user User
-	 * @param $parserOptions null|ParserOptions
+	 * @param Title $title
+	 * @param User $user
+	 * @param ParserOptions $parserOptions
+	 *
 	 * @return Content
 	 */
 	public function preSaveTransform( Title $title, User $user, ParserOptions $parserOptions );
@@ -418,7 +423,8 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $header string
+	 * @param string $header
+	 *
 	 * @return Content
 	 */
 	public function addSectionHeader( $header );
@@ -429,8 +435,9 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $title Title
-	 * @param $parserOptions null|ParserOptions
+	 * @param Title $title
+	 * @param ParserOptions $parserOptions
+	 *
 	 * @return Content
 	 */
 	public function preloadTransform( Title $title, ParserOptions $parserOptions );
@@ -451,15 +458,15 @@ interface Content {
 	 * @since 1.21
 	 *
 	 * @param WikiPage $page The page to be saved.
-	 * @param int $flags bitfield for use with EDIT_XXX constants, see WikiPage::doEditContent()
-	 * @param int $baseRevId the ID of the current revision
+	 * @param int $flags Bitfield for use with EDIT_XXX constants, see WikiPage::doEditContent()
+	 * @param int $baseRevId The ID of the current revision
 	 * @param User $user
 	 *
 	 * @return Status A status object indicating whether the content was
 	 *   successfully prepared for saving. If the returned status indicates
 	 *   an error, a rollback will be performed and the transaction aborted.
 	 *
-	 * @see see WikiPage::doEditContent()
+	 * @see WikiPage::doEditContent()
 	 */
 	public function prepareSave( WikiPage $page, $flags, $baseRevId, User $user );
 
@@ -470,12 +477,12 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $page WikiPage the deleted page
-	 * @param $parserOutput null|ParserOutput optional parser output object
+	 * @param WikiPage $page The deleted page
+	 * @param ParserOutput $parserOutput Optional parser output object
 	 *    for efficient access to meta-information about the content object.
 	 *    Provide if you have one handy.
 	 *
-	 * @return array A list of DataUpdate instances that will clean up the
+	 * @return DataUpdate[] A list of DataUpdate instances that will clean up the
 	 *    database after deletion.
 	 */
 	public function getDeletionUpdates( WikiPage $page,
@@ -486,9 +493,9 @@ interface Content {
 	 *
 	 * @since 1.21
 	 *
-	 * @param MagicWord $word the magic word to match
+	 * @param MagicWord $word The magic word to match
 	 *
-	 * @return bool whether this Content object matches the given magic word.
+	 * @return bool Whether this Content object matches the given magic word.
 	 */
 	public function matchMagicWord( MagicWord $word );
 
@@ -496,9 +503,10 @@ interface Content {
 	 * Converts this content object into another content object with the given content model,
 	 * if that is possible.
 	 *
-	 * @param string $toModel the desired content model, use the CONTENT_MODEL_XXX flags.
-	 * @param string $lossy flag, set to "lossy" to allow lossy conversion. If lossy conversion is
-	 * not allowed, full round-trip conversion is expected to work without losing information.
+	 * @param string $toModel The desired content model, use the CONTENT_MODEL_XXX flags.
+	 * @param string $lossy Optional flag, set to "lossy" to allow lossy conversion. If lossy
+	 * conversion is not allowed, full round-trip conversion is expected to work without losing
+	 * information.
 	 *
 	 * @return Content|bool A content object with the content model $toModel, or false if
 	 * that conversion is not supported.
@@ -509,4 +517,5 @@ interface Content {
 	//   [11:59] <vvv> Hooks are ugly; make CodeHighlighter interface and a
 	//   config to set the class which handles syntax highlighting
 	//   [12:00] <vvv> And default it to a DummyHighlighter
+
 }
diff --git a/includes/content/ContentHandler.php b/includes/content/ContentHandler.php
index 7c51345d8e..defa7da282 100644
--- a/includes/content/ContentHandler.php
+++ b/includes/content/ContentHandler.php
@@ -85,10 +85,11 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $content Content|null
-	 * @return null|string the textual form of $content, if available
-	 * @throws MWException if $content is not an instance of TextContent and
-	 *   $wgContentHandlerTextFallback was set to 'fail'.
+	 * @param Content $content
+	 *
+	 * @throws MWException If the content is not an instance of TextContent and
+	 * wgContentHandlerTextFallback was set to 'fail'.
+	 * @return string|null Textual form of the content, if available.
 	 */
 	public static function getContentText( Content $content = null ) {
 		global $wgContentHandlerTextFallback;
@@ -127,24 +128,21 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param string $text the textual representation, will be
+	 * @param string $text The textual representation, will be
 	 *    unserialized to create the Content object
-	 * @param $title null|Title the title of the page this text belongs to.
+	 * @param Title $title The title of the page this text belongs to.
 	 *    Required if $modelId is not provided.
-	 * @param $modelId null|string the model to deserialize to. If not provided,
+	 * @param string $modelId The model to deserialize to. If not provided,
 	 *    $title->getContentModel() is used.
-	 * @param $format null|string the format to use for deserialization. If not
+	 * @param string $format The format to use for deserialization. If not
 	 *    given, the model's default format is used.
 	 *
-	 * @throws MWException
-	 * @return Content a Content object representing $text
-	 *
-	 * @throws MWException if $model or $format is not supported or if $text can
-	 *    not be unserialized using $format.
+	 * @throws MWException If model ID or format is not supported or if the text can not be
+	 * unserialized using the format.
+	 * @return Content A Content object representing the text.
 	 */
 	public static function makeContent( $text, Title $title = null,
-		$modelId = null, $format = null
-	) {
+		$modelId = null, $format = null ) {
 		if ( is_null( $modelId ) ) {
 			if ( is_null( $title ) ) {
 				throw new MWException( "Must provide a Title object or a content model ID." );
@@ -188,8 +186,9 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $title Title
-	 * @return null|string default model name for the page given by $title
+	 * @param Title $title
+	 *
+	 * @return string Default model name for the page given by $title
 	 */
 	public static function getDefaultModelFor( Title $title ) {
 		// NOTE: this method must not rely on $title->getContentModel() directly or indirectly,
@@ -253,7 +252,8 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $title Title
+	 * @param Title $title
+	 *
 	 * @return ContentHandler
 	 */
 	public static function getForTitle( Title $title ) {
@@ -268,7 +268,8 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $content Content
+	 * @param Content $content
+	 *
 	 * @return ContentHandler
 	 */
 	public static function getForContent( Content $content ) {
@@ -303,9 +304,9 @@ abstract class ContentHandler {
 	 *
 	 * @param string $modelId The ID of the content model for which to get a
 	 *    handler. Use CONTENT_MODEL_XXX constants.
-	 * @return ContentHandler The ContentHandler singleton for handling the
-	 *    model given by $modelId
-	 * @throws MWException if no handler is known for $modelId.
+	 *
+	 * @throws MWException If no handler is known for the model ID.
+	 * @return ContentHandler The ContentHandler singleton for handling the model given by the ID.
 	 */
 	public static function getForModelID( $modelId ) {
 		global $wgContentHandlers;
@@ -353,8 +354,8 @@ abstract class ContentHandler {
 	 * @param string $name The content model ID, as given by a CONTENT_MODEL_XXX
 	 *    constant or returned by Revision::getContentModel().
 	 *
+	 * @throws MWException If the model ID isn't known.
 	 * @return string The content model's localized name.
-	 * @throws MWException if the model id isn't known.
 	 */
 	public static function getLocalizedName( $name ) {
 		// Messages: content-model-wikitext, content-model-text,
@@ -389,7 +390,14 @@ abstract class ContentHandler {
 
 	// ------------------------------------------------------------------------
 
+	/**
+	 * @var string
+	 */
 	protected $mModelID;
+
+	/**
+	 * @var string[]
+	 */
 	protected $mSupportedFormats;
 
 	/**
@@ -398,7 +406,7 @@ abstract class ContentHandler {
 	 * provided as literals by subclass's constructors.
 	 *
 	 * @param string $modelId (use CONTENT_MODEL_XXX constants).
-	 * @param array $formats List for supported serialization formats
+	 * @param string[] $formats List for supported serialization formats
 	 *    (typically as MIME types)
 	 */
 	public function __construct( $modelId, $formats ) {
@@ -415,8 +423,9 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $content Content The Content object to serialize
-	 * @param $format null|String The desired serialization format
+	 * @param Content $content The Content object to serialize
+	 * @param string $format The desired serialization format
+	 *
 	 * @return string Serialized form of the content
 	 */
 	abstract public function serializeContent( Content $content, $format = null );
@@ -426,9 +435,10 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param string $blob serialized form of the content
-	 * @param $format null|String the format used for serialization
-	 * @return Content the Content object created by deserializing $blob
+	 * @param string $blob Serialized form of the content
+	 * @param string $format The format used for serialization
+	 *
+	 * @return Content The Content object created by deserializing $blob
 	 */
 	abstract public function unserializeContent( $blob, $format = null );
 
@@ -454,10 +464,10 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param Title $destination the page to redirect to.
-	 * @param string $text text to include in the redirect, if possible.
+	 * @param Title $destination The page to redirect to.
+	 * @param string $text Text to include in the redirect, if possible.
 	 *
-	 * @return Content
+	 * @return Content Always null.
 	 */
 	public function makeRedirectContent( Title $destination, $text = '' ) {
 		return null;
@@ -469,21 +479,19 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @return String The model ID
+	 * @return string The model ID
 	 */
 	public function getModelID() {
 		return $this->mModelID;
 	}
 
 	/**
-	 * Throws an MWException if $model_id is not the ID of the content model
-	 * supported by this ContentHandler.
-	 *
 	 * @since 1.21
 	 *
 	 * @param string $model_id The model to check
 	 *
-	 * @throws MWException
+	 * @throws MWException If the model ID is not the ID of the content model supported by this
+	 * ContentHandler.
 	 */
 	protected function checkModelID( $model_id ) {
 		if ( $model_id !== $this->mModelID ) {
@@ -500,7 +508,7 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @return array of serialization formats as MIME type like strings
+	 * @return string[] List of serialization formats as MIME type like strings
 	 */
 	public function getSupportedFormats() {
 		return $this->mSupportedFormats;
@@ -515,7 +523,7 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @return string the name of the default serialization format as a MIME type
+	 * @return string The name of the default serialization format as a MIME type
 	 */
 	public function getDefaultFormat() {
 		return $this->mSupportedFormats[0];
@@ -530,11 +538,11 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param string $format the serialization format to check
+	 * @param string $format The serialization format to check
+	 *
 	 * @return bool
 	 */
 	public function isSupportedFormat( $format ) {
-
 		if ( !$format ) {
 			return true; // this means "use the default"
 		}
@@ -543,13 +551,11 @@ abstract class ContentHandler {
 	}
 
 	/**
-	 * Throws an MWException if isSupportedFormat( $format ) is not true.
-	 * Convenient for checking whether a format provided as a parameter is
-	 * actually supported.
+	 * Convenient for checking whether a format provided as a parameter is actually supported.
 	 *
-	 * @param string $format the serialization format to check
+	 * @param string $format The serialization format to check
 	 *
-	 * @throws MWException
+	 * @throws MWException If the format is not supported by this content handler.
 	 */
 	protected function checkFormat( $format ) {
 		if ( !$this->isSupportedFormat( $format ) ) {
@@ -568,7 +574,7 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @return Array
+	 * @return array Always an empty array.
 	 */
 	public function getActionOverrides() {
 		return array();
@@ -579,21 +585,18 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $context IContextSource context to use, anything else will be
-	 *    ignored
-	 * @param $old Integer Old ID we want to show and diff with.
-	 * @param int|string $new String either 'prev' or 'next'.
-	 * @param $rcid Integer ??? FIXME (default 0)
-	 * @param $refreshCache boolean If set, refreshes the diff cache
-	 * @param $unhide boolean If set, allow viewing deleted revs
+	 * @param IContextSource $context Context to use, anything else will be ignored.
+	 * @param int $old Revision ID we want to show and diff with.
+	 * @param int|string $new Either a revision ID or one of the strings 'cur', 'prev' or 'next'.
+	 * @param int $rcid FIXME: Deprecated, no longer used. Defaults to 0.
+	 * @param bool $refreshCache If set, refreshes the diff cache. Defaults to false.
+	 * @param bool $unhide If set, allow viewing deleted revs. Defaults to false.
 	 *
 	 * @return DifferenceEngine
 	 */
-	public function createDifferenceEngine( IContextSource $context,
-		$old = 0, $new = 0,
-		$rcid = 0, # FIXME: use everywhere!
-		$refreshCache = false, $unhide = false
-	) {
+	public function createDifferenceEngine( IContextSource $context, $old = 0, $new = 0,
+		$rcid = 0, //FIXME: Deprecated, no longer used
+		$refreshCache = false, $unhide = false ) {
 		$diffEngineClass = $this->getDiffEngineClass();
 
 		return new $diffEngineClass( $context, $old, $new, $rcid, $refreshCache, $unhide );
@@ -613,10 +616,10 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param Title $title the page to determine the language for.
-	 * @param Content|null $content the page's content, if you have it handy, to avoid reloading it.
+	 * @param Title $title The page to determine the language for.
+	 * @param Content $content The page's content, if you have it handy, to avoid reloading it.
 	 *
-	 * @return Language the page's language
+	 * @return Language The page's language
 	 */
 	public function getPageLanguage( Title $title, Content $content = null ) {
 		global $wgContLang, $wgLang;
@@ -648,10 +651,10 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param Title $title the page to determine the language for.
-	 * @param Content|null $content the page's content, if you have it handy, to avoid reloading it.
+	 * @param Title $title The page to determine the language for.
+	 * @param Content $content The page's content, if you have it handy, to avoid reloading it.
 	 *
-	 * @return Language the page's language for viewing
+	 * @return Language The page's language for viewing
 	 */
 	public function getPageViewLanguage( Title $title, Content $content = null ) {
 		$pageLang = $this->getPageLanguage( $title, $content );
@@ -680,9 +683,9 @@ abstract class ContentHandler {
 	 * @note: this calls the ContentHandlerCanBeUsedOn hook which may be used to override which
 	 * content model can be used where.
 	 *
-	 * @param Title $title the page's title.
+	 * @param Title $title The page's title.
 	 *
-	 * @return bool true if content of this kind can be used on the given page, false otherwise.
+	 * @return bool True if content of this kind can be used on the given page, false otherwise.
 	 */
 	public function canBeUsedOn( Title $title ) {
 		$ok = true;
@@ -704,19 +707,18 @@ abstract class ContentHandler {
 	}
 
 	/**
-	 * Attempts to merge differences between three versions.
-	 * Returns a new Content object for a clean merge and false for failure or
-	 * a conflict.
+	 * Attempts to merge differences between three versions. Returns a new
+	 * Content object for a clean merge and false for failure or a conflict.
 	 *
 	 * This default implementation always returns false.
 	 *
 	 * @since 1.21
 	 *
-	 * @param $oldContent Content|string  String
-	 * @param $myContent Content|string   String
-	 * @param $yourContent Content|string String
+	 * @param Content|string $oldContent The page's previous content.
+	 * @param Content|string $myContent One of the page's conflicting contents.
+	 * @param Content|string $yourContent One of the page's conflicting contents.
 	 *
-	 * @return Content|Bool
+	 * @return Content|bool Always false.
 	 */
 	public function merge3( Content $oldContent, Content $myContent, Content $yourContent ) {
 		return false;
@@ -727,13 +729,14 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $oldContent Content|null: the previous text of the page.
-	 * @param $newContent Content|null: The submitted text of the page.
+	 * @param Content $oldContent The previous text of the page.
+	 * @param Content $newContent The submitted text of the page.
 	 * @param int $flags Bit mask: a bit mask of flags submitted for the edit.
 	 *
 	 * @return string An appropriate auto-summary, or an empty string.
 	 */
-	public function getAutosummary( Content $oldContent = null, Content $newContent = null, $flags ) {
+	public function getAutosummary( Content $oldContent = null, Content $newContent = null,
+		$flags ) {
 		// Decide what kind of auto-summary is needed.
 
 		// Redirect auto-summaries
@@ -799,8 +802,9 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $title Title: the page's title
-	 * @param &$hasHistory Boolean: whether the page has a history
+	 * @param Title $title The page's title
+	 * @param bool &$hasHistory Whether the page has a history
+	 *
 	 * @return mixed String containing deletion reason or empty string, or
 	 *    boolean false if no revision occurred
 	 *
@@ -907,9 +911,9 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $current Revision The current text
-	 * @param $undo Revision The revision to undo
-	 * @param $undoafter Revision Must be an earlier revision than $undo
+	 * @param Revision $current The current text
+	 * @param Revision $undo The revision to undo
+	 * @param Revision $undoafter Must be an earlier revision than $undo
 	 *
 	 * @return mixed String on success, false on failure
 	 */
@@ -980,7 +984,7 @@ abstract class ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @return bool
+	 * @return bool Always false.
 	 */
 	public function isParserCacheSupported() {
 		return false;
@@ -993,7 +997,7 @@ abstract class ContentHandler {
 	 * Content models that return true here should also implement
 	 * Content::getSection, Content::replaceSection, etc. to handle sections..
 	 *
-	 * @return boolean whether sections are supported.
+	 * @return bool Always false.
 	 */
 	public function supportsSections() {
 		return false;
@@ -1006,7 +1010,7 @@ abstract class ContentHandler {
 	 * Content models that return true here should also implement
 	 * ContentHandler::makeRedirectContent to return a Content object.
 	 *
-	 * @return boolean whether redirects are supported.
+	 * @return bool Always false.
 	 */
 	public function supportsRedirects() {
 		return false;
@@ -1038,13 +1042,13 @@ abstract class ContentHandler {
 	 * hook function, a new Content object is constructed from the new
 	 * text.
 	 *
-	 * @param string $event event name
-	 * @param array $args parameters passed to hook functions
-	 * @param bool $warn whether to log a warning.
+	 * @param string $event Event name
+	 * @param array $args Parameters passed to hook functions
+	 * @param bool $warn Whether to log a warning.
 	 *                    Default to self::$enableDeprecationWarnings.
 	 *                    May be set to false for testing.
 	 *
-	 * @return Boolean True if no handler aborted the hook
+	 * @return bool True if no handler aborted the hook
 	 *
 	 * @see ContentHandler::$enableDeprecationWarnings
 	 */
diff --git a/includes/content/CssContent.php b/includes/content/CssContent.php
index 03cc2d005c..5fc2c9f158 100644
--- a/includes/content/CssContent.php
+++ b/includes/content/CssContent.php
@@ -31,6 +31,10 @@
  * @ingroup Content
  */
 class CssContent extends TextContent {
+
+	/**
+	 * @param string $text CSS code.
+	 */
 	public function __construct( $text ) {
 		parent::__construct( $text, CONTENT_MODEL_CSS );
 	}
@@ -39,10 +43,13 @@ class CssContent extends TextContent {
 	 * Returns a Content object with pre-save transformations applied using
 	 * Parser::preSaveTransform().
 	 *
-	 * @param $title Title
-	 * @param $user User
-	 * @param $popts ParserOptions
-	 * @return Content
+	 * @param Title $title
+	 * @param User $user
+	 * @param ParserOptions $popts
+	 *
+	 * @return CssContent
+	 *
+	 * @see TextContent::preSaveTransform
 	 */
 	public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
 		global $wgParser;
@@ -54,6 +61,9 @@ class CssContent extends TextContent {
 		return new CssContent( $pst );
 	}
 
+	/**
+	 * @return string CSS wrapped in a <pre> tag.
+	 */
 	protected function getHtml() {
 		$html = "";
 		$html .= "<pre class=\"mw-code mw-css\" dir=\"ltr\">\n";
@@ -62,4 +72,5 @@ class CssContent extends TextContent {
 
 		return $html;
 	}
+
 }
diff --git a/includes/content/CssContentHandler.php b/includes/content/CssContentHandler.php
index 7becabb888..85059a8911 100644
--- a/includes/content/CssContentHandler.php
+++ b/includes/content/CssContentHandler.php
@@ -28,16 +28,33 @@
  * @ingroup Content
  */
 class CssContentHandler extends TextContentHandler {
+
+	/**
+	 * @param string $modelId
+	 */
 	public function __construct( $modelId = CONTENT_MODEL_CSS ) {
 		parent::__construct( $modelId, array( CONTENT_FORMAT_CSS ) );
 	}
 
+	/**
+	 * @param string $text
+	 * @param string $format
+	 *
+	 * @return CssContent
+	 *
+	 * @see ContentHandler::unserializeContent()
+	 */
 	public function unserializeContent( $text, $format = null ) {
 		$this->checkFormat( $format );
 
 		return new CssContent( $text );
 	}
 
+	/**
+	 * @return CssContent A new CssContent object with empty text.
+	 *
+	 * @see ContentHandler::makeEmptyContent()
+	 */
 	public function makeEmptyContent() {
 		return new CssContent( '' );
 	}
@@ -47,6 +64,7 @@ class CssContentHandler extends TextContentHandler {
 	 *
 	 * @param Title $title
 	 * @param Content $content
+	 *
 	 * @return Language wfGetLangObj( 'en' )
 	 *
 	 * @see ContentHandler::getPageLanguage()
@@ -60,6 +78,7 @@ class CssContentHandler extends TextContentHandler {
 	 *
 	 * @param Title $title
 	 * @param Content $content
+	 *
 	 * @return Language wfGetLangObj( 'en' )
 	 *
 	 * @see ContentHandler::getPageViewLanguage()
@@ -67,4 +86,5 @@ class CssContentHandler extends TextContentHandler {
 	public function getPageViewLanguage( Title $title, Content $content = null ) {
 		return wfGetLangObj( 'en' );
 	}
+
 }
diff --git a/includes/content/JavaScriptContent.php b/includes/content/JavaScriptContent.php
index 2ae572bec0..11a470e1e4 100644
--- a/includes/content/JavaScriptContent.php
+++ b/includes/content/JavaScriptContent.php
@@ -31,6 +31,10 @@
  * @ingroup Content
  */
 class JavaScriptContent extends TextContent {
+
+	/**
+	 * @param string $text JavaScript code.
+	 */
 	public function __construct( $text ) {
 		parent::__construct( $text, CONTENT_MODEL_JAVASCRIPT );
 	}
@@ -42,7 +46,8 @@ class JavaScriptContent extends TextContent {
 	 * @param Title $title
 	 * @param User $user
 	 * @param ParserOptions $popts
-	 * @return Content
+	 *
+	 * @return JavaScriptContent
 	 */
 	public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
 		global $wgParser;
@@ -55,6 +60,9 @@ class JavaScriptContent extends TextContent {
 		return new JavaScriptContent( $pst );
 	}
 
+	/**
+	 * @return string JavaScript wrapped in a <pre> tag.
+	 */
 	protected function getHtml() {
 		$html = "";
 		$html .= "<pre class=\"mw-code mw-js\" dir=\"ltr\">\n";
@@ -63,4 +71,5 @@ class JavaScriptContent extends TextContent {
 
 		return $html;
 	}
+
 }
diff --git a/includes/content/JavaScriptContentHandler.php b/includes/content/JavaScriptContentHandler.php
index 064c422f85..2e98976b9f 100644
--- a/includes/content/JavaScriptContentHandler.php
+++ b/includes/content/JavaScriptContentHandler.php
@@ -28,16 +28,33 @@
  * @todo make ScriptContentHandler base class, do highlighting stuff there?
  */
 class JavaScriptContentHandler extends TextContentHandler {
+
+	/**
+	 * @param string $modelId
+	 */
 	public function __construct( $modelId = CONTENT_MODEL_JAVASCRIPT ) {
 		parent::__construct( $modelId, array( CONTENT_FORMAT_JAVASCRIPT ) );
 	}
 
+	/**
+	 * @param string $text
+	 * @param string $format
+	 *
+	 * @return JavaScriptContent
+	 *
+	 * @see ContentHandler::unserializeContent()
+	 */
 	public function unserializeContent( $text, $format = null ) {
 		$this->checkFormat( $format );
 
 		return new JavaScriptContent( $text );
 	}
 
+	/**
+	 * @return JavaScriptContent A new JavaScriptContent object with empty text.
+	 *
+	 * @see ContentHandler::makeEmptyContent()
+	 */
 	public function makeEmptyContent() {
 		return new JavaScriptContent( '' );
 	}
@@ -47,6 +64,7 @@ class JavaScriptContentHandler extends TextContentHandler {
 	 *
 	 * @param Title $title
 	 * @param Content $content
+	 *
 	 * @return Language wfGetLangObj( 'en' )
 	 *
 	 * @see ContentHandler::getPageLanguage()
@@ -60,6 +78,7 @@ class JavaScriptContentHandler extends TextContentHandler {
 	 *
 	 * @param Title $title
 	 * @param Content $content
+	 *
 	 * @return Language wfGetLangObj( 'en' )
 	 *
 	 * @see ContentHandler::getPageViewLanguage()
@@ -67,4 +86,5 @@ class JavaScriptContentHandler extends TextContentHandler {
 	public function getPageViewLanguage( Title $title, Content $content = null ) {
 		return wfGetLangObj( 'en' );
 	}
+
 }
diff --git a/includes/content/MessageContent.php b/includes/content/MessageContent.php
index e780846cfa..b601344ba4 100644
--- a/includes/content/MessageContent.php
+++ b/includes/content/MessageContent.php
@@ -34,14 +34,15 @@
  * @ingroup Content
  */
 class MessageContent extends AbstractContent {
+
 	/**
 	 * @var Message
 	 */
 	protected $mMessage;
 
 	/**
-	 * @param Message|String $msg A Message object, or a message key
-	 * @param array|null $params An optional array of message parameters
+	 * @param Message|string $msg A Message object, or a message key.
+	 * @param string[] $params An optional array of message parameters.
 	 */
 	public function __construct( $msg, $params = null ) {
 		# XXX: messages may be wikitext, html or plain text! and maybe even something else entirely.
@@ -59,18 +60,18 @@ class MessageContent extends AbstractContent {
 	}
 
 	/**
-	 * Returns the message as rendered HTML
+	 * Fully parse the text from wikitext to HTML.
 	 *
-	 * @return string The message text, parsed into html
+	 * @return string Parsed HTML.
 	 */
 	public function getHtml() {
 		return $this->mMessage->parse();
 	}
 
 	/**
-	 * Returns the message as rendered HTML
+	 * Returns the message text. {{-transformation is done.
 	 *
-	 * @return string The message text, parsed into html
+	 * @return string Unescaped message text.
 	 */
 	public function getWikitext() {
 		return $this->mMessage->text();
@@ -87,6 +88,8 @@ class MessageContent extends AbstractContent {
 	}
 
 	/**
+	 * @return string
+	 *
 	 * @see Content::getTextForSearchIndex
 	 */
 	public function getTextForSearchIndex() {
@@ -94,6 +97,8 @@ class MessageContent extends AbstractContent {
 	}
 
 	/**
+	 * @return string
+	 *
 	 * @see Content::getWikitextForTransclusion
 	 */
 	public function getWikitextForTransclusion() {
@@ -101,6 +106,10 @@ class MessageContent extends AbstractContent {
 	}
 
 	/**
+	 * @param int $maxLength Maximum length of the summary text, defaults to 250.
+	 *
+	 * @return string The summary text.
+	 *
 	 * @see Content::getTextForSummary
 	 */
 	public function getTextForSummary( $maxlength = 250 ) {
@@ -108,18 +117,18 @@ class MessageContent extends AbstractContent {
 	}
 
 	/**
-	 * @see Content::getSize
-	 *
 	 * @return int
+	 *
+	 * @see Content::getSize
 	 */
 	public function getSize() {
 		return strlen( $this->mMessage->plain() );
 	}
 
 	/**
-	 * @see Content::copy
-	 *
 	 * @return Content. A copy of this object
+	 *
+	 * @see Content::copy
 	 */
 	public function copy() {
 		// MessageContent is immutable (because getNativeData() returns a clone of the Message object)
@@ -127,29 +136,28 @@ class MessageContent extends AbstractContent {
 	}
 
 	/**
-	 * @see Content::isCountable
-	 *
 	 * @param bool $hasLinks
-	 * @return bool false
+	 *
+	 * @return bool Always false.
+	 *
+	 * @see Content::isCountable
 	 */
 	public function isCountable( $hasLinks = null ) {
 		return false;
 	}
 
 	/**
-	 * @see Content::getParserOutput
+	 * @param Title $title Unused.
+	 * @param int $revId Unused.
+	 * @param ParserOptions $options Unused.
+	 * @param bool $generateHtml Whether to generate HTML (default: true).
 	 *
-	 * @param Title $title
-	 * @param int $revId Optional revision ID
-	 * @param ParserOptions $options
-	 * @param bool $generateHtml Wether to generate HTML
 	 * @return ParserOutput
+	 *
+	 * @see Content::getParserOutput
 	 */
-	public function getParserOutput(
-		Title $title, $revId = null,
-		ParserOptions $options = null, $generateHtml = true
-	) {
-
+	public function getParserOutput( Title $title, $revId = null,
+		ParserOptions $options = null, $generateHtml = true ) {
 		if ( $generateHtml ) {
 			$html = $this->getHtml();
 		} else {
@@ -160,4 +168,5 @@ class MessageContent extends AbstractContent {
 
 		return $po;
 	}
+
 }
diff --git a/includes/content/TextContent.php b/includes/content/TextContent.php
index 068b15028a..b0da62df3f 100644
--- a/includes/content/TextContent.php
+++ b/includes/content/TextContent.php
@@ -33,6 +33,11 @@
  * @ingroup Content
  */
 class TextContent extends AbstractContent {
+
+	/**
+	 * @param string $text
+	 * @param string $model_id
+	 */
 	public function __construct( $text, $model_id = CONTENT_MODEL_TEXT ) {
 		parent::__construct( $model_id );
 
@@ -50,6 +55,11 @@ class TextContent extends AbstractContent {
 		$this->mText = $text;
 	}
 
+	/**
+	 * @note Mutable subclasses MUST override this to return a copy!
+	 *
+	 * @return Content $this
+	 */
 	public function copy() {
 		return $this; # NOTE: this is ok since TextContent are immutable.
 	}
@@ -81,10 +91,10 @@ class TextContent extends AbstractContent {
 	 * Returns true if this content is not a redirect, and $wgArticleCountMethod
 	 * is "any".
 	 *
-	 * @param bool $hasLinks if it is known whether this content contains links,
+	 * @param bool $hasLinks If it is known whether this content contains links,
 	 * provide this information here, to avoid redundant parsing to find out.
 	 *
-	 * @return bool True if the content is countable
+	 * @return bool
 	 */
 	public function isCountable( $hasLinks = null ) {
 		global $wgArticleCountMethod;
@@ -103,7 +113,7 @@ class TextContent extends AbstractContent {
 	/**
 	 * Returns the text represented by this Content object, as a string.
 	 *
-	 * @return string: the raw text
+	 * @return string The raw text.
 	 */
 	public function getNativeData() {
 		$text = $this->mText;
@@ -114,7 +124,7 @@ class TextContent extends AbstractContent {
 	/**
 	 * Returns the text represented by this Content object, as a string.
 	 *
-	 * @return string: the raw text
+	 * @return string The raw text.
 	 */
 	public function getTextForSearchIndex() {
 		return $this->getNativeData();
@@ -126,7 +136,7 @@ class TextContent extends AbstractContent {
 	 *
 	 * @note: this allows any text-based content to be transcluded as if it was wikitext.
 	 *
-	 * @return string|false: the raw text, or null if the conversion failed
+	 * @return string|false The raw text, or false if the conversion failed.
 	 */
 	public function getWikitextForTransclusion() {
 		$wikitext = $this->convert( CONTENT_MODEL_WIKITEXT, 'lossy' );
@@ -142,9 +152,10 @@ class TextContent extends AbstractContent {
 	 * Returns a Content object with pre-save transformations applied.
 	 * This implementation just trims trailing whitespace.
 	 *
-	 * @param $title Title
-	 * @param $user User
-	 * @param $popts ParserOptions
+	 * @param Title $title
+	 * @param User $user
+	 * @param ParserOptions $popts
+	 *
 	 * @return Content
 	 */
 	public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
@@ -159,9 +170,9 @@ class TextContent extends AbstractContent {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $that Content: The other content object to compare this content
+	 * @param Content $that The other content object to compare this content
 	 * object to.
-	 * @param $lang Language: The language object to use for text segmentation.
+	 * @param Language $lang The language object to use for text segmentation.
 	 *    If not given, $wgContentLang is used.
 	 *
 	 * @return Diff A diff representing the changes that would have to be
@@ -194,17 +205,15 @@ class TextContent extends AbstractContent {
 	 * Returns a generic ParserOutput object, wrapping the HTML returned by
 	 * getHtml().
 	 *
-	 * @param $title Title Context title for parsing
-	 * @param int|null $revId Revision ID (for {{REVISIONID}})
-	 * @param $options ParserOptions|null Parser options
+	 * @param Title $title Context title for parsing
+	 * @param int $revId Revision ID (for {{REVISIONID}})
+	 * @param ParserOptions $options Parser options
 	 * @param bool $generateHtml Whether or not to generate HTML
 	 *
-	 * @return ParserOutput representing the HTML form of the text
+	 * @return ParserOutput Representing the HTML form of the text.
 	 */
-	public function getParserOutput( Title $title,
-		$revId = null,
-		ParserOptions $options = null, $generateHtml = true
-	) {
+	public function getParserOutput( Title $title, $revId = null,
+		ParserOptions $options = null, $generateHtml = true ) {
 		global $wgParser, $wgTextModelsToParse;
 
 		if ( !$options ) {
@@ -249,7 +258,7 @@ class TextContent extends AbstractContent {
 	 * Generates a syntax-highlighted version of the content, as HTML.
 	 * Used by the default implementation of getHtml().
 	 *
-	 * @return string an HTML representation of the content's markup
+	 * @return string A HTML representation of the content's markup
 	 */
 	protected function getHighlightHtml() {
 		# TODO: make Highlighter interface, use highlighter here, if available
@@ -257,17 +266,15 @@ class TextContent extends AbstractContent {
 	}
 
 	/**
-	 * @see Content::convert()
-	 *
 	 * This implementation provides lossless conversion between content models based
 	 * on TextContent.
 	 *
-	 * @param string $toModel the desired content model, use the CONTENT_MODEL_XXX flags.
-	 * @param string $lossy flag, set to "lossy" to allow lossy conversion. If lossy conversion is
-	 * not allowed, full round-trip conversion is expected to work without losing information.
+	 * @param string $toModel
+	 * @param string $lossy
 	 *
-	 * @return Content|bool A content object with the content model $toModel, or false if
-	 * that conversion is not supported.
+	 * @return Content|bool
+	 *
+	 * @see Content::convert()
 	 */
 	public function convert( $toModel, $lossy = '' ) {
 		$converted = parent::convert( $toModel, $lossy );
@@ -286,4 +293,5 @@ class TextContent extends AbstractContent {
 
 		return $converted;
 	}
+
 }
diff --git a/includes/content/TextContentHandler.php b/includes/content/TextContentHandler.php
index 94b5c57865..b728d312ca 100644
--- a/includes/content/TextContentHandler.php
+++ b/includes/content/TextContentHandler.php
@@ -29,10 +29,10 @@
  * @ingroup Content
  */
 class TextContentHandler extends ContentHandler {
+
 	// @codingStandardsIgnoreStart bug 57585
 	public function __construct( $modelId = CONTENT_MODEL_TEXT,
-		$formats = array( CONTENT_FORMAT_TEXT )
-	) {
+		$formats = array( CONTENT_FORMAT_TEXT ) ) {
 		parent::__construct( $modelId, $formats );
 	}
 	// @codingStandardsIgnoreEnd
@@ -40,8 +40,9 @@ class TextContentHandler extends ContentHandler {
 	/**
 	 * Returns the content's text as-is.
 	 *
-	 * @param $content Content
-	 * @param $format string|null
+	 * @param Content $content
+	 * @param string $format The serialization format to check
+	 *
 	 * @return mixed
 	 */
 	public function serializeContent( Content $content, $format = null ) {
@@ -59,11 +60,11 @@ class TextContentHandler extends ContentHandler {
 	 *
 	 * This text-based implementation uses wfMerge().
 	 *
-	 * @param $oldContent Content|string  String
-	 * @param $myContent Content|string   String
-	 * @param $yourContent Content|string String
+	 * @param Content|string $oldContent The page's previous content.
+	 * @param Content|string $myContent One of the page's conflicting contents.
+	 * @param Content|string $yourContent One of the page's conflicting contents.
 	 *
-	 * @return Content|Bool
+	 * @return Content|bool
 	 */
 	public function merge3( Content $oldContent, Content $myContent, Content $yourContent ) {
 		$this->checkModelID( $oldContent->getModel() );
@@ -96,10 +97,10 @@ class TextContentHandler extends ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @param $text   string serialized form of the content
-	 * @param $format null|String the format used for serialization
+	 * @param string $text Serialized form of the content
+	 * @param string $format The format used for serialization
 	 *
-	 * @return Content the TextContent object wrapping $text
+	 * @return Content The TextContent object wrapping $text
 	 */
 	public function unserializeContent( $text, $format = null ) {
 		$this->checkFormat( $format );
@@ -112,9 +113,10 @@ class TextContentHandler extends ContentHandler {
 	 *
 	 * @since 1.21
 	 *
-	 * @return Content
+	 * @return Content A new TextContent object with empty text.
 	 */
 	public function makeEmptyContent() {
 		return new TextContent( '' );
 	}
+
 }
diff --git a/includes/content/WikitextContent.php b/includes/content/WikitextContent.php
index f495c56f5f..605222ef3d 100644
--- a/includes/content/WikitextContent.php
+++ b/includes/content/WikitextContent.php
@@ -31,11 +31,16 @@
  * @ingroup Content
  */
 class WikitextContent extends TextContent {
+
 	public function __construct( $text ) {
 		parent::__construct( $text, CONTENT_MODEL_WIKITEXT );
 	}
 
 	/**
+	 * @param string $section
+	 *
+	 * @return Content|bool|null
+	 *
 	 * @see Content::getSection()
 	 */
 	public function getSection( $section ) {
@@ -52,6 +57,13 @@ class WikitextContent extends TextContent {
 	}
 
 	/**
+	 * @param string $section
+	 * @param Content $with
+	 * @param string $sectionTitle
+	 *
+	 * @throws MWException
+	 * @return Content
+	 *
 	 * @see Content::replaceSection()
 	 */
 	public function replaceSection( $section, Content $with, $sectionTitle = '' ) {
@@ -103,7 +115,8 @@ class WikitextContent extends TextContent {
 	 * Returns a new WikitextContent object with the given section heading
 	 * prepended.
 	 *
-	 * @param $header string
+	 * @param string $header
+	 *
 	 * @return Content
 	 */
 	public function addSectionHeader( $header ) {
@@ -119,9 +132,10 @@ class WikitextContent extends TextContent {
 	 * Returns a Content object with pre-save transformations applied using
 	 * Parser::preSaveTransform().
 	 *
-	 * @param $title Title
-	 * @param $user User
-	 * @param $popts ParserOptions
+	 * @param Title $title
+	 * @param User $user
+	 * @param ParserOptions $popts
+	 *
 	 * @return Content
 	 */
 	public function preSaveTransform( Title $title, User $user, ParserOptions $popts ) {
@@ -138,8 +152,9 @@ class WikitextContent extends TextContent {
 	 * Returns a Content object with preload transformations applied (or this
 	 * object if no transformations apply).
 	 *
-	 * @param $title Title
-	 * @param $popts ParserOptions
+	 * @param Title $title
+	 * @param ParserOptions $popts
+	 *
 	 * @return Content
 	 */
 	public function preloadTransform( Title $title, ParserOptions $popts ) {
@@ -157,7 +172,8 @@ class WikitextContent extends TextContent {
 	 * @note: migrated here from Title::newFromRedirectInternal()
 	 *
 	 * @since 1.23
-	 * @return array 2 elements: Title|null and string
+	 *
+	 * @return array List of two elements: Title|null and string.
 	 */
 	protected function getRedirectTargetAndText() {
 		global $wgMaxRedirects;
@@ -195,10 +211,9 @@ class WikitextContent extends TextContent {
 	/**
 	 * Implement redirect extraction for wikitext.
 	 *
-	 * @return null|Title
+	 * @return Title|null
 	 *
 	 * @see Content::getRedirectTarget
-	 * @see AbstractContent::getRedirectTarget
 	 */
 	public function getRedirectTarget() {
 		list( $title, ) = $this->getRedirectTargetAndText();
@@ -207,8 +222,6 @@ class WikitextContent extends TextContent {
 	}
 
 	/**
-	 * @see Content::updateRedirect()
-	 *
 	 * This implementation replaces the first link on the page with the given new target
 	 * if this Content object is a redirect. Otherwise, this method returns $this.
 	 *
@@ -216,8 +229,9 @@ class WikitextContent extends TextContent {
 	 *
 	 * @param Title $target
 	 *
-	 * @return Content a new Content object with the updated redirect (or $this
-	 *   if this Content object isn't a redirect)
+	 * @return Content
+	 *
+	 * @see Content::updateRedirect()
 	 */
 	public function updateRedirect( Title $target ) {
 		if ( !$this->isRedirect() ) {
@@ -238,14 +252,14 @@ class WikitextContent extends TextContent {
 	 * Returns true if this content is not a redirect, and this content's text
 	 * is countable according to the criteria defined by $wgArticleCountMethod.
 	 *
-	 * @param bool $hasLinks if it is known whether this content contains
+	 * @param bool $hasLinks If it is known whether this content contains
 	 *    links, provide this information here, to avoid redundant parsing to
 	 *    find out (default: null).
-	 * @param $title Title: (default: null)
+	 * @param Title $title Optional title, defaults to the title from the current main request.
 	 *
 	 * @internal param \IContextSource $context context for parsing if necessary
 	 *
-	 * @return bool True if the content is countable
+	 * @return bool
 	 */
 	public function isCountable( $hasLinks = null, Title $title = null ) {
 		global $wgArticleCountMethod;
@@ -279,6 +293,10 @@ class WikitextContent extends TextContent {
 		return false;
 	}
 
+	/**
+	 * @param int $maxlength
+	 * @return string
+	 */
 	public function getTextForSummary( $maxlength = 250 ) {
 		$truncatedtext = parent::getTextForSummary( $maxlength );
 
@@ -294,20 +312,17 @@ class WikitextContent extends TextContent {
 	 * Returns a ParserOutput object resulting from parsing the content's text
 	 * using $wgParser.
 	 *
-	 * @since    1.21
+	 * @since 1.21
 	 *
-	 * @param $title Title
-	 * @param int $revId Revision to pass to the parser (default: null)
-	 * @param $options ParserOptions (default: null)
+	 * @param Title $title * @param int $revId Revision to pass to the parser (default: null)
+	 * @param ParserOptions $options (default: null)
 	 * @param bool $generateHtml (default: false)
-	 *
 	 * @internal param \IContextSource|null $context
-	 * @return ParserOutput representing the HTML form of the text
+	 *
+	 * @return ParserOutput Representing the HTML form of the text
 	 */
-	public function getParserOutput( Title $title,
-		$revId = null,
-		ParserOptions $options = null, $generateHtml = true
-	) {
+	public function getParserOutput( Title $title, $revId = null,
+		ParserOptions $options = null, $generateHtml = true ) {
 		global $wgParser;
 
 		if ( !$options ) {
@@ -334,6 +349,9 @@ class WikitextContent extends TextContent {
 		return $po;
 	}
 
+	/**
+	 * @throws MWException
+	 */
 	protected function getHtml() {
 		throw new MWException(
 			"getHtml() not implemented for wikitext. "
@@ -342,15 +360,16 @@ class WikitextContent extends TextContent {
 	}
 
 	/**
-	 * @see  Content::matchMagicWord()
-	 *
 	 * This implementation calls $word->match() on the this TextContent object's text.
 	 *
 	 * @param MagicWord $word
 	 *
-	 * @return bool whether this Content object matches the given magic word.
+	 * @return bool
+	 *
+	 * @see Content::matchMagicWord()
 	 */
 	public function matchMagicWord( MagicWord $word ) {
 		return $word->match( $this->getNativeData() );
 	}
+
 }
diff --git a/includes/content/WikitextContentHandler.php b/includes/content/WikitextContentHandler.php
index 1e8fd05c1a..5ae3e25d6e 100644
--- a/includes/content/WikitextContentHandler.php
+++ b/includes/content/WikitextContentHandler.php
@@ -29,6 +29,7 @@
  * @ingroup Content
  */
 class WikitextContentHandler extends TextContentHandler {
+
 	public function __construct( $modelId = CONTENT_MODEL_WIKITEXT ) {
 		parent::__construct( $modelId, array( CONTENT_FORMAT_WIKITEXT ) );
 	}
@@ -40,9 +41,9 @@ class WikitextContentHandler extends TextContentHandler {
 	}
 
 	/**
-	 * @see ContentHandler::makeEmptyContent
+	 * @return Content A new WikitextContent object with empty text.
 	 *
-	 * @return Content
+	 * @see ContentHandler::makeEmptyContent
 	 */
 	public function makeEmptyContent() {
 		return new WikitextContent( '' );
@@ -51,12 +52,12 @@ class WikitextContentHandler extends TextContentHandler {
 	/**
 	 * Returns a WikitextContent object representing a redirect to the given destination page.
 	 *
-	 * @see ContentHandler::makeRedirectContent
-	 *
-	 * @param Title $destination the page to redirect to.
-	 * @param string $text text to include in the redirect, if possible.
+	 * @param Title $destination The page to redirect to.
+	 * @param string $text Text to include in the redirect, if possible.
 	 *
 	 * @return Content
+	 *
+	 * @see ContentHandler::makeRedirectContent
 	 */
 	public function makeRedirectContent( Title $destination, $text = '' ) {
 		$optionalColon = '';
@@ -84,9 +85,9 @@ class WikitextContentHandler extends TextContentHandler {
 	/**
 	 * Returns true because wikitext supports redirects.
 	 *
-	 * @see ContentHandler::supportsRedirects
+	 * @return bool Always true.
 	 *
-	 * @return boolean whether redirects are supported.
+	 * @see ContentHandler::supportsRedirects
 	 */
 	public function supportsRedirects() {
 		return true;
@@ -95,7 +96,9 @@ class WikitextContentHandler extends TextContentHandler {
 	/**
 	 * Returns true because wikitext supports sections.
 	 *
-	 * @return boolean whether sections are supported.
+	 * @return bool Always true.
+	 *
+	 * @see ContentHandler::supportsSections
 	 */
 	public function supportsSections() {
 		return true;
@@ -106,9 +109,13 @@ class WikitextContentHandler extends TextContentHandler {
 	 * ParserCache mechanism.
 	 *
 	 * @since 1.21
-	 * @return bool
+	 *
+	 * @return bool Always true.
+	 *
+	 * @see ContentHandler::isParserCacheSupported
 	 */
 	public function isParserCacheSupported() {
 		return true;
 	}
+
 }
diff --git a/includes/diff/ArrayDiffFormatter.php b/includes/diff/ArrayDiffFormatter.php
index 543ee180e3..c12b76adac 100644
--- a/includes/diff/ArrayDiffFormatter.php
+++ b/includes/diff/ArrayDiffFormatter.php
@@ -32,7 +32,8 @@ class ArrayDiffFormatter extends DiffFormatter {
 
 	/**
 	 * @param Diff $diff A Diff object.
-	 * @return array
+	 *
+	 * @return array[] List of associative arrays, each describing a difference.
 	 */
 	public function format( $diff ) {
 		$oldline = 1;
@@ -77,4 +78,5 @@ class ArrayDiffFormatter extends DiffFormatter {
 
 		return $retval;
 	}
+
 }
diff --git a/includes/diff/DairikiDiff.php b/includes/diff/DairikiDiff.php
index 351a9dd6e9..61edc1ed00 100644
--- a/includes/diff/DairikiDiff.php
+++ b/includes/diff/DairikiDiff.php
@@ -32,18 +32,39 @@
  */
 abstract class DiffOp {
 
+	/**
+	 * @var string
+	 */
 	public $type;
+
+	/**
+	 * @var string[]
+	 */
 	public $orig;
+
+	/**
+	 * @var string[]
+	 */
 	public $closing;
 
+	/**
+	 * @return string
+	 */
 	public function getType() {
 		return $this->type;
 	}
 
+	/**
+	 * @return string[]
+	 */
 	public function getOrig() {
 		return $this->orig;
 	}
 
+	/**
+	 * @param int $i
+	 * @return string|null
+	 */
 	public function getClosing( $i = null ) {
 		if( $i === null ) {
 			return $this->closing;
@@ -195,9 +216,10 @@ class DiffEngine {
 	protected $lcs = 0;
 
 	/**
-	 * @param $from_lines
-	 * @param $to_lines
-	 * @return array
+	 * @param string[] $from_lines
+	 * @param string[] $to_lines
+	 *
+	 * @return DiffOp[]
 	 */
 	public function diff( $from_lines, $to_lines ) {
 		wfProfileIn( __METHOD__ );
@@ -256,8 +278,8 @@ class DiffEngine {
 	}
 
 	/**
-	 * @param $from_lines
-	 * @param $to_lines
+	 * @param string[] $from_lines
+	 * @param string[] $to_lines
 	 */
 	private function diffLocal( $from_lines, $to_lines ) {
 		global $wgExternalDiffEngine;
@@ -329,7 +351,9 @@ class DiffEngine {
 
 	/**
 	 * Returns the whole line if it's small enough, or the MD5 hash otherwise
-	 * @param $line string
+	 *
+	 * @param string $line
+	 *
 	 * @return string
 	 */
 	private function lineHash( $line ) {
@@ -356,12 +380,14 @@ class DiffEngine {
 	 * of the two files do not match, and likewise that the last lines do not
 	 * match.  The caller must trim matching lines from the beginning and end
 	 * of the portions it is going to specify.
-	 * @param $xoff
-	 * @param $xlim
-	 * @param $yoff
-	 * @param $ylim
-	 * @param $nchunks
-	 * @return array
+	 *
+	 * @param int $xoff
+	 * @param int $xlim
+	 * @param int $yoff
+	 * @param int $ylim
+	 * @param int $nchunks
+	 *
+	 * @return array List of two elements, integer and array[].
 	 */
 	private function diag( $xoff, $xlim, $yoff, $ylim, $nchunks ) {
 		$flip = false;
@@ -398,7 +424,7 @@ class DiffEngine {
 			}
 
 			$x1 = $xoff + (int)( ( $numer + ( $xlim - $xoff ) * $chunk ) / $nchunks );
-			for ( ; $x < $x1; $x++ ) {
+			for (; $x < $x1; $x++ ) {
 				$line = $flip ? $this->yv[$x] : $this->xv[$x];
 				if ( empty( $ymatches[$line] ) ) {
 					continue;
@@ -446,7 +472,8 @@ class DiffEngine {
 	}
 
 	/**
-	 * @param $ypos
+	 * @param int $ypos
+	 *
 	 * @return int
 	 */
 	private function lcsPos( $ypos ) {
@@ -488,10 +515,11 @@ class DiffEngine {
 	 *
 	 * Note that XLIM, YLIM are exclusive bounds.
 	 * All line numbers are origin-0 and discarded lines are not counted.
-	 * @param $xoff
-	 * @param $xlim
-	 * @param $yoff
-	 * @param $ylim
+	 *
+	 * @param int $xoff
+	 * @param int $xlim
+	 * @param int $yoff
+	 * @param int $ylim
 	 */
 	private function compareSeq( $xoff, $xlim, $yoff, $ylim ) {
 		// Slide down the bottom initial diagonal.
@@ -688,9 +716,9 @@ class Diff {
 	 * Constructor.
 	 * Computes diff between sequences of strings.
 	 *
-	 * @param $from_lines array An array of strings.
+	 * @param string[] $from_lines An array of strings.
 	 *   Typically these are lines from a file.
-	 * @param $to_lines array An array of strings.
+	 * @param string[] $to_lines An array of strings.
 	 */
 	public function __construct( $from_lines, $to_lines ) {
 		$eng = new DiffEngine;
@@ -698,7 +726,7 @@ class Diff {
 	}
 
 	/**
-	 * @return array|DiffOp[]
+	 * @return DiffOp[]
 	 */
 	public function getEdits() {
 		return $this->edits;
@@ -711,6 +739,7 @@ class Diff {
 	 *
 	 *    $diff = new Diff($lines1, $lines2);
 	 *    $rev = $diff->reverse();
+	 *
 	 * @return Object A Diff object representing the inverse of the
 	 *   original diff.
 	 */
@@ -764,7 +793,7 @@ class Diff {
 	 * This reconstructs the $from_lines parameter passed to the
 	 * constructor.
 	 *
-	 * @return array The original sequence of strings.
+	 * @return string[] The original sequence of strings.
 	 */
 	public function orig() {
 		$lines = array();
@@ -784,7 +813,7 @@ class Diff {
 	 * This reconstructs the $to_lines parameter passed to the
 	 * constructor.
 	 *
-	 * @return array The sequence of strings.
+	 * @return string[] The sequence of strings.
 	 */
 	public function closing() {
 		$lines = array();
@@ -814,18 +843,15 @@ class MappedDiff extends Diff {
 	 * case-insensitve diffs, or diffs which ignore
 	 * changes in white-space.
 	 *
-	 * @param $from_lines array An array of strings.
+	 * @param string[] $from_lines An array of strings.
 	 *   Typically these are lines from a file.
-	 *
-	 * @param $to_lines array An array of strings.
-	 *
-	 * @param $mapped_from_lines array This array should
+	 * @param string[] $to_lines An array of strings.
+	 * @param string[] $mapped_from_lines This array should
 	 *   have the same size number of elements as $from_lines.
 	 *   The elements in $mapped_from_lines and
 	 *   $mapped_to_lines are what is actually compared
 	 *   when computing the diff.
-	 *
-	 * @param $mapped_to_lines array This array should
+	 * @param string[] $mapped_to_lines This array should
 	 *   have the same number of elements as $to_lines.
 	 */
 	public function __construct( $from_lines, $to_lines,
@@ -875,7 +901,7 @@ class HWLDFWordAccumulator {
 	private $tag = '';
 
 	/**
-	 * @param $new_tag
+	 * @param string $new_tag
 	 */
 	private function flushGroup( $new_tag ) {
 		if ( $this->group !== '' ) {
@@ -894,7 +920,7 @@ class HWLDFWordAccumulator {
 	}
 
 	/**
-	 * @param $new_tag
+	 * @param string $new_tag
 	 */
 	private function flushLine( $new_tag ) {
 		$this->flushGroup( $new_tag );
@@ -908,8 +934,8 @@ class HWLDFWordAccumulator {
 	}
 
 	/**
-	 * @param $words
-	 * @param $tag string
+	 * @param string[] $words
+	 * @param string $tag
 	 */
 	public function addWords( $words, $tag = '' ) {
 		if ( $tag != $this->tag ) {
@@ -931,7 +957,7 @@ class HWLDFWordAccumulator {
 	}
 
 	/**
-	 * @return array
+	 * @return string[]
 	 */
 	public function getLines() {
 		$this->flushLine( '~done' );
@@ -949,8 +975,8 @@ class WordLevelDiff extends MappedDiff {
 	const MAX_LINE_LENGTH = 10000;
 
 	/**
-	 * @param $orig_lines
-	 * @param $closing_lines
+	 * @param string[] $orig_lines
+	 * @param string[] $closing_lines
 	 */
 	public function __construct( $orig_lines, $closing_lines ) {
 		wfProfileIn( __METHOD__ );
@@ -964,8 +990,9 @@ class WordLevelDiff extends MappedDiff {
 	}
 
 	/**
-	 * @param $lines
-	 * @return array
+	 * @param string[] $lines
+	 *
+	 * @return array[]
 	 */
 	private function split( $lines ) {
 		wfProfileIn( __METHOD__ );
@@ -1005,7 +1032,7 @@ class WordLevelDiff extends MappedDiff {
 	}
 
 	/**
-	 * @return array
+	 * @return string[]
 	 */
 	public function orig() {
 		wfProfileIn( __METHOD__ );
@@ -1025,7 +1052,7 @@ class WordLevelDiff extends MappedDiff {
 	}
 
 	/**
-	 * @return array
+	 * @return string[]
 	 */
 	public function closing() {
 		wfProfileIn( __METHOD__ );
@@ -1043,4 +1070,5 @@ class WordLevelDiff extends MappedDiff {
 
 		return $lines;
 	}
+
 }
diff --git a/includes/diff/DiffFormatter.php b/includes/diff/DiffFormatter.php
index d9e1c95fc6..d8a9ba37c3 100644
--- a/includes/diff/DiffFormatter.php
+++ b/includes/diff/DiffFormatter.php
@@ -34,6 +34,7 @@
  * @ingroup DifferenceEngine
  */
 abstract class DiffFormatter {
+
 	/** @var int Number of leading context "lines" to preserve.
 	 *
 	 * This should be left at zero for this class, but subclasses
@@ -51,7 +52,8 @@ abstract class DiffFormatter {
 	/**
 	 * Format a diff.
 	 *
-	 * @param $diff Diff A Diff object.
+	 * @param Diff $diff A Diff object.
+	 *
 	 * @return string The formatted output.
 	 */
 	public function format( $diff ) {
@@ -124,7 +126,8 @@ abstract class DiffFormatter {
 	 * @param int $ybeg
 	 * @param int $ylen
 	 * @param $edits
-	 * @throws MWException
+	 *
+	 * @throws MWException If the edit type is not known.
 	 */
 	protected function block( $xbeg, $xlen, $ybeg, $ylen, &$edits ) {
 		wfProfileIn( __METHOD__ );
@@ -161,10 +164,11 @@ abstract class DiffFormatter {
 	}
 
 	/**
-	 * @param $xbeg
-	 * @param $xlen
-	 * @param $ybeg
-	 * @param $ylen
+	 * @param int $xbeg
+	 * @param int $xlen
+	 * @param int $ybeg
+	 * @param int $ylen
+	 *
 	 * @return string
 	 */
 	protected function blockHeader( $xbeg, $xlen, $ybeg, $ylen ) {
@@ -178,16 +182,28 @@ abstract class DiffFormatter {
 		return $xbeg . ( $xlen ? ( $ylen ? 'c' : 'd' ) : 'a' ) . $ybeg;
 	}
 
+	/**
+	 * Called at the start of a block of connected edits.
+	 * This default implementation writes the header and a newline to the output buffer.
+	 *
+	 * @param string $header
+	 */
 	protected function startBlock( $header ) {
 		echo $header . "\n";
 	}
 
+	/**
+	 * Called at the end of a block of connected edits.
+	 * This default implementation does nothing.
+	 */
 	protected function endBlock() {
 	}
 
 	/**
-	 * @param $lines
-	 * @param $prefix string
+	 * Writes all (optionally prefixed) lines to the output buffer, separated by newlines.
+	 *
+	 * @param string[] $lines
+	 * @param string $prefix
 	 */
 	protected function lines( $lines, $prefix = ' ' ) {
 		foreach ( $lines as $line ) {
@@ -196,33 +212,36 @@ abstract class DiffFormatter {
 	}
 
 	/**
-	 * @param $lines
+	 * @param string[] $lines
 	 */
 	protected function context( $lines ) {
 		$this->lines( $lines );
 	}
 
 	/**
-	 * @param $lines
+	 * @param string[] $lines
 	 */
 	protected function added( $lines ) {
 		$this->lines( $lines, '>' );
 	}
 
 	/**
-	 * @param $lines
+	 * @param string[] $lines
 	 */
 	protected function deleted( $lines ) {
 		$this->lines( $lines, '<' );
 	}
 
 	/**
-	 * @param $orig
-	 * @param $closing
+	 * Writes the two sets of lines to the output buffer, separated by "---" and a newline.
+	 *
+	 * @param string[] $orig
+	 * @param string[] $closing
 	 */
 	protected function changed( $orig, $closing ) {
 		$this->deleted( $orig );
 		echo "---\n";
 		$this->added( $closing );
 	}
+
 }
diff --git a/includes/diff/DifferenceEngine.php b/includes/diff/DifferenceEngine.php
index d6cf69494c..52eb003980 100644
--- a/includes/diff/DifferenceEngine.php
+++ b/includes/diff/DifferenceEngine.php
@@ -34,6 +34,7 @@ define( 'MW_DIFF_VERSION', '1.11a' );
  * @ingroup DifferenceEngine
  */
 class DifferenceEngine extends ContextSource {
+
 	/** @var int */
 	public $mOldid;
 
@@ -97,16 +98,15 @@ class DifferenceEngine extends ContextSource {
 
 	/**
 	 * Constructor
-	 * @param $context IContextSource context to use, anything else will be ignored
-	 * @param $old Integer old ID we want to show and diff with.
-	 * @param $new String|int either revision ID or 'prev' or 'next'. Default: 0.
-	 * @param $rcid Integer Deprecated, no longer used!
-	 * @param $refreshCache boolean If set, refreshes the diff cache
-	 * @param $unhide boolean If set, allow viewing deleted revs
+	 * @param IContextSource $context context to use, anything else will be ignored
+	 * @param int $old old ID we want to show and diff with.
+	 * @param string|int $new either revision ID or 'prev' or 'next'. Default: 0.
+	 * @param int $rcid Deprecated, no longer used!
+	 * @param bool $refreshCache If set, refreshes the diff cache
+	 * @param bool $unhide If set, allow viewing deleted revs
 	 */
 	function __construct( $context = null, $old = 0, $new = 0, $rcid = 0,
-		$refreshCache = false, $unhide = false
-	) {
+		$refreshCache = false, $unhide = false ) {
 		if ( $context instanceof IContextSource ) {
 			$this->setContext( $context );
 		}
@@ -120,7 +120,7 @@ class DifferenceEngine extends ContextSource {
 	}
 
 	/**
-	 * @param $value bool
+	 * @param bool $value
 	 */
 	function setReducedLineNumbers( $value = true ) {
 		$this->mReducedLineNumbers = $value;
@@ -155,7 +155,7 @@ class DifferenceEngine extends ContextSource {
 	}
 
 	/**
-	 * @return Bool|int
+	 * @return bool|int
 	 */
 	function getNewid() {
 		$this->loadRevisionIds();
@@ -167,7 +167,8 @@ class DifferenceEngine extends ContextSource {
 	 * Look up a special:Undelete link to the given deleted revision id,
 	 * as a workaround for being unable to load deleted diffs in currently.
 	 *
-	 * @param int $id revision ID
+	 * @param int $id Revision ID
+	 *
 	 * @return mixed URL or false
 	 */
 	function deletedLink( $id ) {
@@ -193,8 +194,9 @@ class DifferenceEngine extends ContextSource {
 	/**
 	 * Build a wikitext link toward a deleted revision, if viewable.
 	 *
-	 * @param int $id revision ID
-	 * @return string wikitext fragment
+	 * @param int $id Revision ID
+	 *
+	 * @return string Wikitext fragment
 	 */
 	function deletedIdMarker( $id ) {
 		$link = $this->deletedLink( $id );
@@ -451,7 +453,7 @@ class DifferenceEngine extends ContextSource {
 	 * Side effect: When the patrol link is build, this method will call
 	 * OutputPage::preventClickjacking() and load mediawiki.page.patrol.ajax.
 	 *
-	 * @return String
+	 * @return string
 	 */
 	protected function markPatrolledLink() {
 		global $wgUseRCPatrol, $wgEnableAPI, $wgEnableWriteAPI;
@@ -518,8 +520,9 @@ class DifferenceEngine extends ContextSource {
 	}
 
 	/**
-	 * @param $rev Revision
-	 * @return String
+	 * @param Revision $rev
+	 *
+	 * @return string
 	 */
 	protected function revisionDeleteLink( $rev ) {
 		$link = Linker::getRevDeleteLink( $this->getUser(), $rev, $rev->getTitle() );
@@ -643,6 +646,7 @@ class DifferenceEngine extends ContextSource {
 	 * @param string|bool $otitle Header for old text or false
 	 * @param string|bool $ntitle Header for new text or false
 	 * @param string $notice HTML between diff header and body
+	 *
 	 * @return mixed
 	 */
 	function getDiff( $otitle, $ntitle, $notice = '' ) {
@@ -747,9 +751,10 @@ class DifferenceEngine extends ContextSource {
 	/**
 	 * Returns the cache key for diff body text or content.
 	 *
-	 * @return string
 	 * @since 1.23
+	 *
 	 * @throws MWException
+	 * @return string
 	 */
 	protected function getDiffBodyCacheKey() {
 		if ( !$this->mOldid || !$this->mNewid ) {
@@ -771,12 +776,13 @@ class DifferenceEngine extends ContextSource {
 	 * perhaps taking advantage of the content's native form. This is required for all content
 	 * models that are not text based.
 	 *
-	 * @param $old Content: old content
-	 * @param $new Content: new content
+	 * @since 1.21
+	 *
+	 * @param Content $old Old content
+	 * @param Content $new New content
 	 *
+	 * @throws MWException If old or new content is not an instance of TextContent.
 	 * @return bool|string
-	 * @since 1.21
-	 * @throws MWException if $old or $new are not instances of TextContent.
 	 */
 	function generateContentDiffBody( Content $old, Content $new ) {
 		if ( !( $old instanceof TextContent ) ) {
@@ -798,8 +804,9 @@ class DifferenceEngine extends ContextSource {
 	/**
 	 * Generate a diff, no caching
 	 *
-	 * @param string $otext old text, must be already segmented
-	 * @param string $ntext new text, must be already segmented
+	 * @param string $otext Old text, must be already segmented
+	 * @param string $ntext New text, must be already segmented
+	 *
 	 * @return bool|string
 	 * @deprecated since 1.21, use generateContentDiffBody() instead!
 	 */
@@ -816,6 +823,7 @@ class DifferenceEngine extends ContextSource {
 	 *
 	 * @param string $otext old text, must be already segmented
 	 * @param string $ntext new text, must be already segmented
+	 *
 	 * @return bool|string
 	 */
 	function generateTextDiffBody( $otext, $ntext ) {
@@ -897,7 +905,7 @@ class DifferenceEngine extends ContextSource {
 	 * Generate a debug comment indicating diff generating time,
 	 * server node, and generator backend.
 	 *
-	 * @param String $generator : What diff engine was used
+	 * @param string $generator : What diff engine was used
 	 *
 	 * @return string
 	 */
@@ -920,7 +928,7 @@ class DifferenceEngine extends ContextSource {
 	/**
 	 * Replace line numbers with the text in the user's language
 	 *
-	 * @param String $text
+	 * @param string $text
 	 *
 	 * @return mixed
 	 */
@@ -942,6 +950,7 @@ class DifferenceEngine extends ContextSource {
 
 	/**
 	 * If there are revisions between the ones being compared, return a note saying so.
+	 *
 	 * @return string
 	 */
 	function getMultiNotice() {
@@ -978,9 +987,11 @@ class DifferenceEngine extends ContextSource {
 
 	/**
 	 * Get a notice about how many intermediate edits and users there are
-	 * @param $numEdits int
-	 * @param $numUsers int
-	 * @param $limit int
+	 *
+	 * @param int $numEdits
+	 * @param int $numUsers
+	 * @param int $limit
+	 *
 	 * @return string
 	 */
 	public static function intermediateEditsMsg( $numEdits, $numUsers, $limit ) {
@@ -999,10 +1010,11 @@ class DifferenceEngine extends ContextSource {
 	/**
 	 * Get a header for a specified revision.
 	 *
-	 * @param $rev Revision
+	 * @param Revision $rev
 	 * @param string $complete 'complete' to get the header wrapped depending
 	 *        the visibility of the revision and a link to edit the page.
-	 * @return String HTML fragment
+	 *
+	 * @return string HTML fragment
 	 */
 	protected function getRevisionHeader( Revision $rev, $complete = '' ) {
 		$lang = $this->getLanguage();
@@ -1149,7 +1161,8 @@ class DifferenceEngine extends ContextSource {
 	 *
 	 * @param int $old Revision id, e.g. from URL parameter 'oldid'
 	 * @param int|string $new Revision id or strings 'next' or 'prev', e.g. from URL parameter 'diff'
-	 * @return array Array of two revision ids, older first, later second.
+	 *
+	 * @return int[] List of two revision ids, older first, later second.
 	 *     Zero signifies invalid argument passed.
 	 *     false signifies that there is no previous/next revision ($old is the oldest/newest one).
 	 */
@@ -1337,4 +1350,5 @@ class DifferenceEngine extends ContextSource {
 
 		return true;
 	}
+
 }
diff --git a/includes/diff/TableDiffFormatter.php b/includes/diff/TableDiffFormatter.php
index 5f286272a1..ac8f758cf1 100644
--- a/includes/diff/TableDiffFormatter.php
+++ b/includes/diff/TableDiffFormatter.php
@@ -31,6 +31,7 @@
  * @ingroup DifferenceEngine
  */
 class TableDiffFormatter extends DiffFormatter {
+
 	function __construct() {
 		$this->leadingContextLines = 2;
 		$this->trailingContextLines = 2;
@@ -38,7 +39,8 @@ class TableDiffFormatter extends DiffFormatter {
 
 	/**
 	 * @static
-	 * @param $msg
+	 * @param string $msg
+	 *
 	 * @return mixed
 	 */
 	public static function escapeWhiteSpace( $msg ) {
@@ -50,10 +52,11 @@ class TableDiffFormatter extends DiffFormatter {
 	}
 
 	/**
-	 * @param $xbeg
-	 * @param $xlen
-	 * @param $ybeg
-	 * @param $ylen
+	 * @param int $xbeg
+	 * @param int $xlen
+	 * @param int $ybeg
+	 * @param int $ylen
+	 *
 	 * @return string
 	 */
 	protected function blockHeader( $xbeg, $xlen, $ybeg, $ylen ) {
@@ -64,7 +67,9 @@ class TableDiffFormatter extends DiffFormatter {
 	}
 
 	/**
-	 * @param $header
+	 * Writes the header to the output buffer.
+	 *
+	 * @param string $header
 	 */
 	protected function startBlock( $header ) {
 		echo $header;
@@ -73,12 +78,19 @@ class TableDiffFormatter extends DiffFormatter {
 	protected function endBlock() {
 	}
 
+	/**
+	 * @param string[] $lines
+	 * @param string $prefix
+	 * @param string $color
+	 */
 	protected function lines( $lines, $prefix = ' ', $color = 'white' ) {
 	}
 
 	/**
 	 * HTML-escape parameter before calling this
-	 * @param $line
+	 *
+	 * @param string $line
+	 *
 	 * @return string
 	 */
 	protected function addedLine( $line ) {
@@ -87,7 +99,9 @@ class TableDiffFormatter extends DiffFormatter {
 
 	/**
 	 * HTML-escape parameter before calling this
-	 * @param $line
+	 *
+	 * @param string $line
+	 *
 	 * @return string
 	 */
 	protected function deletedLine( $line ) {
@@ -96,7 +110,9 @@ class TableDiffFormatter extends DiffFormatter {
 
 	/**
 	 * HTML-escape parameter before calling this
-	 * @param $line
+	 *
+	 * @param string $line
+	 *
 	 * @return string
 	 */
 	protected function contextLine( $line ) {
@@ -104,9 +120,10 @@ class TableDiffFormatter extends DiffFormatter {
 	}
 
 	/**
-	 * @param $marker
-	 * @param $class
-	 * @param $line
+	 * @param string $marker
+	 * @param string $class Unused
+	 * @param string $line
+	 *
 	 * @return string
 	 */
 	protected function wrapLine( $marker, $class, $line ) {
@@ -126,7 +143,9 @@ class TableDiffFormatter extends DiffFormatter {
 	}
 
 	/**
-	 * @param $lines array
+	 * Writes all lines to the output buffer, each enclosed in <tr>.
+	 *
+	 * @param string[] $lines
 	 */
 	protected function added( $lines ) {
 		foreach ( $lines as $line ) {
@@ -137,7 +156,9 @@ class TableDiffFormatter extends DiffFormatter {
 	}
 
 	/**
-	 * @param $lines
+	 * Writes all lines to the output buffer, each enclosed in <tr>.
+	 *
+	 * @param string[] $lines
 	 */
 	protected function deleted( $lines ) {
 		foreach ( $lines as $line ) {
@@ -148,7 +169,9 @@ class TableDiffFormatter extends DiffFormatter {
 	}
 
 	/**
-	 * @param $lines
+	 * Writes all lines to the output buffer, each enclosed in <tr>.
+	 *
+	 * @param string[] $lines
 	 */
 	protected function context( $lines ) {
 		foreach ( $lines as $line ) {
@@ -159,8 +182,10 @@ class TableDiffFormatter extends DiffFormatter {
 	}
 
 	/**
-	 * @param $orig
-	 * @param $closing
+	 * Writes the two sets of lines to the output buffer, each enclosed in <tr>.
+	 *
+	 * @param string[] $orig
+	 * @param string[] $closing
 	 */
 	protected function changed( $orig, $closing ) {
 		wfProfileIn( __METHOD__ );
@@ -183,4 +208,5 @@ class TableDiffFormatter extends DiffFormatter {
 		}
 		wfProfileOut( __METHOD__ );
 	}
+
 }
diff --git a/includes/diff/UnifiedDiffFormatter.php b/includes/diff/UnifiedDiffFormatter.php
index 0a86ccc0ab..32a76055ee 100644
--- a/includes/diff/UnifiedDiffFormatter.php
+++ b/includes/diff/UnifiedDiffFormatter.php
@@ -29,6 +29,7 @@
  * @ingroup DifferenceEngine
  */
 class UnifiedDiffFormatter extends DiffFormatter {
+
 	/** @var int */
 	protected $leadingContextLines = 2;
 
@@ -36,22 +37,22 @@ class UnifiedDiffFormatter extends DiffFormatter {
 	protected $trailingContextLines = 2;
 
 	/**
-	 * @param $lines
+	 * @param string[] $lines
 	 */
 	protected function added( $lines ) {
 		$this->lines( $lines, '+' );
 	}
 
 	/**
-	 * @param $lines
+	 * @param string[] $lines
 	 */
 	protected function deleted( $lines ) {
 		$this->lines( $lines, '-' );
 	}
 
 	/**
-	 * @param $orig
-	 * @param $closing
+	 * @param string[] $orig
+	 * @param string[] $closing
 	 */
 	protected function changed( $orig, $closing ) {
 		$this->deleted( $orig );
@@ -59,13 +60,15 @@ class UnifiedDiffFormatter extends DiffFormatter {
 	}
 
 	/**
-	 * @param $xbeg
-	 * @param $xlen
-	 * @param $ybeg
-	 * @param $ylen
+	 * @param int $xbeg
+	 * @param int $xlen
+	 * @param int $ybeg
+	 * @param int $ylen
+	 *
 	 * @return string
 	 */
 	protected function blockHeader( $xbeg, $xlen, $ybeg, $ylen ) {
 		return "@@ -$xbeg,$xlen +$ybeg,$ylen @@";
 	}
+
 }
diff --git a/includes/diff/WikiDiff3.php b/includes/diff/WikiDiff3.php
index 7c019b0ea9..7a0f7403a6 100644
--- a/includes/diff/WikiDiff3.php
+++ b/includes/diff/WikiDiff3.php
@@ -580,6 +580,7 @@ class WikiDiff3 {
 
 		return $this->length;
 	}
+
 }
 
 /**
@@ -589,6 +590,7 @@ class WikiDiff3 {
  * @ingroup DifferenceEngine
  */
 class RangeDifference {
+
 	/** @var int */
 	public $leftstart;
 
@@ -615,4 +617,5 @@ class RangeDifference {
 		$this->rightend = $rightend;
 		$this->rightlength = $rightend - $rightstart;
 	}
+
 }
-- 
2.20.1