Add missing @var and improve documentation

Change-Id: Idb7ff848ba702eac2cde31c6198a70311e3bdb69

.phpcs.xml

@@ -1,11 +1,6 @@
 <?xml version="1.0"?>
 <ruleset name="Scribunto">
 	<rule ref="./vendor/mediawiki/mediawiki-codesniffer/MediaWiki">
-		<exclude name="MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam" />
-		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingDocumentationPrivate" />
-		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingDocumentationProtected" />
-		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingDocumentationPublic" />
-		<exclude name="MediaWiki.Commenting.PropertyDocumentation.WrongStyle" />
 		<exclude name="MediaWiki.Files.ClassMatchesFilename.NotMatch" />
 		<exclude name="MediaWiki.Usage.ForbiddenFunctions.popen" />
 		<exclude name="MediaWiki.Usage.ForbiddenFunctions.proc_open" />

includes/engines/LuaCommon/LanguageLibrary.php

@@ -3,8 +3,11 @@
 use MediaWiki\MediaWikiServices;
 
 class Scribunto_LuaLanguageLibrary extends Scribunto_LuaLibraryBase {
+	/** @var Language[] */
 	public $langCache = [];
+	/** @var array */
 	public $timeCache = [];
+	/** @var int */
 	public $maxLangCacheSize;
 
 	public function register() {

includes/engines/LuaCommon/LuaEngine.php

@@ -30,6 +30,7 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 		'ustring',
 	];
 
+	/** @var bool */
 	protected $loaded = false;
 
 	/**
@@ -46,7 +47,13 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 	 * @var array
 	 */
 	protected $currentFrames = [];
+	/**
+	 * @var array|null
+	 */
 	protected $expandCache = [];
+	/**
+	 * @var array
+	 */
 	protected $availableLibraries = [];
 
 	private const MAX_EXPAND_CACHE_SIZE = 100;

includes/engines/LuaCommon/LuaError.php

@@ -3,6 +3,7 @@
 use UtfNormal\Validator;
 
 class Scribunto_LuaError extends ScribuntoException {
+	/** @var string */
 	public $luaMessage;
 
 	/**

includes/engines/LuaCommon/LuaInterpreter.php

@@ -25,14 +25,14 @@ abstract class Scribunto_LuaInterpreter {
 	 * Lua. If an error occurs, a Scribunto_LuaError will be thrown.
 	 *
 	 * @param callable $callable The PHP callable
-	 * @return object a Lua function
+	 * @return LuaSandboxFunction a Lua function
 	 */
 	abstract public function wrapPhpFunction( $callable );
 
 	/**
 	 * Test whether an object is a Lua function.
 	 *
-	 * @param object $object
+	 * @param mixed|LuaSandboxFunction $object
 	 * @return bool
 	 */
 	abstract public function isLuaFunction( $object );

includes/engines/LuaCommon/SiteLibrary.php

@@ -3,9 +3,13 @@
 use MediaWiki\MediaWikiServices;
 
 class Scribunto_LuaSiteLibrary extends Scribunto_LuaLibraryBase {
+	/** @var string|null */
 	private static $namespacesCacheLang = null;
+	/** @var array[]|null */
 	private static $namespacesCache = null;
+	/** @var array[] */
 	private static $interwikiMapCache = [];
+	/** @var int[][] */
 	private $pagesInCategoryCache = [];
 
 	public function register() {

includes/engines/LuaCommon/TitleLibrary.php

@@ -10,7 +10,9 @@ class Scribunto_LuaTitleLibrary extends Scribunto_LuaLibraryBase {
 	// $wgExpensiveParserFunctionLimit + 1 actual Title objects because any
 	// addition besides the one for the current page calls
 	// incrementExpensiveFunctionCount()
+	/** @var Title[] */
 	private $titleCache = [];
+	/** @var (Title|null)[] */
 	private $idCache = [ 0 => null ];
 
 	public function register() {

includes/engines/LuaSandbox/LuaSandboxEngine.php

@@ -1,7 +1,11 @@
 <?php
 
 class Scribunto_LuaSandboxEngine extends Scribunto_LuaEngine {
-	public $options, $loaded = false;
+	/** @var array */
+	public $options;
+	/** @var bool */
+	public $loaded = false;
+	/** @var array */
 	protected $lineCache = [];
 
 	/**

includes/engines/LuaStandalone/LuaStandaloneEngine.php

@@ -3,8 +3,9 @@
 use MediaWiki\Logger\LoggerFactory;
 
 class Scribunto_LuaStandaloneEngine extends Scribunto_LuaEngine {
+	/** @var int|null */
 	protected static $clockTick;
-	/** @var array|bool */
+	/** @var array|false */
 	public $initialStatus;
 
 	/**
@@ -76,7 +77,7 @@ class Scribunto_LuaStandaloneEngine extends Scribunto_LuaEngine {
 	}
 
 	/**
-	 * @return mixed
+	 * @return int
 	 */
 	protected function getClockTick() {
 		if ( self::$clockTick === null ) {

includes/engines/LuaStandalone/LuaStandaloneInterpreter.php

@@ -4,6 +4,7 @@ use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 
 class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
+	/** @var int */
 	protected static $nextInterpreterId = 0;
 
 	/**

includes/engines/LuaStandalone/LuaStandaloneInterpreterFunction.php

@@ -1,7 +1,9 @@
 <?php
 
 class Scribunto_LuaStandaloneInterpreterFunction {
+	/** @var bool[] */
 	public static $anyChunksDestroyed = [];
+	/** @var int[][] */
 	public static $activeChunkIds = [];
 
 	/**

tests/phpunit/engines/LuaCommon/LuaDataProvider.php

@@ -1,8 +1,11 @@
 <?php
 
 class Scribunto_LuaDataProvider implements Iterator {
+	/** @var Scribunto_LuaEngine|null */
 	protected $engine = null;
+	/** @var mixed|null */
 	protected $exports = null;
+	/** @var int */
 	protected $key = 1;
 
 	/**

tests/phpunit/engines/LuaCommon/LuaEngineTestBase.php

@@ -12,9 +12,13 @@
 abstract class Scribunto_LuaEngineTestBase extends MediaWikiLangTestCase {
 	use Scribunto_LuaEngineTestHelper;
 
+	/** @var string|null */
 	private static $staticEngineName = null;
+	/** @var string|null */
 	private $engineName = null;
+	/** @var Scribunto_LuaEngine|null */
 	private $engine = null;
+	/** @var Scribunto_LuaDataProvider|null */
 	private $luaDataProvider = null;
 
 	/**

tests/phpunit/engines/LuaCommon/LuaEngineTestHelper.php

@@ -11,6 +11,7 @@ use PHPUnit\Util\Test;
  * Trait that helps LuaEngineTestBase and LuaEngineUnitTestBase
  */
 trait Scribunto_LuaEngineTestHelper {
+	/** @var array[] */
 	private static $engineConfigurations = [
 		'LuaSandbox' => [
 			'memoryLimit' => 50000000,

tests/phpunit/engines/LuaCommon/LuaEngineTestSkip.php

@@ -1,7 +1,9 @@
 <?php
 
 class Scribunto_LuaEngineTestSkip extends PHPUnit\Framework\TestCase {
+	/** @var string */
 	private $className = '';
+	/** @var string */
 	private $message = '';
 
 	/**

tests/phpunit/engines/LuaCommon/LuaEngineUnitTestBase.php

@@ -13,9 +13,13 @@ abstract class Scribunto_LuaEngineUnitTestBase extends \PHPUnit\Framework\TestCa
 	use MediaWikiCoversValidator;
 	use Scribunto_LuaEngineTestHelper;
 
+	/** @var string|null */
 	private static $staticEngineName = null;
+	/** @var string|null */
 	private $engineName = null;
+	/** @var Scribunto_LuaEngine|null */
 	private $engine = null;
+	/** @var Scribunto_LuaDataProvider|null */
 	private $luaDataProvider = null;
 
 	/**

tests/phpunit/engines/LuaCommon/UstringLibraryNormalizationTestProvider.php

@@ -1,8 +1,11 @@
 <?php
 
 class UstringLibraryNormalizationTestProvider extends Scribunto_LuaDataProvider {
+	/** @var resource|null */
 	protected $file = null;
+	/** @var string[]|null */
 	protected $current = null;
+	/** @var array */
 	protected static $static = [
 		'1E0A 0323;1E0C 0307;0044 0323 0307;1E0C 0307;0044 0323 0307;',
 		false