diff: Fix and update type hints in DiffOp classes

This patch adds and updates documentation. The most significant
changes are:
* getOrig() and getClosing() can return false. However, this is
  only possible for add and remove operations. These have only
  one side.
* The constructors of the subclasses are not meant to accept
  false, and are in fact never called with false. For the same
  reason. Only add and remove operations are allowed to miss
  one of the two sides.

Change-Id: I9f45f34945e0297e1ea8d3e8ff9e9c53e60e7706

includes/diff/DiffOp.php

@@ -38,36 +38,47 @@ abstract class DiffOp {
 
 	/**
 	 * @var string
+	 * @private Please use {@see getType}
 	 */
 	public $type;
 
 	/**
-	 * @var string[]|false
+	 * @var string[]|false The left ("old") side of the diff, or false when it's an "add"
+	 * @private Please use {@see getOrig}
 	 */
 	public $orig;
 
 	/**
-	 * @var string[]|false
+	 * @var string[]|false The right ("new") side of the diff, or false when it's a "delete"
+	 * @private Please use {@see getClosing}
 	 */
 	public $closing;
 
 	/**
-	 * @return string
+	 * @return string Either "add", "change", "copy", or "delete"
 	 */
 	public function getType() {
 		return $this->type;
 	}
 
 	/**
-	 * @return string[]
+	 * Returns either all lines on the left ("old") side of the diff, or false when it's an add
+	 * operation.
+	 *
+	 * @return string[]|false
 	 */
 	public function getOrig() {
 		return $this->orig;
 	}
 
 	/**
-	 * @param int|null $i
-	 * @return string[]|string|null
+	 * Without a line number this returns either all lines on the right ("new") side of the diff, or
+	 * false when it's a delete operation.
+	 *
+	 * With a line number this returns either the line or null if the line doesn't exist.
+	 *
+	 * @param int|null $i Line number, or null for all lines in the operation
+	 * @return string[]|false|string|null
 	 */
 	public function getClosing( $i = null ) {
 		if ( $i === null ) {
@@ -80,19 +91,19 @@ abstract class DiffOp {
 	}
 
 	/**
-	 * @return self
+	 * @return self Inverted operation (a.k.a. revert or undo), e.g. "delete" becomes "add"
 	 */
 	abstract public function reverse();
 
 	/**
-	 * @return int
+	 * @return int Number of lines on the left ("old") side of the diff, {@see getOrig}
 	 */
 	public function norig() {
 		return $this->orig ? count( $this->orig ) : 0;
 	}
 
 	/**
-	 * @return int
+	 * @return int Number of lines on the right ("new") side of the diff, see {@see getClosing}
 	 */
 	public function nclosing() {
 		return $this->closing ? count( $this->closing ) : 0;

includes/diff/DiffOpAdd.php

@@ -37,7 +37,7 @@ class DiffOpAdd extends DiffOp {
 	public $type = 'add';
 
 	/**
-	 * @param string[]|false $lines
+	 * @param string[] $lines
 	 */
 	public function __construct( $lines ) {
 		$this->closing = $lines;

includes/diff/DiffOpChange.php

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

includes/diff/DiffOpCopy.php

@@ -37,8 +37,8 @@ class DiffOpCopy extends DiffOp {
 	public $type = 'copy';
 
 	/**
-	 * @param string[]|false $orig
-	 * @param string[]|false $closing
+	 * @param string[] $orig
+	 * @param string[]|false $closing Should either be identical to $orig, or not given
 	 */
 	public function __construct( $orig, $closing = false ) {
 		if ( !is_array( $closing ) ) {

includes/diff/DiffOpDelete.php

@@ -37,7 +37,7 @@ class DiffOpDelete extends DiffOp {
 	public $type = 'delete';
 
 	/**
-	 * @param string[]|false $lines
+	 * @param string[] $lines
 	 */
 	public function __construct( $lines ) {
 		$this->orig = $lines;