Document a lot of methods

Clear up a bunch of phpcs ignores by documenting many methods.

Also remove Scribunto_LuaError::setLineMap(), which has apparently never
been used since it was added in Ia51f439e.

Change-Id: I763bcdbc7edbbb8e4600495a03acca3439fc0ec9

.phpcs.xml

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

includes/common/ApiScribuntoConsole.php

@@ -82,6 +82,15 @@ class ApiScribuntoConsole extends ApiBase {
 		}
 	}
 
+	/**
+	 * Execute the console
+	 * @param array $params
+	 *  - 'title': (Title) Module being processed
+	 *  - 'content': (string) New module text
+	 *  - 'prevQuestions': (string[]) Previous values for 'question' in this session.
+	 *  - 'question': (string) Lua code to run.
+	 * @return array Result data
+	 */
 	protected function runConsole( array $params ) {
 		$parser = MediaWikiServices::getInstance()->getParser();
 		$options = new ParserOptions;
@@ -129,6 +138,7 @@ class ApiScribuntoConsole extends ApiBase {
 		return true;
 	}
 
+	/** @inheritDoc */
 	public function getAllowedParams() {
 		return [
 			'title' => [

includes/common/ScribuntoContent.php

@@ -16,6 +16,9 @@ use MediaWiki\MediaWikiServices;
  */
 class ScribuntoContent extends TextContent {
 
+	/**
+	 * @param string $text
+	 */
 	public function __construct( $text ) {
 		parent::__construct( $text, CONTENT_MODEL_SCRIBUNTO );
 	}
@@ -32,6 +35,7 @@ class ScribuntoContent extends TextContent {
 		return $engine->validate( $this->getText(), $title->getPrefixedDBkey() );
 	}
 
+	/** @inheritDoc */
 	public function prepareSave( WikiPage $page, $flags, $parentRevId, User $user ) {
 		return $this->validate( $page->getTitle() );
 	}

includes/common/ScribuntoContentHandler.php

@@ -21,8 +21,11 @@ class ScribuntoContentHandler extends CodeContentHandler {
 		parent::__construct( $modelId, $formats );
 	}
 
+	/**
+	 * @return string Class name
+	 */
 	protected function getContentClass() {
-		return 'ScribuntoContent';
+		return ScribuntoContent::class;
 	}
 
 	/**

includes/engines/LuaCommon/LuaEngine.php

@@ -372,14 +372,17 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 		return $ret[0] ?? null;
 	}
 
+	/** @inheritDoc */
 	public function getGeSHiLanguage() {
 		return 'lua';
 	}
 
+	/** @inheritDoc */
 	public function getCodeEditorLanguage() {
 		return 'lua';
 	}
 
+	/** @inheritDoc */
 	public function runConsole( array $params ) {
 		// $resetFrames is a ScopedCallback, so it has a purpose even though it appears unused.
 		$resetFrames = $this->setupCurrentFrames();
@@ -885,6 +888,12 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 		return [ $this->getParser()->OutputType() === Parser::OT_WIKI ];
 	}
 
+	/**
+	 * @param PPFrame $frame
+	 * @param string|array $input
+	 * @param mixed $cacheKey
+	 * @return string
+	 */
 	private function doCachedExpansion( $frame, $input, $cacheKey ) {
 		$hash = md5( serialize( $cacheKey ) );
 		if ( isset( $this->expandCache[$hash] ) ) {

includes/engines/LuaCommon/LuaError.php

@@ -3,8 +3,12 @@
 use UtfNormal\Validator;
 
 class Scribunto_LuaError extends ScribuntoException {
-	public $luaMessage, $lineMap = [];
+	public $luaMessage;
 
+	/**
+	 * @param string $message
+	 * @param array $options
+	 */
 	public function __construct( $message, array $options = [] ) {
 		$this->luaMessage = $message;
 		$options = $options + [ 'args' => [ Validator::cleanUp( $message ) ] ];
@@ -17,14 +21,13 @@ class Scribunto_LuaError extends ScribuntoException {
 		parent::__construct( $msg, $options );
 	}
 
+	/**
+	 * @return string
+	 */
 	public function getLuaMessage() {
 		return $this->luaMessage;
 	}
 
-	public function setLineMap( $map ) {
-		$this->lineMap = $map;
-	}
-
 	/**
 	 * @param array $options Options for message processing. Currently supports:
 	 * $options['msgOptions']['content'] to use content language.

includes/engines/LuaCommon/MessageLibrary.php

@@ -20,6 +20,17 @@ class Scribunto_LuaMessageLibrary extends Scribunto_LuaLibraryBase {
 		] );
 	}
 
+	/**
+	 * Create a Message
+	 * @param array $data
+	 *  - 'rawMessage': (string, optional) If set, create a RawMessage using this as `$text`
+	 *  - 'keys': (string|string[]) Message keys. Required unless 'rawMessage' is set.
+	 *  - 'lang': (Language|StubUserLang|string) Language for the Message.
+	 *  - 'useDB': (bool) "Use database" flag.
+	 *  - 'params': (array) Parameters for the Message. May be omitted if $setParams is false.
+	 * @param bool $setParams Whether to use $data['params']
+	 * @return Message
+	 */
 	private function makeMessage( $data, $setParams ) {
 		if ( isset( $data['rawMessage'] ) ) {
 			$msg = new RawMessage( $data['rawMessage'] );

includes/engines/LuaCommon/TitleLibrary.php

@@ -26,6 +26,13 @@ class Scribunto_LuaTitleLibrary extends Scribunto_LuaLibraryBase {
 		] );
 	}
 
+	/**
+	 * Check a namespace parameter
+	 * @param string $name Function name (for errors)
+	 * @param int $argIdx Argument index (for errors)
+	 * @param mixed &$arg Argument
+	 * @param int|null $default Default value, if $arg is null
+	 */
 	private function checkNamespace( $name, $argIdx, &$arg, $default = null ) {
 		global $wgContLang;
 
@@ -261,7 +268,7 @@ class Scribunto_LuaTitleLibrary extends Scribunto_LuaLibraryBase {
 	 *
 	 * The title is counted as a transclusion.
 	 *
-	 * @param $text string Title text
+	 * @param string $text Title text
 	 * @return Content|null The Content object of the title, null if missing
 	 */
 	private function getContentInternal( $text ) {
@@ -349,6 +356,11 @@ class Scribunto_LuaTitleLibrary extends Scribunto_LuaLibraryBase {
 		] ];
 	}
 
+	/**
+	 * Renumber an array for return to Lua
+	 * @param array $arr
+	 * @return array
+	 */
 	private static function makeArrayOneBased( $arr ) {
 		if ( empty( $arr ) ) {
 			return $arr;

includes/engines/LuaCommon/UriLibrary.php

@@ -26,6 +26,13 @@ class Scribunto_LuaUriLibrary extends Scribunto_LuaLibraryBase {
 		) ];
 	}
 
+	/**
+	 * Get a URL (helper for handlers)
+	 * @param string $func Title class method to call
+	 * @param string $page Page title
+	 * @param array $query Query string
+	 * @return string[]|null[]
+	 */
 	private function getUrl( $func, $page, $query ) {
 		$title = Title::newFromText( $page );
 		if ( !$title ) {

includes/engines/LuaCommon/UstringLibrary.php

@@ -29,6 +29,7 @@ class Scribunto_LuaUstringLibrary extends Scribunto_LuaLibraryBase {
 	 */
 	private $patternRegexCache = null;
 
+	/** @inheritDoc */
 	public function __construct( $engine ) {
 		if ( $this->stringLengthLimit === null ) {
 			global $wgMaxArticleSize;
@@ -82,6 +83,12 @@ class Scribunto_LuaUstringLibrary extends Scribunto_LuaLibraryBase {
 		] );
 	}
 
+	/**
+	 * Check a string first parameter
+	 * @param string $name Function name, for errors
+	 * @param mixed $s Value to check
+	 * @param bool $checkEncoding Whether to validate UTF-8 encoding.
+	 */
 	private function checkString( $name, $s, $checkEncoding = true ) {
 		if ( $this->getLuaType( $s ) == 'number' ) {
 			$s = (string)$s;
@@ -335,6 +342,11 @@ class Scribunto_LuaUstringLibrary extends Scribunto_LuaLibraryBase {
 		return [ mb_strtolower( $s, 'UTF-8' ) ];
 	}
 
+	/**
+	 * Check a pattern as the second argument
+	 * @param string $name Lua function name, for errors
+	 * @param mixed $pattern Lua pattern
+	 */
 	private function checkPattern( $name, $pattern ) {
 		if ( $this->getLuaType( $pattern ) == 'number' ) {
 			$pattern = (string)$pattern;
@@ -350,7 +362,17 @@ class Scribunto_LuaUstringLibrary extends Scribunto_LuaLibraryBase {
 		}
 	}
 
-	/* Convert a Lua pattern into a PCRE regex */
+	/**
+	 * Convert a Lua pattern into a PCRE regex
+	 * @param string $pattern Lua pattern to convert
+	 * @param string|false $anchor Regex fragment (`^` or `\G`) to use
+	 *  when anchoring the start of the regex, or false to disable start-anchoring.
+	 * @param string $name Lua function name, for errors
+	 * @return array [ string $re, array $capt, bool $anypos ]
+	 *  - $re: The regular expression
+	 *  - $capt: Definition of capturing groups, see addCapturesFromMatch()
+	 *  - $anypos: Whether any positional captures were encountered in the pattern.
+	 */
 	private function patternToRegex( $pattern, $anchor, $name ) {
 		$cacheKey = serialize( [ $pattern, $anchor ] );
 		if ( !$this->patternRegexCache->has( $cacheKey ) ) {
@@ -538,6 +560,15 @@ class Scribunto_LuaUstringLibrary extends Scribunto_LuaLibraryBase {
 		return $this->patternRegexCache->get( $cacheKey );
 	}
 
+	/**
+	 * Convert a Lua pattern bracketed character set to a PCRE regex fragment
+	 * @param string[] $pat Pattern being processed, split into individual characters.
+	 * @param int $i Offset of the start of the bracketed character set in $pat.
+	 * @param int $len Length of $pat.
+	 * @param array $brcharsets Mapping from Lua pattern percent escapes to
+	 *  regex-style character ranges.
+	 * @return array [ int $new_i, string $re_fragment ]
+	 */
 	private function bracketedCharSetToRegex( $pat, $i, $len, $brcharsets ) {
 		$ii = $i + 1;
 		$re = '[';
@@ -588,6 +619,15 @@ class Scribunto_LuaUstringLibrary extends Scribunto_LuaLibraryBase {
 		return [ $i, $re ];
 	}
 
+	/**
+	 * Append captured groups to a result array
+	 * @param array $arr Result array to append to.
+	 * @param string $s String matched against.
+	 * @param array $m Matches, from preg_match with PREG_OFFSET_CAPTURE.
+	 * @param array $capt Capture groups (in $m) to process, see patternToRegex()
+	 * @param bool $m0_if_no_captures Whether to append "$0" if $capt is empty.
+	 * @return array
+	 */
 	private function addCapturesFromMatch( $arr, $s, $m, $capt, $m0_if_no_captures ) {
 		if ( count( $capt ) ) {
 			foreach ( $capt as $n => $pos ) {

includes/engines/LuaSandbox/LuaSandboxCallback.php

@@ -7,6 +7,9 @@ class Scribunto_LuaSandboxCallback {
 	 */
 	protected $callback;
 
+	/**
+	 * @param callable $callback
+	 */
 	public function __construct( $callback ) {
 		$this->callback = $callback;
 	}

includes/engines/LuaSandbox/LuaSandboxEngine.php

@@ -9,12 +9,14 @@ class Scribunto_LuaSandboxEngine extends Scribunto_LuaEngine {
 	 */
 	protected $interpreter;
 
+	/** @inheritDoc */
 	public function getPerformanceCharacteristics() {
 		return [
 			'phpCallsRequireSerialization' => false,
 		];
 	}
 
+	/** @inheritDoc */
 	public function getSoftwareInfo( array &$software ) {
 		try {
 			Scribunto_LuaSandboxInterpreter::checkLuaSandboxVersion();
@@ -37,6 +39,7 @@ class Scribunto_LuaSandboxEngine extends Scribunto_LuaEngine {
 		}
 	}
 
+	/** @inheritDoc */
 	public function getResourceUsage( $resource ) {
 		$this->load();
 		switch ( $resource ) {
@@ -49,6 +52,9 @@ class Scribunto_LuaSandboxEngine extends Scribunto_LuaEngine {
 		}
 	}
 
+	/**
+	 * @return array
+	 */
 	private function getLimitReportData() {
 		$ret = [];
 		$this->load();
@@ -110,6 +116,7 @@ class Scribunto_LuaSandboxEngine extends Scribunto_LuaEngine {
 		return $ret;
 	}
 
+	/** @inheritDoc */
 	public function reportLimitData( ParserOutput $output ) {
 		$data = $this->getLimitReportData();
 		foreach ( $data as $k => $v ) {
@@ -120,6 +127,7 @@ class Scribunto_LuaSandboxEngine extends Scribunto_LuaEngine {
 		}
 	}
 
+	/** @inheritDoc */
 	public function formatLimitData( $key, &$value, &$report, $isHTML, $localize ) {
 		global $wgLang;
 		$lang = $localize ? $wgLang : Language::factory( 'en' );
@@ -200,6 +208,11 @@ class Scribunto_LuaSandboxEngine extends Scribunto_LuaEngine {
 		return false;
 	}
 
+	/**
+	 * Fetch a line from mw.lua
+	 * @param int $lineNum
+	 * @return string
+	 */
 	protected function getMwLuaLine( $lineNum ) {
 		if ( !isset( $this->lineCache['mw.lua'] ) ) {
 			$this->lineCache['mw.lua'] = file( $this->getLuaLibDir() . '/mw.lua' );

includes/engines/LuaSandbox/LuaSandboxInterpreter.php

@@ -39,6 +39,10 @@ class Scribunto_LuaSandboxInterpreter extends Scribunto_LuaInterpreter {
 		}
 	}
 
+	/**
+	 * @param Scribunto_LuaEngine $engine
+	 * @param array $options
+	 */
 	public function __construct( $engine, array $options ) {
 		self::checkLuaSandboxVersion();
 
@@ -55,6 +59,11 @@ class Scribunto_LuaSandboxInterpreter extends Scribunto_LuaInterpreter {
 		}
 	}
 
+	/**
+	 * Convert a LuaSandboxError to a Scribunto_LuaError
+	 * @param LuaSandboxError $e
+	 * @return Scribunto_LuaError
+	 */
 	protected function convertSandboxError( LuaSandboxError $e ) {
 		$opts = [];
 		if ( isset( $e->luaTrace ) ) {
@@ -83,6 +92,7 @@ class Scribunto_LuaSandboxInterpreter extends Scribunto_LuaInterpreter {
 		}
 	}
 
+	/** @inheritDoc */
 	public function registerLibrary( $name, array $functions ) {
 		$realLibrary = [];
 		foreach ( $functions as $funcName => $callback ) {
@@ -97,6 +107,7 @@ class Scribunto_LuaSandboxInterpreter extends Scribunto_LuaInterpreter {
 		# 	$name, [ $this, 'callback' ], $functions );
 	}
 
+	/** @inheritDoc */
 	public function callFunction( $func, ...$args ) {
 		try {
 			$ret = $func->call( ...$args );
@@ -115,22 +126,34 @@ class Scribunto_LuaSandboxInterpreter extends Scribunto_LuaInterpreter {
 		}
 	}
 
+	/** @inheritDoc */
 	public function wrapPhpFunction( $callable ) {
 		return $this->sandbox->wrapPhpFunction( $callable );
 	}
 
+	/** @inheritDoc */
 	public function isLuaFunction( $object ) {
 		return $object instanceof LuaSandboxFunction;
 	}
 
+	/**
+	 * @return int
+	 */
 	public function getPeakMemoryUsage() {
 		return $this->sandbox->getPeakMemoryUsage();
 	}
 
+	/**
+	 * @return float
+	 */
 	public function getCPUUsage() {
 		return $this->sandbox->getCPUUsage();
 	}
 
+	/**
+	 * @param int $units self::SAMPLES, self::SECONDS, or self::PERCENT
+	 * @return array
+	 */
 	public function getProfilerFunctionReport( $units ) {
 		if ( $this->profilerEnabled ) {
 			static $unitsMap;

includes/engines/LuaStandalone/LuaStandaloneEngine.php

@@ -21,12 +21,14 @@ class Scribunto_LuaStandaloneEngine extends Scribunto_LuaEngine {
 		}
 	}
 
+	/** @inheritDoc */
 	public function getPerformanceCharacteristics() {
 		return [
 			'phpCallsRequireSerialization' => true,
 		];
 	}
 
+	/** @inheritDoc */
 	public function reportLimitData( ParserOutput $output ) {
 		try {
 			$this->load();
@@ -59,6 +61,7 @@ class Scribunto_LuaStandaloneEngine extends Scribunto_LuaEngine {
 		}
 	}
 
+	/** @inheritDoc */
 	public function formatLimitData( $key, &$value, &$report, $isHTML, $localize ) {
 		global $wgLang;
 		$lang = $localize ? $wgLang : Language::factory( 'en' );
@@ -102,6 +105,7 @@ class Scribunto_LuaStandaloneEngine extends Scribunto_LuaEngine {
 		] );
 	}
 
+	/** @inheritDoc */
 	public function getSoftwareInfo( array &$software ) {
 		$ver = Scribunto_LuaStandaloneInterpreter::getLuaVersion( $this->options );
 		if ( $ver !== null ) {

includes/engines/LuaStandalone/LuaStandaloneInterpreter.php

@@ -169,6 +169,11 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		$this->terminate();
 	}
 
+	/**
+	 * Fetch the Lua version
+	 * @param array $options Engine options
+	 * @return string|null
+	 */
 	public static function getLuaVersion( array $options ) {
 		if ( $options['luaPath'] === null ) {
 			// We know which versions are distributed, no need to run them.
@@ -240,6 +245,7 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		return new Scribunto_LuaStandaloneInterpreterFunction( $this->id, $result[1] );
 	}
 
+	/** @inheritDoc */
 	public function callFunction( $func, ...$args ) {
 		if ( !( $func instanceof Scribunto_LuaStandaloneInterpreterFunction ) ) {
 			throw new MWException( __METHOD__ . ': invalid function type' );
@@ -263,6 +269,7 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		return array_values( $result );
 	}
 
+	/** @inheritDoc */
 	public function wrapPhpFunction( $callable ) {
 		static $uid = 0;
 		$id = "anonymous*" . ++$uid;
@@ -284,10 +291,12 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		}
 	}
 
+	/** @inheritDoc */
 	public function isLuaFunction( $object ) {
 		return $object instanceof Scribunto_LuaStandaloneInterpreterFunction;
 	}
 
+	/** @inheritDoc */
 	public function registerLibrary( $name, array $functions ) {
 		// Make sure all ids are unique, even when libraries share the same name
 		// which is especially relevant for "mw_interface" (T211203).
@@ -307,6 +316,10 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		] );
 	}
 
+	/**
+	 * Get interpreter status
+	 * @return array
+	 */
 	public function getStatus() {
 		$result = $this->dispatch( [
 			'op' => 'getStatus',
@@ -335,6 +348,11 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		}
 	}
 
+	/**
+	 * Handle a protocol 'call' message from Lua
+	 * @param array $message
+	 * @return array Response message to send to Lua
+	 */
 	protected function handleCall( $message ) {
 		$message['args'] = self::fixNulls( $message['args'], $message['nargs'] );
 		try {
@@ -355,16 +373,28 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 
 		return [
 			'op' => 'return',
-			// @phan-suppress-next-line PhanTypeMismatchArgumentNullableInternal result always array
 			'nvalues' => count( $result ),
 			'values' => $result
 		];
 	}
 
+	/**
+	 * Call a registered/wrapped PHP function from Lua
+	 * @param string $id Callback ID
+	 * @param array $args Arguments to pass to the callback
+	 * @return mixed Return value from the callback
+	 */
 	protected function callback( $id, array $args ) {
 		return ( $this->callbacks[$id] )( ...$args );
 	}
 
+	/**
+	 * Handle a protocol error response
+	 *
+	 * Converts the encoded Lua error to an appropriate exception and throws it.
+	 *
+	 * @param array $message
+	 */
 	protected function handleError( $message ) {
 		$opts = [];
 		if ( preg_match( '/^(.*?):(\d+): (.*)$/', $message['value'], $m ) ) {
@@ -378,6 +408,11 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		throw $this->engine->newLuaError( $message['value'], $opts );
 	}
 
+	/**
+	 * Send a protocol message to Lua, and handle any responses
+	 * @param array $msgToLua
+	 * @return mixed Response data
+	 */
 	protected function dispatch( $msgToLua ) {
 		$this->sendMessage( $msgToLua );
 		while ( true ) {
@@ -400,6 +435,10 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		}
 	}
 
+	/**
+	 * Send a protocol message to Lua
+	 * @param array $msg
+	 */
 	protected function sendMessage( $msg ) {
 		$this->debug( "TX ==> {$msg['op']}" );
 		$this->checkValid();
@@ -413,6 +452,10 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		}
 	}
 
+	/**
+	 * Receive a protocol message from Lua
+	 * @return array
+	 */
 	protected function receiveMessage() {
 		$this->checkValid();
 		// Read the header
@@ -445,6 +488,11 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		return $msg;
 	}
 
+	/**
+	 * Encode a protocol message to send to Lua
+	 * @param mixed $message
+	 * @return string
+	 */
 	protected function encodeMessage( $message ) {
 		$serialized = $this->encodeLuaVar( $message );
 		$length = strlen( $serialized );
@@ -531,6 +579,11 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		}
 	}
 
+	/**
+	 * Verify protocol header and extract the body length.
+	 * @param string $header
+	 * @return int Length
+	 */
 	protected function decodeHeader( $header ) {
 		$length = substr( $header, 0, 8 );
 		$check = substr( $header, 8, 8 );
@@ -608,6 +661,9 @@ class Scribunto_LuaStandaloneInterpreter extends Scribunto_LuaInterpreter {
 		throw $this->exitError;
 	}
 
+	/**
+	 * @param string $msg
+	 */
 	protected function debug( $msg ) {
 		if ( $this->enableDebug ) {
 			$this->logger->debug( "Lua: $msg\n" );

tests/phpunit/engines/LuaCommon/LuaDataProvider.php

@@ -5,6 +5,10 @@ class Scribunto_LuaDataProvider implements Iterator {
 	protected $exports = null;
 	protected $key = 1;
 
+	/**
+	 * @param Scribunto_LuaEngine $engine
+	 * @param string $moduleName
+	 */
 	public function __construct( $engine, $moduleName ) {
 		$this->engine = $engine;
 		$this->key = 1;
@@ -45,6 +49,10 @@ class Scribunto_LuaDataProvider implements Iterator {
 		return $this->engine->getInterpreter()->callFunction( $this->exports['provide'], $this->key );
 	}
 
+	/**
+	 * @param string $key Test to run
+	 * @return mixed Test result
+	 */
 	public function run( $key ) {
 		list( $ret ) = $this->engine->getInterpreter()->callFunction( $this->exports['run'], $key );
 		return $ret;

tests/phpunit/engines/LuaCommon/LuaEngineTestBase.php

@@ -41,6 +41,12 @@ abstract class Scribunto_LuaEngineTestBase extends MediaWikiLangTestCase {
 	 */
 	protected $skipTests = [];
 
+	/**
+	 * @param string|null $name
+	 * @param array $data
+	 * @param string $dataName
+	 * @param string|null $engineName Engine to test with
+	 */
 	public function __construct(
 		$name = null, array $data = [], $dataName = '', $engineName = null
 	) {
@@ -51,6 +57,11 @@ abstract class Scribunto_LuaEngineTestBase extends MediaWikiLangTestCase {
 		parent::__construct( $name, $data, $dataName );
 	}
 
+	/**
+	 * Create a PHPUnit test suite to run the test against all engines
+	 * @param string $className Test class name
+	 * @return \PHPUnit\Framework\TestSuite
+	 */
 	public static function suite( $className ) {
 		return self::makeSuite( $className );
 	}
@@ -85,6 +96,10 @@ abstract class Scribunto_LuaEngineTestBase extends MediaWikiLangTestCase {
 		return $this->engineName . ': ' . parent::toString();
 	}
 
+	/**
+	 * Modules that should exist
+	 * @return string[] Mapping module names to files
+	 */
 	protected function getTestModules() {
 		return [
 			'TestFramework' => __DIR__ . '/TestFramework.lua',

tests/phpunit/engines/LuaCommon/LuaEngineTestHelper.php

@@ -26,6 +26,12 @@ trait Scribunto_LuaEngineTestHelper {
 		],
 	];
 
+	/**
+	 * Create a PHPUnit test suite to run the test against all engines
+	 * @param string $className Test class name
+	 * @param string|null $group Engine to run with, or null to run all engines
+	 * @return TestSuite
+	 */
 	protected static function makeSuite( $className, $group = null ) {
 		$suite = new TestSuite;
 		$suite->setName( $className );
@@ -143,6 +149,12 @@ trait Scribunto_LuaEngineTestHelper {
 		return $this->engine;
 	}
 
+	/**
+	 * @see Parser::statelessFetchTemplate
+	 * @param Title $title
+	 * @param Parser|false $parser
+	 * @return array
+	 */
 	public function templateCallback( $title, $parser ) {
 		if ( isset( $this->extraModules[$title->getFullText()] ) ) {
 			return [

tests/phpunit/engines/LuaCommon/LuaEngineTestSkip.php

@@ -4,6 +4,10 @@ class Scribunto_LuaEngineTestSkip extends PHPUnit\Framework\TestCase {
 	private $className = '';
 	private $message = '';
 
+	/**
+	 * @param string $className Class being skipped
+	 * @param string $message Skip message
+	 */
 	public function __construct( $className = '', $message = '' ) {
 		$this->className = $className;
 		$this->message = $message;

tests/phpunit/engines/LuaCommon/LuaEngineUnitTestBase.php

@@ -42,6 +42,12 @@ abstract class Scribunto_LuaEngineUnitTestBase extends \PHPUnit\Framework\TestCa
 	 */
 	protected $skipTests = [];
 
+	/**
+	 * @param string|null $name
+	 * @param array $data
+	 * @param string $dataName
+	 * @param string|null $engineName Engine to test with
+	 */
 	public function __construct(
 		$name = null, array $data = [], $dataName = '', $engineName = null
 	) {
@@ -52,6 +58,11 @@ abstract class Scribunto_LuaEngineUnitTestBase extends \PHPUnit\Framework\TestCa
 		parent::__construct( $name, $data, $dataName );
 	}
 
+	/**
+	 * Create a PHPUnit test suite to run the test against all engines
+	 * @param string $className Test class name
+	 * @return \PHPUnit\Framework\TestSuite
+	 */
 	public static function suite( $className ) {
 		return self::makeSuite( $className );
 	}
@@ -77,6 +88,10 @@ abstract class Scribunto_LuaEngineUnitTestBase extends \PHPUnit\Framework\TestCa
 		return $this->engineName . ': ' . parent::toString();
 	}
 
+	/**
+	 * Modules that should exist
+	 * @return string[] Mapping module names to files
+	 */
 	protected function getTestModules() {
 		return [
 			'TestFramework' => __DIR__ . '/TestFramework.lua',

tests/phpunit/engines/LuaCommon/UstringLibraryNormalizationTestProvider.php

@@ -9,17 +9,24 @@ class UstringLibraryNormalizationTestProvider extends Scribunto_LuaDataProvider
 		false
 	];
 
+	/**
+	 * @param string|null &$message Message to report when skipping
+	 * @return bool Whether the test can be run
+	 */
 	public static function available( &$message = null ) {
 		if ( is_readable( __DIR__ . '/NormalizationTest.txt' ) ) {
 			return true;
 		}
 		$message = wordwrap( 'Download the Unicode Normalization Test Suite from ' .
-			'http://unicode.org/Public/6.0.0/ucd/NormalizationTest.txt and save as ' .
+			'http://unicode.org/Public/8.0.0/ucd/NormalizationTest.txt and save as ' .
 			__DIR__ . '/NormalizationTest.txt to run normalization tests. Note that ' .
 			'running these tests takes quite some time.' );
 		return false;
 	}
 
+	/**
+	 * @param Scribunto_LuaEngine $engine
+	 */
 	public function __construct( $engine ) {
 		parent::__construct( $engine, 'UstringLibraryNormalizationTests' );
 		if ( self::available() ) {
@@ -84,6 +91,15 @@ class UstringLibraryNormalizationTestProvider extends Scribunto_LuaDataProvider
 		}
 	}
 
+	/**
+	 * Run the normalization test
+	 * @param string $c1 Column 1 from NormalizationTest.txt
+	 * @param string $c2 Column 2 from NormalizationTest.txt
+	 * @param string $c3 Column 3 from NormalizationTest.txt
+	 * @param string $c4 Column 4 from NormalizationTest.txt
+	 * @param string $c5 Column 5 from NormalizationTest.txt
+	 * @return array
+	 */
 	public function runNorm( $c1, $c2, $c3, $c4, $c5 ) {
 		return $this->engine->getInterpreter()->callFunction( $this->exports['run'],
 			$c1, $c2, $c3, $c4, $c5