From 083a0e57cb401477d81a4eac7a3525c1637c8f44 Mon Sep 17 00:00:00 2001 From: Umherirrender Date: Thu, 12 Nov 2020 22:37:48 +0100 Subject: [PATCH] Improve docs in api related classes Change-Id: I78338d48530f098fa5d36fe84cfd45c0d160f444 --- includes/api/ApiBase.php | 10 +++++----- includes/api/ApiErrorFormatter.php | 2 +- includes/api/ApiFormatFeedWrapper.php | 4 ++-- includes/api/ApiModuleManager.php | 2 +- includes/api/ApiOptions.php | 2 +- includes/api/ApiQueryBase.php | 2 +- includes/api/ApiQueryImageInfo.php | 4 ++-- includes/api/ApiQueryRecentChanges.php | 2 +- includes/api/ApiQueryRevisions.php | 2 +- includes/api/ApiQueryRevisionsBase.php | 2 +- includes/api/ApiResult.php | 12 ++++++------ includes/api/Hook/ApiQueryBaseAfterQueryHook.php | 2 +- 12 files changed, 23 insertions(+), 23 deletions(-) diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php index 292312cff17..e3ad6cb7f16 100644 --- a/includes/api/ApiBase.php +++ b/includes/api/ApiBase.php @@ -182,7 +182,7 @@ abstract class ApiBase extends ContextSource { /** @var stdClass[][] Cache for self::filterIDs() */ private static $filterIDsCache = []; - /** $var array Map of web UI block messages to corresponding API messages and codes */ + /** @var array Map of web UI block messages to corresponding API messages and codes */ private static $blockMsgMap = [ 'blockedtext' => [ 'apierror-blocked', 'blocked' ], 'blockedtext-partial' => [ 'apierror-blocked-partial', 'blocked' ], @@ -200,7 +200,7 @@ abstract class ApiBase extends ContextSource { * @var array */ private $mParamCache = []; - /** @var array|null|bool */ + /** @var array|null|false */ private $mModuleSource = false; /** @@ -961,7 +961,7 @@ abstract class ApiBase extends ContextSource { /** * Callback function used in requireOnlyOneParameter to check whether required parameters are set * - * @param object $x Parameter to check is not null/false + * @param mixed $x Parameter to check is not null/false * @return bool */ private function parameterNotEmpty( $x ) { @@ -973,7 +973,7 @@ abstract class ApiBase extends ContextSource { * Can die, if no param is set or if the title or page id is not valid. * * @param array $params User provided set of parameters, as from $this->extractRequestParams() - * @param bool|string $load Whether load the object's state from the database: + * @param string|false $load Whether load the object's state from the database: * - false: don't load (if the pageid is given, it will still be loaded) * - 'fromdb': load from a replica DB * - 'fromdbmaster': load from the master database @@ -1694,7 +1694,7 @@ abstract class ApiBase extends ContextSource { * tweak it as needed. * * @param int $flags Zero or more flags like GET_VALUES_FOR_HELP - * @return array|bool False on no parameters + * @return array * @since 1.21 $flags param added */ public function getFinalParams( $flags = 0 ) { diff --git a/includes/api/ApiErrorFormatter.php b/includes/api/ApiErrorFormatter.php index ded7c168d41..2e935c4c291 100644 --- a/includes/api/ApiErrorFormatter.php +++ b/includes/api/ApiErrorFormatter.php @@ -269,7 +269,7 @@ class ApiErrorFormatter { return []; } - $result = new ApiResult( 1e6 ); + $result = new ApiResult( 1000000 ); $formatter = new ApiErrorFormatter( $result, $this->lang, $format ?: $this->format, $this->useDB ); diff --git a/includes/api/ApiFormatFeedWrapper.php b/includes/api/ApiFormatFeedWrapper.php index 40cc738fffa..00e997dcc5e 100644 --- a/includes/api/ApiFormatFeedWrapper.php +++ b/includes/api/ApiFormatFeedWrapper.php @@ -33,8 +33,8 @@ class ApiFormatFeedWrapper extends ApiFormatBase { /** * Call this method to initialize output data. See execute() * @param ApiResult $result - * @param object $feed An instance of one of the $wgFeedClasses classes - * @param array $feedItems Array of FeedItem objects + * @param FeedItem $feed An instance of one of the $wgFeedClasses classes + * @param FeedItem[] $feedItems */ public static function setResult( $result, $feed, $feedItems ) { // Store output in the Result data. diff --git a/includes/api/ApiModuleManager.php b/includes/api/ApiModuleManager.php index 473fd57a582..7f4bb8b041d 100644 --- a/includes/api/ApiModuleManager.php +++ b/includes/api/ApiModuleManager.php @@ -224,7 +224,7 @@ class ApiModuleManager extends ContextSource { * Returns the class name of the given module * * @param string $module Module name - * @return string|bool class name or false if the module does not exist + * @return string|false class name or false if the module does not exist * @since 1.24 */ public function getClassName( $module ) { diff --git a/includes/api/ApiOptions.php b/includes/api/ApiOptions.php index 56051c2ce16..900945159a5 100644 --- a/includes/api/ApiOptions.php +++ b/includes/api/ApiOptions.php @@ -158,7 +158,7 @@ class ApiOptions extends ApiBase { /** * Load the user from the master to reduce CAS errors on double post (T95839) * - * @return null|User + * @return User|null */ protected function getUserForUpdates() { if ( !$this->userForUpdates ) { diff --git a/includes/api/ApiQueryBase.php b/includes/api/ApiQueryBase.php index 14a06c6d0ed..17e84303679 100644 --- a/includes/api/ApiQueryBase.php +++ b/includes/api/ApiQueryBase.php @@ -444,7 +444,7 @@ abstract class ApiQueryBase extends ApiBase { * here in the same way it treats a false return from addValue(). * * @since 1.28 - * @param object $row Database row + * @param stdClass $row Database row * @param array &$data Data to be added to the result * @param array &$hookData Hook data from ApiQueryBase::select() * @return bool Return false if row processing should end with continuation diff --git a/includes/api/ApiQueryImageInfo.php b/includes/api/ApiQueryImageInfo.php index 6a84e095d43..4b47fa5577b 100644 --- a/includes/api/ApiQueryImageInfo.php +++ b/includes/api/ApiQueryImageInfo.php @@ -364,7 +364,7 @@ class ApiQueryImageInfo extends ApiQueryBase { * @param array $prop Array of properties to get (in the keys) * @param ApiResult $result * @param array|null $thumbParams Containing 'width' and 'height' items, or null - * @param array|bool|string $opts Options for data fetching. + * @param array|false|string $opts Options for data fetching. * This is an array consisting of the keys: * 'version': The metadata version for the metadata option * 'language': The language for extmetadata property @@ -658,7 +658,7 @@ class ApiQueryImageInfo extends ApiQueryBase { /** * @param File $img - * @param null|string $start + * @param string|null $start * @return string */ protected function getContinueStr( $img, $start = null ) { diff --git a/includes/api/ApiQueryRecentChanges.php b/includes/api/ApiQueryRecentChanges.php index 4397f86616a..b5c5db5a977 100644 --- a/includes/api/ApiQueryRecentChanges.php +++ b/includes/api/ApiQueryRecentChanges.php @@ -81,7 +81,7 @@ class ApiQueryRecentChanges extends ApiQueryGeneratorBase { * @internal * @param User $user * @param RecentChange|null $rc - * @return bool|string + * @return string|false */ public static function getPatrolToken( User $user, $rc = null ) { $validTokenUser = false; diff --git a/includes/api/ApiQueryRevisions.php b/includes/api/ApiQueryRevisions.php index f640b545d90..9b83f8f63cf 100644 --- a/includes/api/ApiQueryRevisions.php +++ b/includes/api/ApiQueryRevisions.php @@ -74,7 +74,7 @@ class ApiQueryRevisions extends ApiQueryRevisionsBase { * @deprecated since 1.24 * @internal * @param User $user - * @return bool|string + * @return string|false */ public static function getRollbackToken( User $user ) { if ( !MediaWikiServices::getInstance()->getPermissionManager() diff --git a/includes/api/ApiQueryRevisionsBase.php b/includes/api/ApiQueryRevisionsBase.php index a7342b4acea..c3b13359c0a 100644 --- a/includes/api/ApiQueryRevisionsBase.php +++ b/includes/api/ApiQueryRevisionsBase.php @@ -232,7 +232,7 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase { * * @since 1.32, takes a RevisionRecord instead of a Revision * @param RevisionRecord $revision - * @param object $row Should have a field 'ts_tags' if $this->fld_tags is set + * @param stdClass $row Should have a field 'ts_tags' if $this->fld_tags is set * @return array */ protected function extractRevisionInfo( RevisionRecord $revision, $row ) { diff --git a/includes/api/ApiResult.php b/includes/api/ApiResult.php index 97c1e63d055..8c1fdad19fa 100644 --- a/includes/api/ApiResult.php +++ b/includes/api/ApiResult.php @@ -146,7 +146,7 @@ class ApiResult implements ApiSerializable { private $errorFormatter; /** - * @param int|bool $maxSize Maximum result "size", or false for no limit + * @param int|false $maxSize Maximum result "size", or false for no limit */ public function __construct( $maxSize ) { $this->maxSize = $maxSize; @@ -788,7 +788,7 @@ class ApiResult implements ApiSerializable { * @since 1.25 * @param array $dataIn * @param array $transforms - * @return array|object + * @return array|stdClass */ protected static function applyTransformations( array $dataIn, array $transforms ) { $strip = $transforms['Strip'] ?? 'none'; @@ -1003,8 +1003,8 @@ class ApiResult implements ApiSerializable { * ones. * * @since 1.25 - * @param array|object $data - * @return array|object + * @param array|stdClass $data + * @return array|stdClass */ public static function stripMetadata( $data ) { if ( is_array( $data ) || is_object( $data ) ) { @@ -1036,9 +1036,9 @@ class ApiResult implements ApiSerializable { * ones. * * @since 1.25 - * @param array|object $data + * @param array|stdClass $data * @param array|null &$metadata Store metadata here, if provided - * @return array|object + * @return array|stdClass */ public static function stripMetadataNonRecursive( $data, &$metadata = null ) { if ( !is_array( $metadata ) ) { diff --git a/includes/api/Hook/ApiQueryBaseAfterQueryHook.php b/includes/api/Hook/ApiQueryBaseAfterQueryHook.php index 375013d4624..018c98bfc2c 100644 --- a/includes/api/Hook/ApiQueryBaseAfterQueryHook.php +++ b/includes/api/Hook/ApiQueryBaseAfterQueryHook.php @@ -22,7 +22,7 @@ interface ApiQueryBaseAfterQueryHook { * @since 1.35 * * @param ApiQueryBase $module Module in question - * @param IResultWrapper|bool $result ResultWrapper or bool returned from the IDatabase::select() + * @param IResultWrapper $result ResultWrapper * @param array &$hookData Array that was passed to the ApiQueryBaseBeforeQuery hook and * will be passed to the ApiQueryBaseProcessRow hook, intended for inter-hook * communication