Improve some parameter docs

Change-Id: Ic85f74fc8dcefe86a3620e2d12f0b2ad2386ee23

.phpcs.xml

@@ -5,9 +5,6 @@
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationProtected" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingParamComment" />
-		<exclude name="MediaWiki.Commenting.FunctionComment.MissingParamTag" />
-		<exclude name="MediaWiki.Commenting.FunctionComment.MissingReturn" />
-		<exclude name="MediaWiki.Commenting.FunctionComment.WrongStyle" />
 		<exclude name="MediaWiki.Files.ClassMatchesFilename.NotMatch" />
 		<exclude name="MediaWiki.WhiteSpace.SpaceBeforeSingleLineComment.NewLineComment" />
 		<exclude name="Squiz.Scope.MethodScope.Missing" />
@@ -15,6 +12,4 @@
 	<file>.</file>
 	<arg name="extensions" value="php" />
 	<arg name="encoding" value="UTF-8" />
-	<exclude-pattern>node_modules/</exclude-pattern>
-	<exclude-pattern>vendor/</exclude-pattern>
 </ruleset>

engines/LuaCommon/LanguageLibrary.php

@@ -106,6 +106,10 @@ class Scribunto_LuaLanguageLibrary extends Scribunto_LuaLibraryBase {
 
 	/**
 	 * Language object method handler
+	 * @param string $name
+	 * @param array $args
+	 * @return array
+	 * @throws Scribunto_LuaError
 	 */
 	function languageMethod( $name, $args ) {
 		$name = strval( $name );
@@ -153,6 +157,9 @@ class Scribunto_LuaLanguageLibrary extends Scribunto_LuaLibraryBase {
 
 	/**
 	 * convertPlural handler
+	 * @param Language $lang
+	 * @param array $args
+	 * @return array
 	 */
 	function convertPlural( $lang, $args ) {
 		$number = array_shift( $args );
@@ -166,6 +173,9 @@ class Scribunto_LuaLanguageLibrary extends Scribunto_LuaLibraryBase {
 
 	/**
 	 * convertGrammar handler
+	 * @param Language $lang
+	 * @param array $args
+	 * @return array
 	 */
 	function convertGrammar( $lang, $args ) {
 		$this->checkType( 'convertGrammar', 1, $args[0], 'string' );
@@ -175,6 +185,9 @@ class Scribunto_LuaLanguageLibrary extends Scribunto_LuaLibraryBase {
 
 	/**
 	 * gender handler
+	 * @param Language $lang
+	 * @param array $args
+	 * @return array
 	 */
 	function gender( $lang, $args ) {
 		$this->checkType( 'gender', 1, $args[0], 'string' );
@@ -220,6 +233,9 @@ class Scribunto_LuaLanguageLibrary extends Scribunto_LuaLibraryBase {
 
 	/**
 	 * formatNum handler
+	 * @param Language $lang
+	 * @param array $args
+	 * @return array
 	 */
 	function formatNum( $lang, $args ) {
 		$num = $args[0];
@@ -236,6 +252,10 @@ class Scribunto_LuaLanguageLibrary extends Scribunto_LuaLibraryBase {
 
 	/**
 	 * formatDate handler
+	 * @param Language $lang
+	 * @param array $args
+	 * @return array
+	 * @throws Scribunto_LuaError
 	 */
 	function formatDate( $lang, $args ) {
 		$this->checkType( 'formatDate', 1, $args[0], 'string' );
@@ -308,6 +328,9 @@ class Scribunto_LuaLanguageLibrary extends Scribunto_LuaLibraryBase {
 
 	/**
 	 * formatDuration handler
+	 * @param Language $lang
+	 * @param array $args
+	 * @return array
 	 */
 	function formatDuration( $lang, $args ) {
 		$this->checkType( 'formatDuration', 1, $args[0], 'number' );
@@ -323,6 +346,9 @@ class Scribunto_LuaLanguageLibrary extends Scribunto_LuaLibraryBase {
 
 	/**
 	 * getDurationIntervals handler
+	 * @param Language $lang
+	 * @param array $args
+	 * @return array
 	 */
 	function getDurationIntervals( $lang, $args ) {
 		$this->checkType( 'getDurationIntervals', 1, $args[0], 'number' );

engines/LuaCommon/LuaCommon.php

@@ -253,6 +253,11 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 
 	/**
 	 * Execute a module chunk in a new isolated environment, and return the specified function
+	 * @param mixed $chunk As accepted by Scribunto_LuaInterpreter::callFunction()
+	 * @param string $functionName
+	 * @param PPFrame|null $frame
+	 * @return mixed
+	 * @throws ScribuntoException
 	 */
 	public function executeModule( $chunk, $functionName, $frame ) {
 		$resetFrames = null;
@@ -278,6 +283,9 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 
 	/**
 	 * Execute a module function chunk
+	 * @param mixed $chunk As accepted by Scribunto_LuaInterpreter::callFunction()
+	 * @param PPFrame|null $frame
+	 * @return array
 	 */
 	public function executeFunctionChunk( $chunk, $frame ) {
 		// $resetFrames is a ScopedCallback, so it has a purpose even though it appears unused.
@@ -599,6 +607,10 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 	/**
 	 * Handler for newChildFrame()
 	 *
+	 * @param string $frameId
+	 * @param string $title
+	 * @param array $args
+	 * @return array
 	 * @throws Scribunto_LuaError
 	 */
 	function newChildFrame( $frameId, $title, array $args ) {
@@ -636,6 +648,7 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 
 	/**
 	 * Handler for setTTL()
+	 * @param int $ttl
 	 */
 	function setTTL( $ttl ) {
 		$args = func_get_args();
@@ -647,6 +660,9 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 
 	/**
 	 * Handler for getExpandedArgument()
+	 * @param string $frameId
+	 * @param string $name
+	 * @return array
 	 */
 	function getExpandedArgument( $frameId, $name ) {
 		$args = func_get_args();
@@ -664,6 +680,8 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 
 	/**
 	 * Handler for getAllExpandedArguments()
+	 * @param string $frameId
+	 * @return array
 	 */
 	function getAllExpandedArguments( $frameId ) {
 		$frame = $this->getFrameById( $frameId );
@@ -673,6 +691,11 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 
 	/**
 	 * Handler for expandTemplate()
+	 * @param string $frameId
+	 * @param string $titleText
+	 * @param array $args
+	 * @return array
+	 * @throws Scribunto_LuaError
 	 */
 	function expandTemplate( $frameId, $titleText, $args ) {
 		$frame = $this->getFrameById( $frameId );
@@ -794,6 +817,10 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 
 	/**
 	 * Handler for preprocess()
+	 * @param string $frameId
+	 * @param string $text
+	 * @return array
+	 * @throws Scribunto_LuaError
 	 */
 	function preprocess( $frameId, $text ) {
 		$args = func_get_args();
@@ -880,7 +907,7 @@ abstract class Scribunto_LuaEngine extends ScribuntoEngineBase {
 // @codingStandardsIgnoreLine Squiz.Classes.ValidClassName.NotCamelCaps
 class Scribunto_LuaModule extends ScribuntoModuleBase {
 	/**
-	 * @var string
+	 * @var mixed
 	 */
 	protected $initChunk;
 
@@ -904,6 +931,7 @@ class Scribunto_LuaModule extends ScribuntoModuleBase {
 
 	/**
 	 * Get the chunk which, when called, will return the export table.
+	 * @return mixed
 	 */
 	public function getInitChunk() {
 		if ( !$this->initChunk ) {

engines/LuaCommon/TitleLibrary.php

@@ -208,8 +208,14 @@ class Scribunto_LuaTitleLibrary extends Scribunto_LuaLibraryBase {
 		return [ $this->getInexpensiveTitleData( $title ) ];
 	}
 
-	// May call the following Title methods:
-	// getFullUrl, getLocalUrl, getCanonicalUrl
+	/**
+	 * Get a URL referring to this title
+	 * @param string $text Title text.
+	 * @param string $which 'fullUrl', 'localUrl', or 'canonicalUrl'
+	 * @param string|array|null $query Query string or query string data.
+	 * @param string|null $proto 'http', 'https', 'relative', or 'canonical'
+	 * @return array
+	 */
 	function getUrl( $text, $which, $query = null, $proto = null ) {
 		static $protoMap = [
 			'http' => PROTO_HTTP,
@@ -223,6 +229,9 @@ class Scribunto_LuaTitleLibrary extends Scribunto_LuaLibraryBase {
 		if ( !in_array( $which, [ 'fullUrl', 'localUrl', 'canonicalUrl' ], true ) ) {
 			$this->checkType( 'getUrl', 2, $which, "'fullUrl', 'localUrl', or 'canonicalUrl'" );
 		}
+
+		// May call the following Title methods:
+		// getFullUrl, getLocalUrl, getCanonicalUrl
 		$func = "get" . ucfirst( $which );
 
 		$args = [ $query, false ];

tests/phpunit/engines/LuaCommon/LuaEngineTestBase.php

@@ -239,7 +239,12 @@ abstract class Scribunto_LuaEngineTestBase extends MediaWikiLangTestCase {
 		return $this->luaDataProvider;
 	}
 
-	/** @dataProvider provideLuaData */
+	/**
+	 * @dataProvider provideLuaData
+	 * @param string $key
+	 * @param string $testName
+	 * @param mixed $expected
+	 */
 	public function testLua( $key, $testName, $expected ) {
 		$this->luaTestName = static::$moduleName."[$key]: $testName";
 		if ( isset( $this->skipTests[$testName] ) ) {