Improve and add documentation to diff related classes

Change-Id: Ic10c700e970018fa0b9a219d96d56908b0298d71

includes/diff/DiffEngine.php

@@ -51,24 +51,39 @@ class DiffEngine {
 	private $from;
 	/** @var string[] */
 	private $to;
+	/** @var int */
 	private $m;
+	/** @var int */
 	private $n;
 
+	/** @var int */
 	private $tooLong;
+	/** @var float */
 	private $powLimit;
 
+	/** @var int */
 	protected $bailoutComplexity = 0;
 
 	// State variables
+	/** @var float */
 	private $maxDifferences;
+	/** @var bool */
 	private $lcsLengthCorrectedForHeuristic = false;
 
 	// Output variables
+	/** @var int */
 	public $length;
+	/** @var array */
 	public $removed;
+	/** @var array */
 	public $added;
+	/** @var bool */
 	public $heuristicUsed;
 
+	/**
+	 * @param int $tooLong
+	 * @param float $powLimit
+	 */
 	public function __construct( $tooLong = 2000000, $powLimit = 1.45 ) {
 		$this->tooLong = $tooLong;
 		$this->powLimit = $powLimit;
@@ -412,6 +427,15 @@ class DiffEngine {
 		$this->added = $added;
 	}
 
+	/**
+	 * @param int $bottoml1
+	 * @param int $topl1
+	 * @param int $bottoml2
+	 * @param int $topl2
+	 * @param array &$V
+	 * @param array &$snake
+	 * @return int
+	 */
 	private function lcs_rec( $bottoml1, $topl1, $bottoml2, $topl2, &$V, &$snake ) {
 		// check that both sequences are non-empty
 		if ( $bottoml1 > $topl1 || $bottoml2 > $topl2 ) {
@@ -454,6 +478,15 @@ class DiffEngine {
 		return $len;
 	}
 
+	/**
+	 * @param int $bottoml1
+	 * @param int $topl1
+	 * @param int $bottoml2
+	 * @param int $topl2
+	 * @param array &$V
+	 * @param array &$snake
+	 * @return int
+	 */
 	private function find_middle_snake( $bottoml1, $topl1, $bottoml2, $topl2, &$V, &$snake ) {
 		$from = &$this->from;
 		$to = &$this->to;
@@ -678,6 +711,13 @@ class DiffEngine {
 		*/
 	}
 
+	/**
+	 * @param int $M
+	 * @param int $N
+	 * @param int $limit
+	 * @param array $V
+	 * @return array
+	 */
 	private static function findMostProgress( $M, $N, $limit, $V ) {
 		$delta = $N - $M;
 
@@ -758,7 +798,7 @@ class DiffEngine {
 	}
 
 	/**
-	 * @return mixed
+	 * @return int
 	 */
 	public function getLcsLength() {
 		if ( $this->heuristicUsed && !$this->lcsLengthCorrectedForHeuristic ) {

includes/diff/DiffOp.php

@@ -79,6 +79,9 @@ abstract class DiffOp {
 		return null;
 	}
 
+	/**
+	 * @return self
+	 */
 	abstract public function reverse();
 
 	/**

includes/diff/DiffOpAdd.php

@@ -33,8 +33,12 @@
  * @ingroup DifferenceEngine
  */
 class DiffOpAdd extends DiffOp {
+	/** @inheritDoc */
 	public $type = 'add';
 
+	/**
+	 * @param string[]|false $lines
+	 */
 	public function __construct( $lines ) {
 		$this->closing = $lines;
 		$this->orig = false;

includes/diff/DiffOpChange.php

@@ -33,8 +33,13 @@
  * @ingroup DifferenceEngine
  */
 class DiffOpChange extends DiffOp {
+	/** @inheritDoc */
 	public $type = 'change';
 
+	/**
+	 * @param string[]|false $orig
+	 * @param string[]|false $closing
+	 */
 	public function __construct( $orig, $closing ) {
 		$this->orig = $orig;
 		$this->closing = $closing;

includes/diff/DiffOpCopy.php

@@ -33,8 +33,13 @@
  * @ingroup DifferenceEngine
  */
 class DiffOpCopy extends DiffOp {
+	/** @inheritDoc */
 	public $type = 'copy';
 
+	/**
+	 * @param string[]|false $orig
+	 * @param string[]|false $closing
+	 */
 	public function __construct( $orig, $closing = false ) {
 		if ( !is_array( $closing ) ) {
 			$closing = $orig;

includes/diff/DiffOpDelete.php

@@ -33,8 +33,12 @@
  * @ingroup DifferenceEngine
  */
 class DiffOpDelete extends DiffOp {
+	/** @inheritDoc */
 	public $type = 'delete';
 
+	/**
+	 * @param string[]|false $lines
+	 */
 	public function __construct( $lines ) {
 		$this->orig = $lines;
 		$this->closing = false;

includes/diff/DifferenceEngine.php

@@ -173,6 +173,7 @@ class DifferenceEngine extends ContextSource {
 	 * Set this to true to add debug info to the HTML output.
 	 * Warning: this may cause RSS readers to spuriously mark articles as "new"
 	 * (T22601)
+	 * @var bool
 	 */
 	public $enableDebugComment = false;
 
@@ -356,6 +357,7 @@ class DifferenceEngine extends ContextSource {
 		return $slots;
 	}
 
+	/** @inheritDoc */
 	public function getTitle() {
 		// T202454 avoid errors when there is no title
 		return parent::getTitle() ?: Title::makeTitle( NS_SPECIAL, 'BadTitle/DifferenceEngine' );
@@ -606,6 +608,9 @@ class DifferenceEngine extends ContextSource {
 			!$this->isUserAllowedToSeeRevisions( $user ) );
 	}
 
+	/**
+	 * @param bool $diffOnly
+	 */
 	public function showDiffPage( $diffOnly = false ) {
 		# Allow frames except in certain special cases
 		$out = $this->getOutput();
@@ -1085,7 +1090,7 @@ class DifferenceEngine extends ContextSource {
 	 * @param WikiPage $page
 	 * @param RevisionRecord $revRecord
 	 *
-	 * @return ParserOutput|bool False if the revision was not found
+	 * @return ParserOutput|false False if the revision was not found
 	 */
 	protected function getParserOutput( WikiPage $page, RevisionRecord $revRecord ) {
 		if ( !$revRecord->getId() ) {
@@ -1105,8 +1110,8 @@ class DifferenceEngine extends ContextSource {
 	 * Get the diff text, send it to the OutputPage object
 	 * Returns false if the diff could not be generated, otherwise returns true
 	 *
-	 * @param string|bool $otitle Header for old text or false
-	 * @param string|bool $ntitle Header for new text or false
+	 * @param string|false $otitle Header for old text or false
+	 * @param string|false $ntitle Header for new text or false
 	 * @param string $notice HTML between diff header and body
 	 *
 	 * @return bool
@@ -1146,8 +1151,8 @@ class DifferenceEngine extends ContextSource {
 	/**
 	 * Get complete diff table, including header
 	 *
-	 * @param string|bool $otitle Header for old text or false
-	 * @param string|bool $ntitle Header for new text or false
+	 * @param string|false $otitle Header for old text or false
+	 * @param string|false $ntitle Header for new text or false
 	 * @param string $notice HTML between diff header and body
 	 *
 	 * @return mixed
@@ -1172,7 +1177,7 @@ class DifferenceEngine extends ContextSource {
 	/**
 	 * Get the diff table body, without header
 	 *
-	 * @return mixed (string/false)
+	 * @return string|false
 	 */
 	public function getDiffBody() {
 		$this->mCacheHit = true;
@@ -1338,7 +1343,7 @@ class DifferenceEngine extends ContextSource {
 	 *
 	 * @since 1.31
 	 *
-	 * @return array
+	 * @return string[]
 	 * @throws MWException
 	 */
 	protected function getDiffBodyCacheKeyParams() {
@@ -1371,7 +1376,7 @@ class DifferenceEngine extends ContextSource {
 	/**
 	 * Implements DifferenceEngineSlotDiffRenderer::getExtraCacheKeys(). Only used when
 	 * DifferenceEngine is wrapped in DifferenceEngineSlotDiffRenderer.
-	 * @return array
+	 * @return string[]
 	 * @internal for use by DifferenceEngineSlotDiffRenderer only
 	 * @deprecated
 	 */
@@ -1570,6 +1575,9 @@ class DifferenceEngine extends ContextSource {
 			" -->\n";
 	}
 
+	/**
+	 * @return string
+	 */
 	private function getDebugString() {
 		$engine = self::getEngine();
 		if ( $engine === 'wikidiff2' ) {
@@ -1602,7 +1610,7 @@ class DifferenceEngine extends ContextSource {
 	 *
 	 * @param string $text
 	 *
-	 * @return mixed
+	 * @return string
 	 */
 	public function localiseLineNumbers( $text ) {
 		return preg_replace_callback(
@@ -1612,6 +1620,10 @@ class DifferenceEngine extends ContextSource {
 		);
 	}
 
+	/**
+	 * @param array $matches
+	 * @return string
+	 */
 	public function localiseLineNumbersCb( $matches ) {
 		if ( $matches[1] === '1' && $this->mReducedLineNumbers ) {
 			return '';

includes/diff/DifferenceEngineSlotDiffRenderer.php

@@ -34,6 +34,9 @@ class DifferenceEngineSlotDiffRenderer extends SlotDiffRenderer {
 	/** @var DifferenceEngine */
 	private $differenceEngine;
 
+	/**
+	 * @param DifferenceEngine $differenceEngine
+	 */
 	public function __construct( DifferenceEngine $differenceEngine ) {
 		$this->differenceEngine = clone $differenceEngine;
 
@@ -54,6 +57,7 @@ class DifferenceEngineSlotDiffRenderer extends SlotDiffRenderer {
 		return $this->differenceEngine->generateContentDiffBody( $oldContent, $newContent );
 	}
 
+	/** @inheritDoc */
 	public function addModules( OutputPage $output ) {
 		$oldContext = null;
 		if ( $output !== $this->differenceEngine->getOutput() ) {
@@ -68,6 +72,7 @@ class DifferenceEngineSlotDiffRenderer extends SlotDiffRenderer {
 		}
 	}
 
+	/** @inheritDoc */
 	public function getExtraCacheKeys() {
 		return $this->differenceEngine->getExtraCacheKeys();
 	}

includes/diff/RangeDifference.php

@@ -49,6 +49,12 @@ class RangeDifference {
 	/** @var int */
 	public $rightlength;
 
+	/**
+	 * @param int $leftstart
+	 * @param int $leftend
+	 * @param int $rightstart
+	 * @param int $rightend
+	 */
 	public function __construct( $leftstart, $leftend, $rightstart, $rightend ) {
 		$this->leftstart = $leftstart;
 		$this->leftend = $leftend;

includes/diff/SlotDiffRenderer.php

@@ -60,7 +60,7 @@ abstract class SlotDiffRenderer {
 	/**
 	 * Return any extra keys to split the diff cache by.
 	 * @stable to override
-	 * @return array
+	 * @return string[]
 	 */
 	public function getExtraCacheKeys() {
 		return [];

includes/diff/TableDiffFormatter.php

@@ -40,7 +40,7 @@ class TableDiffFormatter extends DiffFormatter {
 	/**
 	 * @param string $msg
 	 *
-	 * @return mixed
+	 * @return string
 	 */
 	public static function escapeWhiteSpace( $msg ) {
 		$msg = preg_replace( '/^ /m', "\u{00A0} ", $msg );
@@ -73,15 +73,12 @@ class TableDiffFormatter extends DiffFormatter {
 		return $r;
 	}
 
-	/**
-	 * Writes the header to the output buffer.
-	 *
-	 * @param string $header
-	 */
+	/** @inheritDoc */
 	protected function startBlock( $header ) {
 		$this->writeOutput( $header );
 	}
 
+	/** @inheritDoc */
 	protected function endBlock() {
 	}
 

includes/diff/TextSlotDiffRenderer.php

@@ -61,10 +61,7 @@ class TextSlotDiffRenderer extends SlotDiffRenderer {
 	/** @var string Path to an executable to be used as the diff engine. */
 	private $externalEngine;
 
-	/**
-	 * @inheritDoc
-	 * @return array
-	 */
+	/** @inheritDoc */
 	public function getExtraCacheKeys() {
 		// Tell DifferenceEngine this is a different variant from the standard wikidiff2 variant
 		return $this->engine === self::ENGINE_WIKIDIFF2_INLINE ? [
@@ -88,10 +85,16 @@ class TextSlotDiffRenderer extends SlotDiffRenderer {
 		return $slotDiffRenderer->getTextDiff( $oldText, $newText );
 	}
 
+	/**
+	 * @param IBufferingStatsdDataFactory $statsdDataFactory
+	 */
 	public function setStatsdDataFactory( IBufferingStatsdDataFactory $statsdDataFactory ) {
 		$this->statsdDataFactory = $statsdDataFactory;
 	}
 
+	/**
+	 * @param Language $language
+	 */
 	public function setLanguage( Language $language ) {
 		$this->language = $language;
 	}

includes/diff/WordAccumulator.php

@@ -32,12 +32,18 @@ namespace MediaWiki\Diff;
  * @ingroup DifferenceEngine
  */
 class WordAccumulator {
+	/** @var string */
 	public $insClass = ' class="diffchange diffchange-inline"';
+	/** @var string */
 	public $delClass = ' class="diffchange diffchange-inline"';
 
+	/** @var array */
 	private $lines = [];
+	/** @var string */
 	private $line = '';
+	/** @var string */
 	private $group = '';
+	/** @var string */
 	private $tag = '';
 
 	/**