Improve a few PHPDoc type hints

Mostly unspecific arrays that can be made more specific. This patch
intentionally doesn't touch any code, only comments.

Change-Id: I5b4690e6160c6c543f9fcb2f62c41f6329d48bdb

includes/Engines/LuaCommon/LanguageLibrary.php

@@ -18,7 +18,7 @@ use Wikimedia\RequestTimeout\TimeoutException;
 class LanguageLibrary extends LibraryBase {
 	/** @var Language[] */
 	public $langCache = [];
-	/** @var array */
+	/** @var array[] */
 	public $timeCache = [];
 	/** @var int */
 	public $maxLangCacheSize;

includes/Engines/LuaCommon/LuaEngine.php

@@ -20,7 +20,7 @@ use Wikimedia\ScopedCallback;
 abstract class LuaEngine extends ScribuntoEngineBase {
 	/**
 	 * Libraries to load. See also the 'ScribuntoExternalLibraries' hook.
-	 * @var array Maps module names to PHP classes or definition arrays
+	 * @var array<string,class-string<LibraryBase>> Maps module names to PHP classes or definition arrays
 	 */
 	protected static $libraryClasses = [
 		'mw.site' => SiteLibrary::class,
@@ -37,7 +37,7 @@ abstract class LuaEngine extends ScribuntoEngineBase {
 	/**
 	 * Paths for modules that may be loaded from Lua. See also the
 	 * 'ScribuntoExternalLibraryPaths' hook.
-	 * @var array Paths
+	 * @var string[] Paths
 	 */
 	protected static $libraryPaths = [
 		'.',
@@ -59,15 +59,15 @@ abstract class LuaEngine extends ScribuntoEngineBase {
 	protected $mw;
 
 	/**
-	 * @var array
+	 * @var array<string,?PPFrame>
 	 */
 	protected $currentFrames = [];
 	/**
-	 * @var array|null
+	 * @var array<string,string>|null
 	 */
 	protected $expandCache = [];
 	/**
-	 * @var array
+	 * @var array<string,array|class-string<LibraryBase>>
 	 */
 	protected $availableLibraries = [];
 
@@ -189,7 +189,7 @@ abstract class LuaEngine extends ScribuntoEngineBase {
 	 *
 	 * @param string $moduleFileName The path to the Lua portion of the library
 	 *         (absolute, or relative to $this->getLuaLibDir())
-	 * @param array $interfaceFuncs Populates mw_interface
+	 * @param array<string,callable> $interfaceFuncs Populates mw_interface
 	 * @param array $setupOptions Passed to the modules setupInterface() method.
 	 * @return array Lua package
 	 */
@@ -474,7 +474,7 @@ abstract class LuaEngine extends ScribuntoEngineBase {
 	 * @param string $funcName The Lua function name, for use in error messages
 	 * @param array $args The argument array
 	 * @param int $index0 The zero-based argument index
-	 * @param string|array $type The allowed type names as given by gettype()
+	 * @param string|string[] $type The allowed type names as given by gettype()
 	 * @param string $msgType The type name used in the error message
 	 * @throws LuaError
 	 */
@@ -513,19 +513,21 @@ abstract class LuaEngine extends ScribuntoEngineBase {
 	/**
 	 * Instantiate and register a library.
 	 * @param string $name
-	 * @param array|string $def
+	 * @param array|class-string<LibraryBase> $def
 	 * @param bool $loadDeferred
 	 * @return array|null
 	 */
 	private function instantiatePHPLibrary( $name, $def, $loadDeferred ) {
 		$def = $this->availableLibraries[$name];
 		if ( is_string( $def ) ) {
+			/** @var LibraryBase $class */
 			$class = new $def( $this );
 		} else {
 			if ( !$loadDeferred && !empty( $def['deferLoad'] ) ) {
 				return null;
 			}
 			if ( isset( $def['class'] ) ) {
+				/** @var LibraryBase $class */
 				$class = new $def['class']( $this );
 			} else {
 				throw new RuntimeException( "No class for library \"$name\"" );
@@ -607,6 +609,7 @@ abstract class LuaEngine extends ScribuntoEngineBase {
 		if ( $frameId === 'empty' ) {
 			return $this->getParser()->getPreprocessor()->newFrame();
 		} elseif ( isset( $this->currentFrames[$frameId] ) ) {
+			// @phan-suppress-next-line PhanTypeMismatchReturnNullable False positive
 			return $this->currentFrames[$frameId];
 		} else {
 			throw new LuaError( 'invalid frame ID' );

includes/Engines/LuaCommon/LuaInterpreter.php

@@ -21,6 +21,7 @@ abstract class LuaInterpreter {
 	 *
 	 * @param mixed $func The function object
 	 * @param mixed ...$args Arguments to the function
+	 * @return array
 	 */
 	abstract public function callFunction( $func, ...$args );
 
@@ -45,7 +46,7 @@ abstract class LuaInterpreter {
 	 * Register a library of functions.
 	 *
 	 * @param string $name The global variable name to be created or added to.
-	 * @param array $functions An associative array mapping the function name to the
+	 * @param array<string,callable> $functions An associative array mapping the function name to the
 	 *    callback. The callback may throw a LuaError, which will be
 	 *    caught and raised in the Lua code as a Lua error, catchable with
 	 *    pcall().

includes/Hooks.php

@@ -52,6 +52,7 @@ use MediaWiki\Title\Title;
 use MediaWiki\User\User;
 use MediaWiki\WikiMap\WikiMap;
 use PPFrame;
+use PPNode;
 use UtfNormal\Validator;
 use Wikimedia\PSquare;
 
@@ -135,7 +136,7 @@ class Hooks implements
 	 *
 	 * @param Parser $parser
 	 * @param PPFrame $frame
-	 * @param array $args
+	 * @param PPNode[] $args
 	 * @return string
 	 */
 	public function invokeHook( Parser $parser, PPFrame $frame, array $args ) {

includes/ScribuntoContentHandler.php

@@ -38,9 +38,7 @@ class ScribuntoContentHandler extends CodeContentHandler {
 		parent::__construct( $modelId, $formats );
 	}
 
-	/**
-	 * @return string Class name
-	 */
+	/** @inheritDoc */
 	protected function getContentClass() {
 		return ScribuntoContent::class;
 	}