From 3a19bb8b0c499c6a5a6fa021fcb918659e8309dc Mon Sep 17 00:00:00 2001 From: Brad Jorsch Date: Tue, 14 Jan 2020 13:50:34 -0500 Subject: [PATCH] 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 | 6 -- includes/common/ApiScribuntoConsole.php | 10 ++++ includes/common/ScribuntoContent.php | 4 ++ includes/common/ScribuntoContentHandler.php | 5 +- includes/engines/LuaCommon/LuaEngine.php | 9 +++ includes/engines/LuaCommon/LuaError.php | 13 +++-- includes/engines/LuaCommon/MessageLibrary.php | 11 ++++ includes/engines/LuaCommon/TitleLibrary.php | 14 ++++- includes/engines/LuaCommon/UriLibrary.php | 7 +++ includes/engines/LuaCommon/UstringLibrary.php | 42 +++++++++++++- .../engines/LuaSandbox/LuaSandboxCallback.php | 3 + .../engines/LuaSandbox/LuaSandboxEngine.php | 13 +++++ .../LuaSandbox/LuaSandboxInterpreter.php | 23 ++++++++ .../LuaStandalone/LuaStandaloneEngine.php | 4 ++ .../LuaStandaloneInterpreter.php | 58 ++++++++++++++++++- .../engines/LuaCommon/LuaDataProvider.php | 8 +++ .../engines/LuaCommon/LuaEngineTestBase.php | 15 +++++ .../engines/LuaCommon/LuaEngineTestHelper.php | 12 ++++ .../engines/LuaCommon/LuaEngineTestSkip.php | 4 ++ .../LuaCommon/LuaEngineUnitTestBase.php | 15 +++++ ...stringLibraryNormalizationTestProvider.php | 18 +++++- 21 files changed, 278 insertions(+), 16 deletions(-) diff --git a/.phpcs.xml b/.phpcs.xml index 05001f2e..ae483e59 100644 --- a/.phpcs.xml +++ b/.phpcs.xml @@ -1,12 +1,6 @@ - - - - - - diff --git a/includes/common/ApiScribuntoConsole.php b/includes/common/ApiScribuntoConsole.php index 2676f08e..22ea645f 100644 --- a/includes/common/ApiScribuntoConsole.php +++ b/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' => [ diff --git a/includes/common/ScribuntoContent.php b/includes/common/ScribuntoContent.php index 2b225d5e..f094f899 100644 --- a/includes/common/ScribuntoContent.php +++ b/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() ); } diff --git a/includes/common/ScribuntoContentHandler.php b/includes/common/ScribuntoContentHandler.php index ad2c1baa..a9506998 100644 --- a/includes/common/ScribuntoContentHandler.php +++ b/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; } /** diff --git a/includes/engines/LuaCommon/LuaEngine.php b/includes/engines/LuaCommon/LuaEngine.php index 1f8a24f5..73f58475 100644 --- a/includes/engines/LuaCommon/LuaEngine.php +++ b/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] ) ) { diff --git a/includes/engines/LuaCommon/LuaError.php b/includes/engines/LuaCommon/LuaError.php index 5bb88bc5..e48dbf2c 100644 --- a/includes/engines/LuaCommon/LuaError.php +++ b/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. diff --git a/includes/engines/LuaCommon/MessageLibrary.php b/includes/engines/LuaCommon/MessageLibrary.php index b204e027..b7aebdf5 100644 --- a/includes/engines/LuaCommon/MessageLibrary.php +++ b/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'] ); diff --git a/includes/engines/LuaCommon/TitleLibrary.php b/includes/engines/LuaCommon/TitleLibrary.php index 6a53bc49..ed89bb49 100644 --- a/includes/engines/LuaCommon/TitleLibrary.php +++ b/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; diff --git a/includes/engines/LuaCommon/UriLibrary.php b/includes/engines/LuaCommon/UriLibrary.php index dd400cc6..448b0675 100644 --- a/includes/engines/LuaCommon/UriLibrary.php +++ b/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 ) { diff --git a/includes/engines/LuaCommon/UstringLibrary.php b/includes/engines/LuaCommon/UstringLibrary.php index b7ada6af..420dfbf3 100644 --- a/includes/engines/LuaCommon/UstringLibrary.php +++ b/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 ) { diff --git a/includes/engines/LuaSandbox/LuaSandboxCallback.php b/includes/engines/LuaSandbox/LuaSandboxCallback.php index 938bc69e..2f7bfe70 100644 --- a/includes/engines/LuaSandbox/LuaSandboxCallback.php +++ b/includes/engines/LuaSandbox/LuaSandboxCallback.php @@ -7,6 +7,9 @@ class Scribunto_LuaSandboxCallback { */ protected $callback; + /** + * @param callable $callback + */ public function __construct( $callback ) { $this->callback = $callback; } diff --git a/includes/engines/LuaSandbox/LuaSandboxEngine.php b/includes/engines/LuaSandbox/LuaSandboxEngine.php index b7aaa7c3..cba1ff54 100644 --- a/includes/engines/LuaSandbox/LuaSandboxEngine.php +++ b/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' ); diff --git a/includes/engines/LuaSandbox/LuaSandboxInterpreter.php b/includes/engines/LuaSandbox/LuaSandboxInterpreter.php index 0e221136..0502f5fa 100644 --- a/includes/engines/LuaSandbox/LuaSandboxInterpreter.php +++ b/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; diff --git a/includes/engines/LuaStandalone/LuaStandaloneEngine.php b/includes/engines/LuaStandalone/LuaStandaloneEngine.php index f03de50c..0c6ca3ab 100644 --- a/includes/engines/LuaStandalone/LuaStandaloneEngine.php +++ b/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 ) { diff --git a/includes/engines/LuaStandalone/LuaStandaloneInterpreter.php b/includes/engines/LuaStandalone/LuaStandaloneInterpreter.php index 71749e54..619345f6 100644 --- a/includes/engines/LuaStandalone/LuaStandaloneInterpreter.php +++ b/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" ); diff --git a/tests/phpunit/engines/LuaCommon/LuaDataProvider.php b/tests/phpunit/engines/LuaCommon/LuaDataProvider.php index 9306fd99..62aceb61 100644 --- a/tests/phpunit/engines/LuaCommon/LuaDataProvider.php +++ b/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; diff --git a/tests/phpunit/engines/LuaCommon/LuaEngineTestBase.php b/tests/phpunit/engines/LuaCommon/LuaEngineTestBase.php index 8dd28bd7..073ffe01 100644 --- a/tests/phpunit/engines/LuaCommon/LuaEngineTestBase.php +++ b/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', diff --git a/tests/phpunit/engines/LuaCommon/LuaEngineTestHelper.php b/tests/phpunit/engines/LuaCommon/LuaEngineTestHelper.php index f8dbf085..3575039a 100644 --- a/tests/phpunit/engines/LuaCommon/LuaEngineTestHelper.php +++ b/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 [ diff --git a/tests/phpunit/engines/LuaCommon/LuaEngineTestSkip.php b/tests/phpunit/engines/LuaCommon/LuaEngineTestSkip.php index da61d863..31acb66b 100644 --- a/tests/phpunit/engines/LuaCommon/LuaEngineTestSkip.php +++ b/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; diff --git a/tests/phpunit/engines/LuaCommon/LuaEngineUnitTestBase.php b/tests/phpunit/engines/LuaCommon/LuaEngineUnitTestBase.php index 7675eb56..bc6609f1 100644 --- a/tests/phpunit/engines/LuaCommon/LuaEngineUnitTestBase.php +++ b/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', diff --git a/tests/phpunit/engines/LuaCommon/UstringLibraryNormalizationTestProvider.php b/tests/phpunit/engines/LuaCommon/UstringLibraryNormalizationTestProvider.php index 094eb0f7..d456da44 100644 --- a/tests/phpunit/engines/LuaCommon/UstringLibraryNormalizationTestProvider.php +++ b/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