Various minor code cleanups in the Parsoid PHP code

* Improve PHPDoc documentation.
* Add some missing language-level type declarations.
* Remove unused code.
* Avoid count() when the code doesn't care about the actual count.
* Use the short ??= operator where possible.

Change-Id: I79de49b65d32661b7efa67ecc350276968943e11

src/Parsoid/Ref.php

@@ -90,7 +90,6 @@ class Ref extends ExtensionTagHandler {
 	) {
 		$startTagSrc = $extApi->extStartTagToWikitext( $node );
 		$dataMw = DOMDataUtils::getDataMw( $node );
-		$html = null;
 		if ( !isset( $dataMw->body ) ) {
 			return $startTagSrc; // We self-closed this already.
 		}

src/Parsoid/RefGroup.php

@@ -15,19 +15,10 @@ use Wikimedia\Parsoid\Utils\DOMCompat;
  */
 class RefGroup {
 
-	/**
-	 * @var string
-	 */
-	public $name;
-
-	/**
-	 * @var RefGroupItem[]
-	 */
+	public string $name;
+	/** @var RefGroupItem[] */
 	public array $refs = [];
-
-	/**
-	 * @var RefGroupItem[]
-	 */
+	/** @var array<string,RefGroupItem> Lookup map only for named refs */
 	public array $indexByName = [];
 
 	public function __construct( string $group = '' ) {
@@ -36,27 +27,20 @@ class RefGroup {
 
 	/**
 	 * Generate leading linkbacks
-	 * @param ParsoidExtensionAPI $extApi
-	 * @param string $href
-	 * @param ?string $group
-	 * @param string $text
-	 * @param Document $ownerDoc
-	 * @return Element
 	 */
 	private static function createLinkback(
-		ParsoidExtensionAPI $extApi, string $href, ?string $group,
+		ParsoidExtensionAPI $extApi, string $target, ?string $group,
 		string $text, Document $ownerDoc
 	): Element {
 		$a = $ownerDoc->createElement( 'a' );
-		$s = $ownerDoc->createElement( 'span' );
-		$textNode = $ownerDoc->createTextNode( $text . ' ' );
-		$a->setAttribute( 'href', $extApi->getPageUri() . '#' . $href );
-		$s->setAttribute( 'class', 'mw-linkback-text' );
+		$span = $ownerDoc->createElement( 'span' );
+		$a->setAttribute( 'href', $extApi->getPageUri() . '#' . $target );
+		$span->setAttribute( 'class', 'mw-linkback-text' );
 		if ( $group ) {
 			$a->setAttribute( 'data-mw-group', $group );
 		}
-		$s->appendChild( $textNode );
-		$a->appendChild( $s );
+		$span->appendChild( $ownerDoc->createTextNode( $text . ' ' ) );
+		$a->appendChild( $span );
 		return $a;
 	}
 

src/Parsoid/RefProcessor.php

@@ -23,7 +23,7 @@ class RefProcessor extends DOMProcessor {
 		$refsData = new ReferencesData();
 		References::processRefs( $extApi, $refsData, $node );
 		References::insertMissingReferencesIntoDOM( $extApi, $refsData, $node );
-		if ( count( $refsData->embeddedErrors ) > 0 ) {
+		if ( $refsData->embeddedErrors ) {
 			References::addEmbeddedErrors( $extApi, $refsData, $node );
 		}
 	}
@@ -35,9 +35,6 @@ class RefProcessor extends DOMProcessor {
 	 *
 	 * But, for example, as part of some future functionality, this could be used to
 	 * reconstitute page-level information from local annotations left behind by editing clients.
-	 *
-	 * @param ParsoidExtensionAPI $extApi
-	 * @param Element $root
 	 */
 	public function htmlPreprocess( ParsoidExtensionAPI $extApi, Element $root ): void {
 		// TODO

src/Parsoid/References.php

@@ -50,8 +50,7 @@ class References extends ExtensionTagHandler {
 		$doc = $domFragment->ownerDocument;
 
 		$ol = $doc->createElement( 'ol' );
-		DOMCompat::getClassList( $ol )->add( 'mw-references' );
-		DOMCompat::getClassList( $ol )->add( 'references' );
+		DOMCompat::getClassList( $ol )->add( 'mw-references', 'references' );
 
 		DOMUtils::migrateChildren( $domFragment, $ol );
 
@@ -380,7 +379,7 @@ class References extends ExtensionTagHandler {
 
 		// FIXME(T214241): Should the errors be added to data-mw if
 		// $isTplWrapper?  Here and other calls to addErrorsToNode.
-		if ( count( $errs ) > 0 ) {
+		if ( $errs ) {
 			self::addErrorsToNode( $linkBack, $errs );
 		}
 
@@ -492,7 +491,7 @@ class References extends ExtensionTagHandler {
 					// the key should arguably be "cite_error_ref_no_text"
 					$errs[] = [ 'key' => 'cite_error_references_no_text' ];
 				}
-				if ( count( $errs ) > 0 ) {
+				if ( $errs ) {
 					foreach ( $ref->nodes as $node ) {
 						self::addErrorsToNode( $node, $errs );
 					}
@@ -522,7 +521,7 @@ class References extends ExtensionTagHandler {
 			// html -> wt and so that clients can strip it if necessary.
 			if ( $autoGenerated ) {
 				$dataMw->autoGenerated = true;
-			} elseif ( count( $nestedRefsHTML ) > 0 ) {
+			} elseif ( $nestedRefsHTML ) {
 				$dataMw->body = (object)[ 'html' => "\n" . implode( $nestedRefsHTML ) ];
 			} elseif ( empty( $dp->selfClose ) ) {
 				$dataMw->body = (object)[ 'html' => '' ];

src/Parsoid/ReferencesData.php

@@ -11,24 +11,14 @@ use Wikimedia\Parsoid\Ext\ParsoidExtensionAPI;
  */
 class ReferencesData {
 
-	/**
-	 * @var int
-	 */
-	private $index = 0;
-
-	/**
-	 * @var RefGroup[]
-	 */
-	private $refGroups = [];
-
-	/** @var array */
-	public $embeddedErrors = [];
-
-	/** @var array */
-	private $inEmbeddedContent = [];
-
-	/** @var string */
-	public $referencesGroup = '';
+	private int $index = 0;
+	/** @var array<string,RefGroup> indexed by group name */
+	private array $refGroups = [];
+	/** @var array<string,array[]> */
+	public array $embeddedErrors = [];
+	/** @var string[] */
+	private array $inEmbeddedContent = [];
+	public string $referencesGroup = '';
 
 	public function inReferencesContent(): bool {
 		return $this->inEmbeddedContent( 'references' );
@@ -38,7 +28,7 @@ class ReferencesData {
 		if ( $needle ) {
 			return in_array( $needle, $this->inEmbeddedContent, true );
 		} else {
-			return count( $this->inEmbeddedContent ) > 0;
+			return $this->inEmbeddedContent !== [];
 		}
 	}
 
@@ -53,8 +43,8 @@ class ReferencesData {
 	public function getRefGroup(
 		string $groupName, bool $allocIfMissing = false
 	): ?RefGroup {
-		if ( !isset( $this->refGroups[$groupName] ) && $allocIfMissing ) {
-			$this->refGroups[$groupName] = new RefGroup( $groupName );
+		if ( $allocIfMissing ) {
+			$this->refGroups[$groupName] ??= new RefGroup( $groupName );
 		}
 		return $this->refGroups[$groupName] ?? null;
 	}
@@ -80,7 +70,7 @@ class ReferencesData {
 		ParsoidExtensionAPI $extApi, string $groupName, string $refName, string $refDir
 	): RefGroupItem {
 		$group = $this->getRefGroup( $groupName, true );
-		$hasRefName = strlen( $refName ) > 0;
+		$hasRefName = $refName !== '';
 
 		// The ids produced Cite.php have some particulars:
 		// Simple refs get 'cite_ref-' + index
@@ -96,7 +86,7 @@ class ReferencesData {
 		$noteId = 'cite_note-' . ( $hasRefName ? $refNameSanitized . '-' . $refKey : $refKey );
 
 		// bump index
-		$this->index += 1;
+		$this->index++;
 
 		$ref = new RefGroupItem();
 		$ref->dir = $refDir;