From 5477568274e37d9ebfbcf0962d8bae9a1a92c37c Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Thu, 16 May 2024 10:45:15 +0200 Subject: [PATCH 01/16] Correct call to non-existing Filesystem::removePath() in ArcanistDownloadWorkflow.php Summary: rARC21e80a635d798c5be2c6e5c272497b3170c1e079 introduced a call to non-existing `Filesystem::removePath()`. Presumably, `remove()` in `src/filesystem/Filesystem.php` was meant, so use that function instead. Test Plan: Unknown, apart from reading and grep'ing the code base. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25640 --- src/workflow/ArcanistDownloadWorkflow.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/workflow/ArcanistDownloadWorkflow.php b/src/workflow/ArcanistDownloadWorkflow.php index 3b1264b2..58e566de 100644 --- a/src/workflow/ArcanistDownloadWorkflow.php +++ b/src/workflow/ArcanistDownloadWorkflow.php @@ -156,7 +156,7 @@ EOTEXT try { list($data) = $future->resolvex(); } catch (Exception $ex) { - Filesystem::removePath($path); + Filesystem::remove($path); throw $ex; } From 3cb117684f4e684650d01ffb15170f98afe330ef Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Fri, 17 May 2024 11:47:38 +0200 Subject: [PATCH 02/16] Fix calls to non-existing getDescription() in ArcanistWorkingCopyPath Summary: `ArcanistWorkingCopyPath::getDescription()` is undefined. Given its use in the exception message, the path is supposed to be used, so call `ArcanistWorkingCopyPath::getPath()` instead. Test Plan: Carefully read the code and check for existing methods in the class. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25657 --- src/workingcopy/ArcanistWorkingCopyPath.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/workingcopy/ArcanistWorkingCopyPath.php b/src/workingcopy/ArcanistWorkingCopyPath.php index 5fcd1498..217d5932 100644 --- a/src/workingcopy/ArcanistWorkingCopyPath.php +++ b/src/workingcopy/ArcanistWorkingCopyPath.php @@ -30,7 +30,7 @@ final class ArcanistWorkingCopyPath throw new Exception( pht( 'No data provided for path "%s".', - $this->getDescription())); + $this->getPath())); } return $this->data; @@ -55,7 +55,7 @@ final class ArcanistWorkingCopyPath throw new Exception( pht( 'No mode provided for path "%s".', - $this->getDescription())); + $this->getPath())); } return $this->mode; From 6250296648fa64bc8124caa6f9407ce4b4c56dd4 Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Thu, 16 May 2024 10:53:33 +0200 Subject: [PATCH 03/16] Correct call to non-existing PhutilFileLockException in support/unit/lock.php Summary: `PhutilFileLockException` does not exist. Per https://we.phorge.it/source/arcanist/browse/master/src/filesystem/PhutilFileLock.php$54-66 , if lock acquisition fails it is supposed to throw a `PhutilLockException` instead. Test Plan: Grep the code base. Or, run this, from arcanist, from two different terminals: php ./support/unit/lock.php asd.txt After this change, the exception is correctly managed. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25641 --- support/unit/lock.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/support/unit/lock.php b/support/unit/lock.php index b4e13a60..1670cd12 100755 --- a/support/unit/lock.php +++ b/support/unit/lock.php @@ -51,7 +51,7 @@ $lock = PhutilFileLock::newForPath($file); try { $lock->lock($args->getArg('wait')); -} catch (PhutilFileLockException $ex) { +} catch (PhutilLockException $ex) { $console->writeOut( "**%s** %s\n", pht('UNABLE TO ACQUIRE LOCK:'), From f7fcf31c7e23475e345cb3cd4abf0474ba6fd9cf Mon Sep 17 00:00:00 2001 From: Pppery Date: Fri, 7 Jun 2024 12:52:04 -0400 Subject: [PATCH 04/16] Remove PhutilPhtTestCase::getDateTranslations() Summary: See my comment at T15815#17864. I don't think the translation extractor has any consumers other than the downstream translations extension, and I'd prefer to handle this issue there rather than upstream. Test Plan: Read the code. Reviewers: O1 Blessed Committers, aklapper Reviewed By: O1 Blessed Committers, aklapper Subscribers: aklapper, tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25684 --- .../__tests__/PhutilPhtTestCase.php | 69 ------------------- 1 file changed, 69 deletions(-) diff --git a/src/internationalization/__tests__/PhutilPhtTestCase.php b/src/internationalization/__tests__/PhutilPhtTestCase.php index fed12b1d..e10ed35a 100644 --- a/src/internationalization/__tests__/PhutilPhtTestCase.php +++ b/src/internationalization/__tests__/PhutilPhtTestCase.php @@ -29,73 +29,4 @@ final class PhutilPhtTestCase extends PhutilTestCase { $this->assertEqual('5 piv', pht('%d beer(s)', 5)); } - - public function getDateTranslations() { - // The only purpose of this function is to provide a static list of - // translations which can come from PhutilTranslator::translateDate() to - // allow translation extractor getting them. - return array( - 'D' => array( - pht('Sun'), - pht('Mon'), - pht('Tue'), - pht('Wed'), - pht('Thu'), - pht('Fri'), - pht('Sat'), - ), - 'l' => array( - pht('Sunday'), - pht('Monday'), - pht('Tuesday'), - pht('Wednesday'), - pht('Thursday'), - pht('Friday'), - pht('Saturday'), - ), - 'S' => array( - pht('st'), - pht('nd'), - pht('rd'), - pht('th'), - ), - 'F' => array( - pht('January'), - pht('February'), - pht('March'), - pht('April'), - pht('May'), - pht('June'), - pht('July'), - pht('August'), - pht('September'), - pht('October'), - pht('November'), - pht('December'), - ), - 'M' => array( - pht('Jan'), - pht('Feb'), - pht('Mar'), - pht('Apr'), - pht('May'), - pht('Jun'), - pht('Jul'), - pht('Aug'), - pht('Sep'), - pht('Oct'), - pht('Nov'), - pht('Dec'), - ), - 'a' => array( - pht('am'), - pht('pm'), - ), - 'A' => array( - pht('AM'), - pht('PM'), - ), - ); - } - } From 0af89f7d323b0b3beb91ed9a3a18be1e5e3b9321 Mon Sep 17 00:00:00 2001 From: Pppery Date: Wed, 19 Jun 2024 15:54:09 -0400 Subject: [PATCH 05/16] Add fallback languages for locale files Summary: Upstream version of https://gerrit.wikimedia.org/r/c/phabricator/translations/+/1047593 Test Plan: Set any languages and observe untranslated strings display proper PLURAL rules With the downstream "translations" extension installed, set the language to traditional Chinese and see Simplified Chinese rather than English translations if they exist, like "Foo added/removed a project" Reviewers: O1 Blessed Committers, avivey Reviewed By: O1 Blessed Committers, avivey Subscribers: avivey, tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25695 --- src/internationalization/PhutilLocale.php | 5 ++++- .../locales/PhutilPortugueseBrazilLocale.php | 9 +++++++++ .../locales/PhutilPortuguesePortugalLocale.php | 10 ++++++++++ .../locales/PhutilSimplifiedChineseLocale.php | 9 +++++++++ .../locales/PhutilTraditionalChineseLocale.php | 4 ++++ .../locales/PhutilUSEnglishLocale.php | 6 ++++++ 6 files changed, 42 insertions(+), 1 deletion(-) diff --git a/src/internationalization/PhutilLocale.php b/src/internationalization/PhutilLocale.php index 3ef2524e..5ed03a92 100644 --- a/src/internationalization/PhutilLocale.php +++ b/src/internationalization/PhutilLocale.php @@ -30,11 +30,14 @@ abstract class PhutilLocale extends Phobject { * For locales like "English (Great Britain)", missing translations can be * sourced from "English (US)". * + * Languages with no other fallback use en_US because that's better + * than proto-English for untranslated strings. + * * @return string|null Locale code of fallback locale, or null if there is * no fallback locale. */ public function getFallbackLocaleCode() { - return null; + return 'en_US'; } diff --git a/src/internationalization/locales/PhutilPortugueseBrazilLocale.php b/src/internationalization/locales/PhutilPortugueseBrazilLocale.php index 2c1ffbea..259ed541 100644 --- a/src/internationalization/locales/PhutilPortugueseBrazilLocale.php +++ b/src/internationalization/locales/PhutilPortugueseBrazilLocale.php @@ -13,4 +13,13 @@ final class PhutilPortugueseBrazilLocale extends PhutilLocale { return pht('Portuguese (Brazil)'); } + public function getFallbackLocaleCode() { + // Phabricator does not support bidirectional + // fallbacks (pt_BR -> pt and pt -> pt_BR simultaneously) + // since Translatewiki calls pt_PT "Portugese" without a country + // it makes slightly more sense to fall back in this direction + // than the other one + return 'pt_PT'; + } + } diff --git a/src/internationalization/locales/PhutilPortuguesePortugalLocale.php b/src/internationalization/locales/PhutilPortuguesePortugalLocale.php index f893b77f..f5a9eb71 100644 --- a/src/internationalization/locales/PhutilPortuguesePortugalLocale.php +++ b/src/internationalization/locales/PhutilPortuguesePortugalLocale.php @@ -13,4 +13,14 @@ final class PhutilPortuguesePortugalLocale extends PhutilLocale { return pht('Portuguese (Portugal)'); } + public function getFallbackLocaleCode() { + // Ideally this would be pt_BR but Phabricator does not support + // bidirectional fallbacks (pt_BR -> pt and pt -> pt_BR simultaneously) + // since Translatewiki calls pt_PT "Portugese" without a country + // it makes slightly more sense to fall back in the other direction + // In the mean time return `en_US` so users don't see Proto-English + // unncecessarily + return 'en_US'; + } + } diff --git a/src/internationalization/locales/PhutilSimplifiedChineseLocale.php b/src/internationalization/locales/PhutilSimplifiedChineseLocale.php index 6b0c709b..4f763323 100644 --- a/src/internationalization/locales/PhutilSimplifiedChineseLocale.php +++ b/src/internationalization/locales/PhutilSimplifiedChineseLocale.php @@ -13,4 +13,13 @@ final class PhutilSimplifiedChineseLocale extends PhutilLocale { return pht('Chinese (Simplified)'); } + public function getFallbackLocaleCode() { + // Ideally this would be zh_Hant but Phabricator does not support + // bidirectional fallbacks + // (zh_Hant -> zh_Hans and zh_Hans -> zh_Hant simultaneously) + // arbitrarily choose to fall back in the other direction instead + // In the mean time return `en_US` so users don't see Proto-English + return 'en_US'; + } + } diff --git a/src/internationalization/locales/PhutilTraditionalChineseLocale.php b/src/internationalization/locales/PhutilTraditionalChineseLocale.php index f8879506..19ca3edb 100644 --- a/src/internationalization/locales/PhutilTraditionalChineseLocale.php +++ b/src/internationalization/locales/PhutilTraditionalChineseLocale.php @@ -13,4 +13,8 @@ final class PhutilTraditionalChineseLocale extends PhutilLocale { return pht('Chinese (Traditional)'); } + public function getFallbackLocaleCode() { + return 'zh_Hans'; + } + } diff --git a/src/internationalization/locales/PhutilUSEnglishLocale.php b/src/internationalization/locales/PhutilUSEnglishLocale.php index ef1633ed..1bd7430c 100644 --- a/src/internationalization/locales/PhutilUSEnglishLocale.php +++ b/src/internationalization/locales/PhutilUSEnglishLocale.php @@ -13,4 +13,10 @@ final class PhutilUSEnglishLocale extends PhutilLocale { return pht('English (US)'); } + public function getFallbackLocaleCode() { + // The default fallback is en_US, explicitly return null here + // to avoid a fallback loop + return null; + } + } From 21fbc806e4e15e8ab2610f19bdb27fe4a572ed4d Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Thu, 16 May 2024 17:28:47 +0200 Subject: [PATCH 06/16] Fix call to non-existing ArcanistAliasEffect::EFFECT_CONFIGURATION in ArcanistAliasEngine Summary: `ArcanistAliasEffect::EFFECT_CONFIGURATION` does not exist. Probably `ArcanistAliasEffect::EFFECT_MISCONFIGURATION` was meant, given the message it sets. Test Plan: Carefully read the code. Reviewers: O1 Blessed Committers, avivey Reviewed By: O1 Blessed Committers, avivey Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25652 --- src/toolset/ArcanistAliasEngine.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/toolset/ArcanistAliasEngine.php b/src/toolset/ArcanistAliasEngine.php index baa4ab56..250842c8 100644 --- a/src/toolset/ArcanistAliasEngine.php +++ b/src/toolset/ArcanistAliasEngine.php @@ -67,7 +67,8 @@ final class ArcanistAliasEngine // This alias is not defined properly, so we're going to ignore it. unset($aliases[$key]); - $results[] = $this->newEffect(ArcanistAliasEffect::EFFECT_CONFIGURATION) + $results[] = + $this->newEffect(ArcanistAliasEffect::EFFECT_MISCONFIGURATION) ->setMessage( pht( 'Configuration source ("%s") defines an invalid alias, which '. From 331b255b15088eb18d91a42f3b0c79fdb569a7bb Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Tue, 2 Jul 2024 20:53:23 +0200 Subject: [PATCH 07/16] Declare missing class properties Summary: Code in these classes tries to access undefined properties. Thus define these properties. Test Plan: Run PHPStan static code analysis; grep the code in each class. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25712 --- src/future/postmark/PhutilPostmarkFuture.php | 1 + src/workingcopy/ArcanistWorkingCopyPath.php | 1 + 2 files changed, 2 insertions(+) diff --git a/src/future/postmark/PhutilPostmarkFuture.php b/src/future/postmark/PhutilPostmarkFuture.php index 23c21f47..fcf6e9d7 100644 --- a/src/future/postmark/PhutilPostmarkFuture.php +++ b/src/future/postmark/PhutilPostmarkFuture.php @@ -3,6 +3,7 @@ final class PhutilPostmarkFuture extends FutureProxy { private $future; + private $clientID; private $accessToken; private $method; private $parameters; diff --git a/src/workingcopy/ArcanistWorkingCopyPath.php b/src/workingcopy/ArcanistWorkingCopyPath.php index 217d5932..80b03bce 100644 --- a/src/workingcopy/ArcanistWorkingCopyPath.php +++ b/src/workingcopy/ArcanistWorkingCopyPath.php @@ -7,6 +7,7 @@ final class ArcanistWorkingCopyPath private $mode; private $data; private $binary; + private $mimeType; private $dataAsLines; private $charMap; private $lineMap; From 72e59da8047c8e0d048aff3bdbddbfb7e11e4e99 Mon Sep 17 00:00:00 2001 From: Valerio Bozzolan Date: Mon, 8 Jul 2024 10:03:25 +0200 Subject: [PATCH 08/16] Fix arc diff in Subversion for non-English languages Summary: When using `arc diff`, this crash should not fire anymore on non-English shells: Undefined array key "Repository UUID" The error message comes to this line: https://we.phorge.it/source/arcanist/browse/master/src/repository/api/ArcanistSubversionAPI.php;f7fcf31c7e23475e345cb3cd4abf0474ba6fd9cf$606 Look at the parser of `svn info` that expects English language: https://we.phorge.it/source/arcanist/browse/master/src/repository/api/ArcanistSubversionAPI.php;f7fcf31c7e23475e345cb3cd4abf0474ba6fd9cf$326-375 The historical behavior of `ExecFuture` is to inherit environment variables. It may have sense, to have the user home, etc. So, the approach is to just clear the incompatible specific environment variable that alters the output language. Closes T15855 Test Plan: - clone a random a Subversion repository - have your operating system in a non-English language - (e.g. `export LANGUAGE=en_US:it_IT`) - run 'arc diff' No crash anymore. You are able to submit the patch, just like in git. Reviewers: O1 Blessed Committers, l2dy, avivey Reviewed By: O1 Blessed Committers, l2dy, avivey Subscribers: l2dy, aklapper, tobiaswiese, Matthew, Cigaryno Maniphest Tasks: T15855 Differential Revision: https://we.phorge.it/D25691 --- src/repository/api/ArcanistSubversionAPI.php | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/repository/api/ArcanistSubversionAPI.php b/src/repository/api/ArcanistSubversionAPI.php index cfd4ab30..6fc17bf5 100644 --- a/src/repository/api/ArcanistSubversionAPI.php +++ b/src/repository/api/ArcanistSubversionAPI.php @@ -40,6 +40,12 @@ final class ArcanistSubversionAPI extends ArcanistRepositoryAPI { $argv[0] = 'svn '.$argv[0]; $future = newv('ExecFuture', $argv); + + // For historical reasons we run Subversion commands keeping env. + // But, let's keep English, to have a reliable parser. + // https://we.phorge.it/T15872 + $future->updateEnv('LC_ALL', 'C'); + $future->setCWD($this->getPath()); return $future; } From 76d22d70e4292aadc96a419f88436e36bd39dd2d Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Wed, 3 Jul 2024 08:29:47 +0200 Subject: [PATCH 09/16] Correct PHPDoc of dropSymbolCache() Summary: `dropSymbolCache()` does not return anything, and its only call in `rebuild-map.php` does not expect a return value either. Thus replace `@return this` with `@return void`. Test Plan: Read/grep the code. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25720 --- src/moduleutils/PhutilLibraryMapBuilder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/moduleutils/PhutilLibraryMapBuilder.php b/src/moduleutils/PhutilLibraryMapBuilder.php index 5d359bbc..7997bf57 100644 --- a/src/moduleutils/PhutilLibraryMapBuilder.php +++ b/src/moduleutils/PhutilLibraryMapBuilder.php @@ -212,7 +212,7 @@ final class PhutilLibraryMapBuilder extends Phobject { /** * Drop the symbol cache, forcing a clean rebuild. * - * @return this + * @return void * * @task symbol */ From 84210cedc6ce4ceb6b8ffcfb47fdaaa6e6d83917 Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Tue, 2 Jul 2024 21:00:52 +0200 Subject: [PATCH 10/16] Declare missing class properties in ArcanistDownloadWorkflow Summary: rARCbd9769ba92df63d0429f74ec7fb8b00a4989f28b added and declared the three private properties `$id`, `$saveAs`, `$show`. However rARC21e80a635d798c5be2c6e5c272497b3170c1e079 removed their declarations while still initializing these properties in `didParseArguments()`. Test Plan: Run PHPStan static code analysis; grep the code in this class. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25713 --- src/workflow/ArcanistDownloadWorkflow.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/workflow/ArcanistDownloadWorkflow.php b/src/workflow/ArcanistDownloadWorkflow.php index 58e566de..acbd01de 100644 --- a/src/workflow/ArcanistDownloadWorkflow.php +++ b/src/workflow/ArcanistDownloadWorkflow.php @@ -3,6 +3,10 @@ final class ArcanistDownloadWorkflow extends ArcanistArcWorkflow { + private $id; + private $saveAs; + private $show; + public function getWorkflowName() { return 'download'; } From 06028fad3c6af49da975e0d33a16e5bddfdb1326 Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Sun, 28 Jul 2024 19:24:07 +0200 Subject: [PATCH 11/16] Add return statements for PhutilChannelChannel::readBytes()/writeBytes() Summary: PHPStan complains that `Method PhutilChannelChannel::readBytes() should return string but return statement is missing.` and `Method PhutilChannelChannel::writeBytes() should return int but return statement is missing.` All other subclasses of `PhutilChannel` implementing these two methods either provide a return value or directly throw an exception. `PhutilChannelChannel` throws an exception for both methods but hadn't explicitly declared that as a `return` statement. Test Plan: Run static code analysis; read/grep the code. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25754 --- src/channel/PhutilChannelChannel.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/channel/PhutilChannelChannel.php b/src/channel/PhutilChannelChannel.php index 1ab99e30..3b0cb437 100644 --- a/src/channel/PhutilChannelChannel.php +++ b/src/channel/PhutilChannelChannel.php @@ -53,10 +53,12 @@ abstract class PhutilChannelChannel extends PhutilChannel { protected function readBytes($length) { $this->throwOnRawByteOperations(); + return ''; // Never returned but makes static code analyzers happy } protected function writeBytes($bytes) { $this->throwOnRawByteOperations(); + return -1; // Never returned but makes static code analyzers happy } protected function getReadSockets() { From 475256713078cbc5bc15c217a28ba839f1ebc37c Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Sun, 11 Aug 2024 22:48:18 +0200 Subject: [PATCH 12/16] Fix $boot_length comparison in PhagePHPAgentBootloader Summary: `$boot_length = strlen($boot_sequence->toString())` returns an `int` and `strlen()` expects a `string` as a parameter. Thus calling `if (strlen($boot_length) > 8192)` afterwards to get the string length of an integer makes no sense. Test Plan: Read the code. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25770 --- src/phage/bootloader/PhagePHPAgentBootloader.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/phage/bootloader/PhagePHPAgentBootloader.php b/src/phage/bootloader/PhagePHPAgentBootloader.php index e4d522a4..18669b0a 100644 --- a/src/phage/bootloader/PhagePHPAgentBootloader.php +++ b/src/phage/bootloader/PhagePHPAgentBootloader.php @@ -89,7 +89,7 @@ final class PhagePHPAgentBootloader extends PhageAgentBootloader { $boot_length = strlen($boot_sequence->toString()); $boot_sequence->addText($main_sequence->toString()); - if (strlen($boot_length) > 8192) { + if ($boot_length > 8192) { throw new Exception(pht('Stage 1 bootloader is too large!')); } From 0d5f4379709d165045adce7acfd10f611fa396f7 Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Sun, 18 Aug 2024 00:15:13 +0200 Subject: [PATCH 13/16] Fix return value of PhutilTestCase::tryTestCaseMap() Summary: `PhutilTestCase::tryTestCases()` returns void. Thus `PhutilTestCase::tryTestCaseMap()` should behave the same way as `PhutilTestCase::assertException()`: return void. Test Plan: Read the code; run static code analysis and don't get "Result of method PhutilTestCase::tryTestCases() (void) is used" anymore. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25791 --- src/unit/engine/phutil/PhutilTestCase.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/unit/engine/phutil/PhutilTestCase.php b/src/unit/engine/phutil/PhutilTestCase.php index e5f56164..81062ff2 100644 --- a/src/unit/engine/phutil/PhutilTestCase.php +++ b/src/unit/engine/phutil/PhutilTestCase.php @@ -445,7 +445,7 @@ abstract class PhutilTestCase extends Phobject { $callable, $exception_class = 'Exception') { - return $this->tryTestCases( + $this->tryTestCases( array_fuse(array_keys($map)), array_values($map), $callable, From 0c9c94748b5855ef4ef1b27423a014118b8d16c9 Mon Sep 17 00:00:00 2001 From: jkim Date: Thu, 27 Jun 2024 10:57:07 +0100 Subject: [PATCH 14/16] Fix PHP 8.1 "trim(null)" exception when creating a diff with an empty "Differential Revision:" field Summary: This revision fixes a `trim(null)` exception when creating a diff with an empty field. Fixes: T15868 Test Plan: 1. Create a commit with an empty "Differential Revision:" field 2. Run `arc diff` Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: avivey, tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25703 --- src/workflow/ArcanistDiffWorkflow.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/workflow/ArcanistDiffWorkflow.php b/src/workflow/ArcanistDiffWorkflow.php index f8a627d7..a7d11fde 100644 --- a/src/workflow/ArcanistDiffWorkflow.php +++ b/src/workflow/ArcanistDiffWorkflow.php @@ -1938,6 +1938,10 @@ EOTEXT continue; } + if ($value === null) { + continue; + } + if (is_array($value)) { // For array values, merge the arrays, appending the new values. // Examples are "Reviewers" and "Cc", where this produces a list of From 901f0607716679792800e39015c7cc63cbb0d43c Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Thu, 22 Aug 2024 11:58:48 +0200 Subject: [PATCH 15/16] Drop question mark suffix from optional PHPDoc @param types Summary: The question mark in `@param type? $foo Desc` is a custom notation not consistently applied across the codebase and not necessarily obvious to the reader (because custom and not mentioned in https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md ). Instead, explicitly state "optional" in the parameter description for clarity. Closes T15925. Test Plan: Run PHPStan, see no `PHPDoc @param has invalid value (type? [...]` style output anymore. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Maniphest Tasks: T15925 Differential Revision: https://we.phorge.it/D25798 --- src/channel/PhutilSocketChannel.php | 2 +- src/filesystem/TempFile.php | 12 +++++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/src/channel/PhutilSocketChannel.php b/src/channel/PhutilSocketChannel.php index 4bd2a47a..e8cf9cf1 100644 --- a/src/channel/PhutilSocketChannel.php +++ b/src/channel/PhutilSocketChannel.php @@ -35,7 +35,7 @@ final class PhutilSocketChannel extends PhutilChannel { * * @param socket Socket (stream socket, not plain socket). If only one * socket is provided, it is used for reading and writing. - * @param socket? Optional write socket. + * @param socket (optional) Write socket. * * @task construct */ diff --git a/src/filesystem/TempFile.php b/src/filesystem/TempFile.php index 895b7a2b..f905903c 100644 --- a/src/filesystem/TempFile.php +++ b/src/filesystem/TempFile.php @@ -27,11 +27,13 @@ final class TempFile extends Phobject { /** * Create a new temporary file. * - * @param string? Filename hint. This is useful if you intend to edit the - * file with an interactive editor, so the user's editor shows - * "commit-message" instead of "p3810hf-1z9b89bas". - * @param string? Root directory to hold the file. If omitted, the system - * temporary directory (often "/tmp") will be used by default. + * @param string (optional) Filename hint. This is useful if you intend to + * edit the file with an interactive editor, so the user's + * editor shows "commit-message" instead of + * "p3810hf-1z9b89bas". + * @param string (optional) Root directory to hold the file. If omitted, the + * system temporary directory (often "/tmp") will be used by + * default. * @task create */ public function __construct($filename = null, $root_directory = null) { From 04e3e250f7da6a55c908d373a0df9949eeea6d7b Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Fri, 23 Aug 2024 12:55:36 +0200 Subject: [PATCH 16/16] Add missing variable names to PHPDoc @param of methods Summary: Add variable names (`$varname` in `@param type $varname explanation`) to PHPDoc method headers, for fun and profit. Closes T15923 Test Plan: * Read the method signatures and their corresponding PHPDoc headers at your fireplace * Still run `./bin/diviner generate` without explosions (though it is very lenient anyway?) Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Maniphest Tasks: T15923 Differential Revision: https://we.phorge.it/D25799 --- src/channel/PhutilChannel.php | 20 +- src/channel/PhutilExecChannel.php | 4 +- src/channel/PhutilProtocolChannel.php | 8 +- src/channel/PhutilSocketChannel.php | 7 +- src/conduit/ConduitClient.php | 2 +- .../ArcanistConfigurationManager.php | 10 +- src/console/PhutilConsole.php | 2 +- src/console/PhutilInteractiveEditor.php | 14 +- src/console/format.php | 6 +- src/console/view/PhutilConsoleTable.php | 4 +- src/console/view/PhutilConsoleView.php | 4 +- .../ArcanistDifferentialCommitMessage.php | 2 +- src/error/PhutilErrorHandler.php | 32 +-- src/error/phlog.php | 22 +- src/filesystem/FileFinder.php | 4 +- src/filesystem/FileList.php | 11 +- src/filesystem/Filesystem.php | 130 +++++------ src/filesystem/FilesystemException.php | 4 +- src/filesystem/PhutilDeferredLog.php | 17 +- src/filesystem/PhutilFileLock.php | 4 +- src/filesystem/PhutilLock.php | 12 +- src/filesystem/TempFile.php | 14 +- .../linesofalarge/LinesOfALarge.php | 2 +- .../linesofalarge/LinesOfALargeExecFuture.php | 2 +- .../linesofalarge/LinesOfALargeFile.php | 2 +- src/future/FutureIterator.php | 16 +- src/future/exec/ExecFuture.php | 33 +-- src/future/exec/PhutilExecutableFuture.php | 11 +- src/future/exec/execx.php | 8 +- src/future/http/BaseHTTPFuture.php | 38 ++-- src/future/http/HTTPSFuture.php | 32 +-- src/hgdaemon/ArcanistHgClientChannel.php | 4 +- src/hgdaemon/ArcanistHgProxyClient.php | 7 +- src/hgdaemon/ArcanistHgProxyServer.php | 16 +- src/hgdaemon/ArcanistHgServerChannel.php | 4 +- .../lib/PhutilLibraryConflictException.php | 8 +- src/internationalization/PhutilLocale.php | 24 +- .../PhutilTranslation.php | 2 +- src/internationalization/PhutilTranslator.php | 10 +- src/internationalization/pht.php | 10 +- src/land/engine/ArcanistLandEngine.php | 14 +- src/lexer/PhutilLexer.php | 4 +- src/lexer/PhutilShellLexer.php | 2 +- src/lint/ArcanistLintMessage.php | 5 +- src/lint/engine/ArcanistLintEngine.php | 11 +- src/lint/linter/ArcanistBaseXHPASTLinter.php | 12 +- src/lint/linter/ArcanistChmodLinter.php | 2 +- src/lint/linter/ArcanistExternalLinter.php | 22 +- src/lint/linter/ArcanistFutureLinter.php | 2 +- src/lint/linter/ArcanistLinter.php | 12 +- .../linter/ArcanistScriptAndRegexLinter.php | 5 +- src/lint/linter/ArcanistXHPASTLinter.php | 2 +- .../__tests__/ArcanistLinterTestCase.php | 4 +- .../standards/ArcanistLinterStandard.php | 8 +- .../xhpast/ArcanistXHPASTLintNamingHook.php | 23 +- .../xhpast/ArcanistXHPASTLinterRule.php | 12 +- src/moduleutils/PhutilLibraryMapBuilder.php | 18 +- src/object/Phobject.php | 5 +- src/parser/ArcanistDiffParser.php | 2 +- src/parser/PhutilEditorConfig.php | 8 +- src/parser/PhutilJSON.php | 18 +- src/parser/PhutilLanguageGuesser.php | 2 +- src/parser/PhutilQueryStringParser.php | 6 +- src/parser/PhutilSimpleOptions.php | 10 +- src/parser/aast/api/AASTNode.php | 6 +- src/parser/argument/PhutilArgumentParser.php | 15 +- .../argument/PhutilArgumentSpecification.php | 2 +- src/parser/xhpast/api/XHPASTNode.php | 1 - .../api/__tests__/XHPASTNodeTestCase.php | 2 +- src/parser/xhpast/bin/PhutilXHPASTBinary.php | 2 +- .../PhutilReadableSerializer.php | 29 +-- src/repository/api/ArcanistGitAPI.php | 22 +- src/repository/api/ArcanistMercurialAPI.php | 15 +- src/repository/api/ArcanistRepositoryAPI.php | 12 +- .../parser/ArcanistMercurialParser.php | 8 +- .../state/ArcanistRepositoryLocalState.php | 2 +- src/symbols/PhutilClassMapQuery.php | 14 +- src/symbols/PhutilSymbolLoader.php | 14 +- src/unit/ArcanistUnitTestResult.php | 4 +- src/unit/engine/CSharpToolsTestEngine.php | 16 +- src/unit/engine/PhpunitTestEngine.php | 4 +- src/unit/engine/XUnitTestEngine.php | 22 +- src/unit/engine/phutil/PhutilTestCase.php | 84 +++---- src/unit/parser/ArcanistTestResultParser.php | 4 +- src/upload/ArcanistFileDataRef.php | 8 +- src/upload/ArcanistFileUploader.php | 4 +- src/utils/AbstractDirectedGraph.php | 11 +- src/utils/CaseInsensitiveArray.php | 4 +- src/utils/PhutilBufferedIterator.php | 2 +- src/utils/PhutilCallbackFilterIterator.php | 4 +- src/utils/PhutilChunkedIterator.php | 4 +- src/utils/PhutilRope.php | 6 +- src/utils/PhutilSystem.php | 4 +- src/utils/utf8.php | 62 ++--- src/utils/utils.php | 212 +++++++++--------- src/utils/viewutils.php | 10 +- src/workflow/ArcanistDiffWorkflow.php | 6 +- src/workflow/ArcanistUnitWorkflow.php | 4 +- src/workflow/ArcanistWorkflow.php | 42 ++-- .../ArcanistWorkingCopyIdentity.php | 13 +- src/xsprintf/csprintf.php | 6 +- src/xsprintf/pregsprintf.php | 6 +- src/xsprintf/xsprintf.php | 18 +- 103 files changed, 760 insertions(+), 715 deletions(-) diff --git a/src/channel/PhutilChannel.php b/src/channel/PhutilChannel.php index 65ea544b..2827de10 100644 --- a/src/channel/PhutilChannel.php +++ b/src/channel/PhutilChannel.php @@ -65,7 +65,7 @@ abstract class PhutilChannel extends Phobject { * * The default implementation accepts bytes. * - * @param wild Data to write to the channel, normally bytes. + * @param wild $bytes Data to write to the channel, normally bytes. * @return this * * @task io @@ -90,8 +90,8 @@ abstract class PhutilChannel extends Phobject { * Wait for any activity on a list of channels. Convenience wrapper around * @{method:waitForActivity}. * - * @param list A list of channels to wait for. - * @param dict Options, see above. + * @param list $channels A list of channels to wait for. + * @param dict $options (optional) Options, see above. * @return void * * @task wait @@ -119,8 +119,9 @@ abstract class PhutilChannel extends Phobject { * NOTE: Extra streams must be //streams//, not //sockets//, because this * method uses `stream_select()`, not `socket_select()`. * - * @param list List of channels to wait for reads on. - * @param list List of channels to wait for writes on. + * @param list $reads List of channels to wait for reads on. + * @param list $writes List of channels to wait for writes on. + * @param dict $options (optional) Options, see above. * @return void * * @task wait @@ -245,7 +246,7 @@ abstract class PhutilChannel extends Phobject { * Set a channel name. This is primarily intended to allow you to debug * channel code more easily, by naming channels something meaningful. * - * @param string Channel name. + * @param string $name Channel name. * @return this * * @task impl @@ -313,7 +314,7 @@ abstract class PhutilChannel extends Phobject { /** * Read from the channel's underlying I/O. * - * @param int Maximum number of bytes to read. + * @param int $length Maximum number of bytes to read. * @return string Bytes, if available. * * @task impl @@ -324,7 +325,7 @@ abstract class PhutilChannel extends Phobject { /** * Write to the channel's underlying I/O. * - * @param string Bytes to write. + * @param string $bytes Bytes to write. * @return int Number of bytes written. * * @task impl @@ -361,7 +362,8 @@ abstract class PhutilChannel extends Phobject { * block once the buffer reaches this size until the in-process buffer is * consumed. * - * @param int|null Maximum read buffer size, or `null` for a limitless buffer. + * @param int|null $size Maximum read buffer size, or `null` for a limitless + * buffer. * @return this * @task impl */ diff --git a/src/channel/PhutilExecChannel.php b/src/channel/PhutilExecChannel.php index 0d4e722b..0f862103 100644 --- a/src/channel/PhutilExecChannel.php +++ b/src/channel/PhutilExecChannel.php @@ -57,7 +57,7 @@ final class PhutilExecChannel extends PhutilChannel { * because @{class:ExecFuture} closes stdin by default when futures start. * If stdin has been closed, you will be unable to write on the channel. * - * @param ExecFuture Future to use as an underlying I/O source. + * @param ExecFuture $future Future to use as an underlying I/O source. * @task construct */ public function __construct(ExecFuture $future) { @@ -162,7 +162,7 @@ final class PhutilExecChannel extends PhutilChannel { * You can set a handler which does nothing to effectively ignore and discard * any output on stderr. * - * @param callable Handler to invoke when stderr data is received. + * @param callable $handler Handler to invoke when stderr data is received. * @return this */ public function setStderrHandler($handler) { diff --git a/src/channel/PhutilProtocolChannel.php b/src/channel/PhutilProtocolChannel.php index 2e018fd8..1670857e 100644 --- a/src/channel/PhutilProtocolChannel.php +++ b/src/channel/PhutilProtocolChannel.php @@ -46,7 +46,7 @@ abstract class PhutilProtocolChannel extends PhutilChannelChannel { /** * Write a message to the channel. * - * @param wild Some message. + * @param wild $message Some message. * @return this * * @task io @@ -61,7 +61,7 @@ abstract class PhutilProtocolChannel extends PhutilChannelChannel { * Add a message to the queue. While you normally do not need to do this, * you can use it to inject out-of-band messages. * - * @param wild Some message. + * @param wild $message Some message. * @return this * * @task io @@ -78,7 +78,7 @@ abstract class PhutilProtocolChannel extends PhutilChannelChannel { /** * Encode a message for transmission. * - * @param wild Some message. + * @param wild $message Some message. * @return string The message serialized into a wire format for * transmission. * @@ -100,7 +100,7 @@ abstract class PhutilProtocolChannel extends PhutilChannelChannel { * a parser in this method, and store parser state on the object to be able * to process incoming data in small chunks. * - * @param string One or more bytes from the underlying channel. + * @param string $data One or more bytes from the underlying channel. * @return list Zero or more parsed messages. * * @task protocol diff --git a/src/channel/PhutilSocketChannel.php b/src/channel/PhutilSocketChannel.php index e8cf9cf1..41cd2ddc 100644 --- a/src/channel/PhutilSocketChannel.php +++ b/src/channel/PhutilSocketChannel.php @@ -33,9 +33,10 @@ final class PhutilSocketChannel extends PhutilChannel { * `stream_socket_server()` or similar, not a //plain// socket from * `socket_create()` or similar. * - * @param socket Socket (stream socket, not plain socket). If only one - * socket is provided, it is used for reading and writing. - * @param socket (optional) Write socket. + * @param socket $read_socket Socket (stream socket, not plain socket). If + * only one socket is provided, it is used for reading and + * writing. + * @param socket $write_socket (optional) Write socket. * * @task construct */ diff --git a/src/conduit/ConduitClient.php b/src/conduit/ConduitClient.php index 441fe25c..21db1427 100644 --- a/src/conduit/ConduitClient.php +++ b/src/conduit/ConduitClient.php @@ -206,7 +206,7 @@ final class ConduitClient extends Phobject { * This implicit port behavior is similar to what browsers do, so it is less * likely to get us into trouble with webserver configurations. * - * @param bool True to include the port explicitly. + * @param bool $with_explicit_port True to include the port explicitly. * @return string String describing the host for the request. */ private function newHostString($with_explicit_port) { diff --git a/src/configuration/ArcanistConfigurationManager.php b/src/configuration/ArcanistConfigurationManager.php index 68ebde4e..36c05b20 100644 --- a/src/configuration/ArcanistConfigurationManager.php +++ b/src/configuration/ArcanistConfigurationManager.php @@ -50,8 +50,8 @@ final class ArcanistConfigurationManager extends Phobject { * arguments ("runtime"). * The precedence is runtime > local > project > user > system * - * @param key Key to read. - * @param wild Default value if key is not found. + * @param key $key Key to read. + * @param wild $default (optional) Default value if key is not found. * @return wild Value, or default value if not found. * * @task config @@ -71,7 +71,7 @@ final class ArcanistConfigurationManager extends Phobject { * The map is ordered by the canonical sources precedence, which is: * runtime > local > project > user > system * - * @param key Key to read + * @param key $key Key to read * @return array Mapping of source => value read. Sources with no value are * not in the array. * @@ -135,8 +135,8 @@ final class ArcanistConfigurationManager extends Phobject { * Sets a runtime config value that takes precedence over any static * config values. * - * @param key Key to set. - * @param value The value of the key. + * @param key $key Key to set. + * @param value $value The value of the key. * * @task config */ diff --git a/src/console/PhutilConsole.php b/src/console/PhutilConsole.php index 5d646f7c..f6eabe71 100644 --- a/src/console/PhutilConsole.php +++ b/src/console/PhutilConsole.php @@ -56,7 +56,7 @@ final class PhutilConsole extends Phobject { /** * Set the active console. * - * @param PhutilConsole + * @param PhutilConsole $console * @return void * @task construct */ diff --git a/src/console/PhutilInteractiveEditor.php b/src/console/PhutilInteractiveEditor.php index 3e12611c..eb3c4803 100644 --- a/src/console/PhutilInteractiveEditor.php +++ b/src/console/PhutilInteractiveEditor.php @@ -31,7 +31,7 @@ final class PhutilInteractiveEditor extends Phobject { /** * Constructs an interactive editor, using the text of a document. * - * @param string Document text. + * @param string $content Document text. * @return $this * * @task create @@ -171,7 +171,7 @@ final class PhutilInteractiveEditor extends Phobject { * opens. By default, the cursor will be positioned at the start of the * content. * - * @param int Line number where the cursor should be positioned. + * @param int $offset Line number where the cursor should be positioned. * @return $this * * @task config @@ -198,7 +198,7 @@ final class PhutilInteractiveEditor extends Phobject { * Set the document name. Depending on the editor, this may be exposed to * the user and can give them a sense of what they're editing. * - * @param string Document name. + * @param string $name Document name. * @return $this * * @task config @@ -228,7 +228,7 @@ final class PhutilInteractiveEditor extends Phobject { /** * Set the text content to be edited. * - * @param string New content. + * @param string $content New content. * @return $this * * @task config @@ -255,7 +255,7 @@ final class PhutilInteractiveEditor extends Phobject { * Set the fallback editor program to be used if the env variable $EDITOR * is not available and there is no `editor` binary in PATH. * - * @param string Command-line editing program (e.g. 'emacs', 'vi') + * @param string $editor Command-line editing program (e.g. 'emacs', 'vi') * @return $this * * @task config @@ -270,7 +270,7 @@ final class PhutilInteractiveEditor extends Phobject { * Set the preferred editor program. If set, this will override all other * sources of editor configuration, like $EDITOR. * - * @param string Command-line editing program (e.g. 'emacs', 'vi') + * @param string $editor Command-line editing program (e.g. 'emacs', 'vi') * @return $this * * @task config @@ -284,7 +284,7 @@ final class PhutilInteractiveEditor extends Phobject { * Set the message that identifies the task for which the editor is being * launched, displayed to the user prior to it being launched. * - * @param string The message to display to the user. + * @param string $task_message The message to display to the user. * @return $this * * @task config diff --git a/src/console/format.php b/src/console/format.php index a4fa98d5..7e621a92 100644 --- a/src/console/format.php +++ b/src/console/format.php @@ -94,9 +94,9 @@ function phutil_console_prompt($prompt, $history = '') { * Soft wrap text for display on a console, respecting UTF8 character boundaries * and ANSI color escape sequences. * - * @param string Text to wrap. - * @param int Optional indent level. - * @param bool True to also indent the first line. + * @param string $text Text to wrap. + * @param int $indent (optional) Indent level. Defaults to 0. + * @param bool $with_prefix (Optional) True to also indent the first line. * @return string Wrapped text. */ function phutil_console_wrap($text, $indent = 0, $with_prefix = true) { diff --git a/src/console/view/PhutilConsoleTable.php b/src/console/view/PhutilConsoleTable.php index 392ff813..86e9f4e3 100644 --- a/src/console/view/PhutilConsoleTable.php +++ b/src/console/view/PhutilConsoleTable.php @@ -219,7 +219,7 @@ final class PhutilConsoleTable extends PhutilConsoleView { /** * Get the width of a specific column, including padding. * - * @param string + * @param string $key * @return int */ protected function getWidth($key) { @@ -265,7 +265,7 @@ final class PhutilConsoleTable extends PhutilConsoleView { /** * Format cells into an entire row. * - * @param list + * @param list $columns * @return string */ protected function formatRow(array $columns) { diff --git a/src/console/view/PhutilConsoleView.php b/src/console/view/PhutilConsoleView.php index 85f5b8f9..39fe58c6 100644 --- a/src/console/view/PhutilConsoleView.php +++ b/src/console/view/PhutilConsoleView.php @@ -57,7 +57,7 @@ abstract class PhutilConsoleView extends Phobject { /** * Reduce a view to a list of simple, unnested parts. * - * @param wild Any drawable view. + * @param wild $view Any drawable view. * @return list List of unnested drawables. * @task draw */ @@ -84,7 +84,7 @@ abstract class PhutilConsoleView extends Phobject { /** - * @param list List of views, one per line. + * @param list $parts List of views, one per line. * @return wild Each view rendered on a separate line. */ final protected function drawLines(array $parts) { diff --git a/src/differential/ArcanistDifferentialCommitMessage.php b/src/differential/ArcanistDifferentialCommitMessage.php index cada4895..27053d91 100644 --- a/src/differential/ArcanistDifferentialCommitMessage.php +++ b/src/differential/ArcanistDifferentialCommitMessage.php @@ -111,7 +111,7 @@ final class ArcanistDifferentialCommitMessage extends Phobject { /** * Extract the revision ID from a commit message. * - * @param string Raw commit message. + * @param string $corpus Raw commit message. * @return int|null Revision ID, if the commit message contains one. */ private function parseRevisionIDFromRawCorpus($corpus) { diff --git a/src/error/PhutilErrorHandler.php b/src/error/PhutilErrorHandler.php index 2fc8fe7d..510fe9f8 100644 --- a/src/error/PhutilErrorHandler.php +++ b/src/error/PhutilErrorHandler.php @@ -88,7 +88,7 @@ final class PhutilErrorHandler extends Phobject { * can use @{class:PhutilProxyException} to nest exceptions; after PHP 5.3 * all exceptions are nestable. * - * @param Exception|Throwable Exception to unnest. + * @param Exception|Throwable $ex Exception to unnest. * @return Exception|Throwable|null Previous exception, if one exists. * @task exutil */ @@ -106,7 +106,7 @@ final class PhutilErrorHandler extends Phobject { /** * Find the most deeply nested exception from a possibly-nested exception. * - * @param Exception|Throwable A possibly-nested exception. + * @param Exception|Throwable $ex A possibly-nested exception. * @return Exception|Throwable Deepest exception in the nest. * @task exutil */ @@ -126,7 +126,7 @@ final class PhutilErrorHandler extends Phobject { * Adds an error trap. Normally you should not invoke this directly; * @{class:PhutilErrorTrap} registers itself on construction. * - * @param PhutilErrorTrap Trap to add. + * @param PhutilErrorTrap $trap Trap to add. * @return void * @task trap */ @@ -140,7 +140,7 @@ final class PhutilErrorHandler extends Phobject { * Removes an error trap. Normally you should not invoke this directly; * @{class:PhutilErrorTrap} deregisters itself on destruction. * - * @param PhutilErrorTrap Trap to remove. + * @param PhutilErrorTrap $trap Trap to remove. * @return void * @task trap */ @@ -179,11 +179,11 @@ final class PhutilErrorHandler extends Phobject { * This handler converts E_NOTICE messages from uses of undefined variables * into @{class:RuntimeException}s. * - * @param int Error code. - * @param string Error message. - * @param string File where the error occurred. - * @param int Line on which the error occurred. - * @param wild Error context information. + * @param int $num Error code. + * @param string $str Error message. + * @param string $file File where the error occurred. + * @param int $line Line on which the error occurred. + * @param wild $ctx (optional) Error context information. * @return void * @task internal */ @@ -278,7 +278,7 @@ final class PhutilErrorHandler extends Phobject { * ##set_exception_handler()##. You should not call this function directly; * to print exceptions, pass the exception object to @{function:phlog}. * - * @param Exception|Throwable Uncaught exception object. + * @param Exception|Throwable $ex Uncaught exception object. * @return void * @task internal */ @@ -304,7 +304,7 @@ final class PhutilErrorHandler extends Phobject { /** * Output a stacktrace to the PHP error log. * - * @param trace A stacktrace, e.g. from debug_backtrace(); + * @param trace $trace A stacktrace, e.g. from debug_backtrace(); * @return void * @task internal */ @@ -319,7 +319,7 @@ final class PhutilErrorHandler extends Phobject { /** * Format a stacktrace for output. * - * @param trace A stacktrace, e.g. from debug_backtrace(); + * @param trace $trace A stacktrace, e.g. from debug_backtrace(); * @return string Human-readable trace. * @task internal */ @@ -382,9 +382,9 @@ final class PhutilErrorHandler extends Phobject { * dispatched to the listener; this method also prints them to the PHP error * log. * - * @param const Event type constant. - * @param wild Event value. - * @param dict Event metadata. + * @param const $event Event type constant. + * @param wild $value Event value. + * @param dict $metadata Event metadata. * @return void * @task internal */ @@ -560,7 +560,7 @@ final class PhutilErrorHandler extends Phobject { * all of the places an exception came from, even if it came from multiple * origins and has been aggregated or proxied. * - * @param Exception|Throwable Exception to retrieve a trace for. + * @param Exception|Throwable $ex Exception to retrieve a trace for. * @return list List of stack frames. */ public static function getExceptionTrace($ex) { diff --git a/src/error/phlog.php b/src/error/phlog.php index 52dc6af9..6dff4f06 100644 --- a/src/error/phlog.php +++ b/src/error/phlog.php @@ -5,8 +5,8 @@ * forwards it to registered listeners. This is essentially a more powerful * version of `error_log()`. * - * @param wild Any value you want printed to the error log or other registered - * logs/consoles. + * @param wild $value Any value you want printed to the error log or other + * registered logs/consoles. * @param ... Other values to be logged. * @return wild Passed $value. */ @@ -52,15 +52,15 @@ function phlog($value/* , ... */) { * you don't want to display these, test for `@` being in effect by checking if * `error_reporting() === 0` before displaying the error. * - * @param const A PhutilErrorHandler constant, like PhutilErrorHandler::ERROR, - * which indicates the event type (e.g. error, exception, - * user message). - * @param wild The event value, like the Exception object for an exception - * event, an error string for an error event, or some user object - * for user messages. - * @param dict A dictionary of metadata about the event. The keys 'file', - * 'line' and 'trace' are always available. Other keys may be - * present, depending on the event type. + * @param const $event A PhutilErrorHandler constant, like + * PhutilErrorHandler::ERROR, which indicates the event type + * (e.g. error, exception, user message). + * @param wild $value The event value, like the Exception object for an + * exception event, an error string for an error event, or some + * user object for user messages. + * @param dict $metadata A dictionary of metadata about the event. The keys + * 'file', 'line' and 'trace' are always available. Other keys + * may be present, depending on the event type. * @return void */ function phutil_error_listener_example($event, $value, array $metadata) { diff --git a/src/filesystem/FileFinder.php b/src/filesystem/FileFinder.php index 6b1dbbb4..4eb2c3fd 100644 --- a/src/filesystem/FileFinder.php +++ b/src/filesystem/FileFinder.php @@ -31,7 +31,7 @@ final class FileFinder extends Phobject { /** * Create a new FileFinder. * - * @param string Root directory to find files beneath. + * @param string $root Root directory to find files beneath. * @return this * @task create */ @@ -106,7 +106,7 @@ final class FileFinder extends Phobject { /** * @task config - * @param string Either "php", "shell", or the empty string. + * @param string $mode Either "php", "shell", or the empty string. */ public function setForceMode($mode) { $this->forceMode = $mode; diff --git a/src/filesystem/FileList.php b/src/filesystem/FileList.php index 656c92de..89eb6f7d 100644 --- a/src/filesystem/FileList.php +++ b/src/filesystem/FileList.php @@ -26,7 +26,7 @@ final class FileList extends Phobject { /** * Build a new FileList from an array of paths, e.g. from $argv. * - * @param list List of relative or absolute file paths. + * @param list $paths List of relative or absolute file paths. * @return this * @task create */ @@ -46,10 +46,11 @@ final class FileList extends Phobject { * Determine if a path is one of the paths in the list. Note that an empty * file list is considered to contain every file. * - * @param string Relative or absolute system file path. - * @param bool If true, consider the path to be contained in the list if - * the list contains a parent directory. If false, require - * that the path be part of the list explicitly. + * @param string $path Relative or absolute system file path. + * @param bool $allow_parent_directory (optional) If true, consider the + * path to be contained in the list if the list contains a + * parent directory. If false, require that the path be part + * of the list explicitly. * @return bool If true, the file is in the list. * @task test */ diff --git a/src/filesystem/Filesystem.php b/src/filesystem/Filesystem.php index dd6e984a..ca93f4cf 100644 --- a/src/filesystem/Filesystem.php +++ b/src/filesystem/Filesystem.php @@ -25,8 +25,8 @@ final class Filesystem extends Phobject { * Read a file in a manner similar to file_get_contents(), but throw detailed * exceptions on failure. * - * @param string File path to read. This file must exist and be readable, - * or an exception will be thrown. + * @param string $path File path to read. This file must exist and be + * readable, or an exception will be thrown. * @return string Contents of the specified file. * * @task file @@ -79,9 +79,9 @@ final class Filesystem extends Phobject { * detailed exceptions on failure. If the file already exists, it will be * overwritten. * - * @param string File path to write. This file must be writable and its - * parent directory must exist. - * @param string Data to write. + * @param string $path File path to write. This file must be writable and + * its parent directory must exist. + * @param string $data Data to write. * * @task file */ @@ -106,8 +106,8 @@ final class Filesystem extends Phobject { * file without needing locking; any given read of the file is guaranteed to * be self-consistent and not see partial file contents. * - * @param string file path to write - * @param string data to write + * @param string $path file path to write + * @param string $data data to write * * @return boolean indicating whether the file was changed by this function. */ @@ -159,10 +159,10 @@ final class Filesystem extends Phobject { * exists, e.g. "example.bak", "example.bak.1", "example.bak.2", etc. (Don't * rely on this exact behavior, of course.) * - * @param string Suggested filename, like "example.bak". This name will - * be used if it does not exist, or some similar name will - * be chosen if it does. - * @param string Data to write to the file. + * @param string $base Suggested filename, like "example.bak". This name + * will be used if it does not exist, or some similar name + * will be chosen if it does. + * @param string $data Data to write to the file. * @return string Path to a newly created and written file which did not * previously exist, like "example.bak.3". * @task file @@ -207,9 +207,9 @@ final class Filesystem extends Phobject { * Append to a file without having to deal with file handles, with * detailed exceptions on failure. * - * @param string File path to write. This file must be writable or its - * parent directory must exist and be writable. - * @param string Data to write. + * @param string $path File path to write. This file must be writable or + * its parent directory must exist and be writable. + * @param string $data Data to write. * * @task file */ @@ -253,9 +253,9 @@ final class Filesystem extends Phobject { /** * Copy a file, preserving file attributes (if relevant for the OS). * - * @param string File path to copy from. This file must exist and be + * @param string $from File path to copy from. This file must exist and be * readable, or an exception will be thrown. - * @param string File path to copy to. If a file exists at this path + * @param string $to File path to copy to. If a file exists at this path * already, it wll be overwritten. * * @task file @@ -301,7 +301,7 @@ final class Filesystem extends Phobject { /** * Remove a file or directory. * - * @param string File to a path or directory to remove. + * @param string $path File to a path or directory to remove. * @return void * * @task file @@ -327,8 +327,8 @@ final class Filesystem extends Phobject { /** * Rename a file or directory. * - * @param string Old path. - * @param string New path. + * @param string $old Old path. + * @param string $new New path. * * @task file */ @@ -351,7 +351,7 @@ final class Filesystem extends Phobject { * Internal. Recursively remove a file or an entire directory. Implements * the core function of @{method:remove} in a way that works on Windows. * - * @param string File to a path or directory to remove. + * @param string $path File to a path or directory to remove. * @return void * * @task file @@ -381,9 +381,9 @@ final class Filesystem extends Phobject { /** * Change the permissions of a file or directory. * - * @param string Path to the file or directory. - * @param int Permission umask. Note that umask is in octal, so you - * should specify it as, e.g., `0777', not `777'. + * @param string $path Path to the file or directory. + * @param int $umask Permission umask. Note that umask is in octal, so + * you should specify it as, e.g., `0777', not `777'. * @return void * * @task file @@ -405,7 +405,7 @@ final class Filesystem extends Phobject { /** * Get the last modified time of a file * - * @param string Path to file + * @param string $path Path to file * @return int Time last modified * * @task file @@ -432,7 +432,7 @@ final class Filesystem extends Phobject { * Read random bytes from /dev/urandom or equivalent. See also * @{method:readRandomCharacters}. * - * @param int Number of bytes to read. + * @param int $number_of_bytes Number of bytes to read. * @return string Random bytestring of the provided length. * * @task file @@ -530,7 +530,7 @@ final class Filesystem extends Phobject { * output (a-z, 0-9) so it's appropriate for use in URIs and other contexts * where it needs to be human readable. * - * @param int Number of characters to read. + * @param int $number_of_characters Number of characters to read. * @return string Random character string of the provided length. * * @task file @@ -563,8 +563,8 @@ final class Filesystem extends Phobject { * * This method uses less-entropic random sources under older versions of PHP. * - * @param int Minimum value, inclusive. - * @param int Maximum value, inclusive. + * @param int $min Minimum value, inclusive. + * @param int $max Maximum value, inclusive. */ public static function readRandomInteger($min, $max) { if (!is_int($min)) { @@ -612,9 +612,9 @@ final class Filesystem extends Phobject { * Identify the MIME type of a file. This returns only the MIME type (like * text/plain), not the encoding (like charset=utf-8). * - * @param string Path to the file to examine. - * @param string Optional default mime type to return if the file's mime - * type can not be identified. + * @param string $path Path to the file to examine. + * @param string $default (optional) default mime type to return if the + * file's mime type can not be identified. * @return string File mime type. * * @task file @@ -693,11 +693,12 @@ final class Filesystem extends Phobject { * Create a directory in a manner similar to mkdir(), but throw detailed * exceptions on failure. * - * @param string Path to directory. The parent directory must exist and - * be writable. - * @param int Permission umask. Note that umask is in octal, so you - * should specify it as, e.g., `0777', not `777'. - * @param boolean Recursively create directories. Default to false. + * @param string $path Path to directory. The parent directory must exist + * and be writable. + * @param int $umask Permission umask. Note that umask is in octal, so + * you should specify it as, e.g., `0777', not `777'. + * @param boolean $recursive (optional) Recursively create directories. + * Defaults to false. * @return string Path to the created directory. * * @task directory @@ -752,11 +753,13 @@ final class Filesystem extends Phobject { * responsible for removing it (e.g., with Filesystem::remove()) * when you are done with it. * - * @param string Optional directory prefix. - * @param int Permissions to create the directory with. By default, - * these permissions are very restrictive (0700). - * @param string Optional root directory. If not provided, the system - * temporary directory (often "/tmp") will be used. + * @param string $prefix (optional) directory prefix. + * @param int $umask (optional) Permissions to create the directory + * with. By default, these permissions are very restrictive + * (0700). + * @param string $root_directory (optional) Root directory. If not + * provided, the system temporary directory (often "/tmp") + * will be used. * @return string Path to newly created temporary directory. * * @task directory @@ -814,8 +817,9 @@ final class Filesystem extends Phobject { /** * List files in a directory. * - * @param string Path, absolute or relative to PWD. - * @param bool If false, exclude files beginning with a ".". + * @param string $path Path, absolute or relative to PWD. + * @param bool $include_hidden If false, exclude files beginning with + * a ".". * * @return array List of files and directories in the specified * directory, excluding `.' and `..'. @@ -850,8 +854,8 @@ final class Filesystem extends Phobject { * Return all directories between a path and the specified root directory * (defaulting to "/"). Iterating over them walks from the path to the root. * - * @param string Path, absolute or relative to PWD. - * @param string The root directory. + * @param string $path Path, absolute or relative to PWD. + * @param string $root (optional) The root directory. * @return list List of parent paths, including the provided path. * @task directory */ @@ -924,7 +928,7 @@ final class Filesystem extends Phobject { /** * Checks if a path is specified as an absolute path. * - * @param string + * @param string $path * @return bool */ public static function isAbsolutePath($path) { @@ -940,8 +944,8 @@ final class Filesystem extends Phobject { * default PWD), following parent symlinks and removing artifacts. If the * path is itself a symlink it is left unresolved. * - * @param string Path, absolute or relative to PWD. - * @return string Canonical, absolute path. + * @param string $path Path, absolute or relative to PWD. + * @return string $relative_to (optional) Canonical, absolute path. * * @task path */ @@ -1009,8 +1013,8 @@ final class Filesystem extends Phobject { * symlinks and removing artifacts. Both paths must exists for the relation * to obtain. A path is always a descendant of itself as long as it exists. * - * @param string Child path, absolute or relative to PWD. - * @param string Root path, absolute or relative to PWD. + * @param string $path Child path, absolute or relative to PWD. + * @param string $root Root path, absolute or relative to PWD. * @return bool True if resolved child path is in fact a descendant of * resolved root path and both exist. * @task path @@ -1031,8 +1035,8 @@ final class Filesystem extends Phobject { * guaranteed that you can use resolvePath() to restore a path to its * canonical format. * - * @param string Path, absolute or relative to PWD. - * @param string Optionally, working directory to make files readable + * @param string $path Path, absolute or relative to PWD. + * @param string $pwd (optional) Working directory to make files readable * relative to. * @return string Human-readable path. * @@ -1060,7 +1064,7 @@ final class Filesystem extends Phobject { * file_exists() in that it returns true for symlinks. This method does not * attempt to resolve paths before testing them. * - * @param string Test for the existence of this path. + * @param string $path Test for the existence of this path. * @return bool True if the path exists in the filesystem. * @task path */ @@ -1073,7 +1077,7 @@ final class Filesystem extends Phobject { * Determine if an executable binary (like `git` or `svn`) exists within * the configured `$PATH`. * - * @param string Binary name, like `'git'` or `'svn'`. + * @param string $binary Binary name, like `'git'` or `'svn'`. * @return bool True if the binary exists and is executable. * @task exec */ @@ -1086,7 +1090,7 @@ final class Filesystem extends Phobject { * Locates the full path that an executable binary (like `git` or `svn`) is at * the configured `$PATH`. * - * @param string Binary name, like `'git'` or `'svn'`. + * @param string $binary Binary name, like `'git'` or `'svn'`. * @return string The full binary path if it is present, or null. * @task exec */ @@ -1129,8 +1133,8 @@ final class Filesystem extends Phobject { * resolvePath() only resolves symlinks in parent directories, not the * path itself. * - * @param string First path to test for equivalence. - * @param string Second path to test for equivalence. + * @param string $u First path to test for equivalence. + * @param string $v Second path to test for equivalence. * @return bool True if both paths are equivalent, i.e. reference the same * entity in the filesystem. * @task path @@ -1171,7 +1175,7 @@ final class Filesystem extends Phobject { * Assert that something (e.g., a file, directory, or symlink) exists at a * specified location. * - * @param string Assert that this path exists. + * @param string $path Assert that this path exists. * @return void * * @task assert @@ -1223,7 +1227,7 @@ final class Filesystem extends Phobject { /** * Assert that nothing exists at a specified location. * - * @param string Assert that this path does not exist. + * @param string $path Assert that this path does not exist. * @return void * * @task assert @@ -1240,7 +1244,7 @@ final class Filesystem extends Phobject { /** * Assert that a path represents a file, strictly (i.e., not a directory). * - * @param string Assert that this path is a file. + * @param string $path Assert that this path is a file. * @return void * * @task assert @@ -1257,7 +1261,7 @@ final class Filesystem extends Phobject { /** * Assert that a path represents a directory, strictly (i.e., not a file). * - * @param string Assert that this path is a directory. + * @param string $path Assert that this path is a directory. * @return void * * @task assert @@ -1274,7 +1278,7 @@ final class Filesystem extends Phobject { /** * Assert that a file or directory exists and is writable. * - * @param string Assert that this path is writable. + * @param string $path Assert that this path is writable. * @return void * * @task assert @@ -1291,7 +1295,7 @@ final class Filesystem extends Phobject { /** * Assert that a file or directory exists and is readable. * - * @param string Assert that this path is readable. + * @param string $path Assert that this path is readable. * @return void * * @task assert diff --git a/src/filesystem/FilesystemException.php b/src/filesystem/FilesystemException.php index cc464ff7..d1ba12ab 100644 --- a/src/filesystem/FilesystemException.php +++ b/src/filesystem/FilesystemException.php @@ -11,8 +11,8 @@ final class FilesystemException extends Exception { /** * Create a new FilesystemException, providing a path and a message. * - * @param string Path that caused the failure. - * @param string Description of the failure. + * @param string $path Path that caused the failure. + * @param string $message Description of the failure. */ public function __construct($path, $message) { $this->path = $path; diff --git a/src/filesystem/PhutilDeferredLog.php b/src/filesystem/PhutilDeferredLog.php index 2193eb3c..e2d1ac35 100644 --- a/src/filesystem/PhutilDeferredLog.php +++ b/src/filesystem/PhutilDeferredLog.php @@ -55,9 +55,9 @@ final class PhutilDeferredLog extends Phobject { * * $log = new PhutilDeferredLog('/some/file.log', '[%T] %u'); * - * @param string|null The file the entry should be written to, or null to - * create a log object which does not write anywhere. - * @param string The log entry format. + * @param string|null $file The file the entry should be written to, or null + * to create a log object which does not write anywhere. + * @param string $format The log entry format. * @task log */ public function __construct($file, $format) { @@ -85,7 +85,7 @@ final class PhutilDeferredLog extends Phobject { * When the log is written, the "%T" and "%u" variables will be replaced with * the values you provide. * - * @param dict Map of variables to values. + * @param dict $map Map of variables to values. * @return this * @task log */ @@ -98,8 +98,9 @@ final class PhutilDeferredLog extends Phobject { /** * Get existing log data. * - * @param string Log data key. - * @param wild Default to return if data does not exist. + * @param string $key Log data key. + * @param wild $default (optional) Default to return if data does not + * exist. * @return wild Data, or default if data does not exist. * @task log */ @@ -114,8 +115,8 @@ final class PhutilDeferredLog extends Phobject { * * NOTE: You can not change the file after the log writes. * - * @param string|null File where the entry should be written to, or null to - * prevent writes. + * @param string|null $file File where the entry should be written to, or + * null to prevent writes. * @return this * @task log */ diff --git a/src/filesystem/PhutilFileLock.php b/src/filesystem/PhutilFileLock.php index e8dd07f4..01e3ffc5 100644 --- a/src/filesystem/PhutilFileLock.php +++ b/src/filesystem/PhutilFileLock.php @@ -29,7 +29,7 @@ final class PhutilFileLock extends PhutilLock { /** * Create a new lock on a lockfile. The file need not exist yet. * - * @param string The lockfile to use. + * @param string $lockfile The lockfile to use. * @return PhutilFileLock New lock object. * * @task construct @@ -59,7 +59,7 @@ final class PhutilFileLock extends PhutilLock { * If the lock is already held, this method throws. You can test the lock * status with @{method:isLocked}. * - * @param float Seconds to block waiting for the lock. + * @param float $wait Seconds to block waiting for the lock. * @return void * * @task lock diff --git a/src/filesystem/PhutilLock.php b/src/filesystem/PhutilLock.php index f69d7544..3be495e1 100644 --- a/src/filesystem/PhutilLock.php +++ b/src/filesystem/PhutilLock.php @@ -41,7 +41,7 @@ abstract class PhutilLock extends Phobject { * Build a new lock, given a lock name. The name should be globally unique * across all locks. * - * @param string Globally unique lock name. + * @param string $name Globally unique lock name. * @task construct */ protected function __construct($name) { @@ -55,7 +55,7 @@ abstract class PhutilLock extends Phobject { /** * Acquires the lock, or throws @{class:PhutilLockException} if it fails. * - * @param float Seconds to block waiting for the lock. + * @param float $wait Seconds to block waiting for the lock. * @return void * @task impl */ @@ -88,7 +88,7 @@ abstract class PhutilLock extends Phobject { /** * Get a named lock, if it has been registered. * - * @param string Lock name. + * @param string $name Lock name. * @task registry */ protected static function getLock($name) { @@ -99,7 +99,7 @@ abstract class PhutilLock extends Phobject { /** * Register a lock for cleanup when the process exits. * - * @param PhutilLock Lock to register. + * @param PhutilLock $lock Lock to register. * @task registry */ protected static function registerLock(PhutilLock $lock) { @@ -144,8 +144,8 @@ abstract class PhutilLock extends Phobject { * If the lock is already held by this process, this method throws. You can * test the lock status with @{method:isLocked}. * - * @param float Seconds to block waiting for the lock. By default, do not - * block. + * @param float $wait (optional) Seconds to block waiting for the lock. By + * default, do not block. * @return this * * @task lock diff --git a/src/filesystem/TempFile.php b/src/filesystem/TempFile.php index f905903c..ec493a7f 100644 --- a/src/filesystem/TempFile.php +++ b/src/filesystem/TempFile.php @@ -27,13 +27,13 @@ final class TempFile extends Phobject { /** * Create a new temporary file. * - * @param string (optional) Filename hint. This is useful if you intend to - * edit the file with an interactive editor, so the user's - * editor shows "commit-message" instead of + * @param string $filename (optional) Filename hint. This is useful if you + * intend to edit the file with an interactive editor, so the + * user's editor shows "commit-message" instead of * "p3810hf-1z9b89bas". - * @param string (optional) Root directory to hold the file. If omitted, the - * system temporary directory (often "/tmp") will be used by - * default. + * @param string $root_directory (optional) Root directory to hold the file. + * If omitted, the system temporary directory (often "/tmp") + * will be used by default. * @task create */ public function __construct($filename = null, $root_directory = null) { @@ -62,7 +62,7 @@ final class TempFile extends Phobject { * Normally, the file is deleted when this object passes out of scope. You * can set it to be preserved instead. * - * @param bool True to preserve the file after object destruction. + * @param bool $preserve True to preserve the file after object destruction. * @return this * @task config */ diff --git a/src/filesystem/linesofalarge/LinesOfALarge.php b/src/filesystem/linesofalarge/LinesOfALarge.php index 74a33b69..4b030bd9 100644 --- a/src/filesystem/linesofalarge/LinesOfALarge.php +++ b/src/filesystem/linesofalarge/LinesOfALarge.php @@ -56,7 +56,7 @@ abstract class LinesOfALarge extends Phobject implements Iterator { * without looking for delimiters. You can use this to stream a large file or * the output of a command which returns a large amount of data. * - * @param string|null A one-byte delimiter character. + * @param string|null $character A one-byte delimiter character. * @return this * @task config */ diff --git a/src/filesystem/linesofalarge/LinesOfALargeExecFuture.php b/src/filesystem/linesofalarge/LinesOfALargeExecFuture.php index c54151f1..484eb502 100644 --- a/src/filesystem/linesofalarge/LinesOfALargeExecFuture.php +++ b/src/filesystem/linesofalarge/LinesOfALargeExecFuture.php @@ -34,7 +34,7 @@ final class LinesOfALargeExecFuture extends LinesOfALarge { /** * To construct, pass an @{class:ExecFuture}. * - * @param ExecFuture Future to wrap. + * @param ExecFuture $future Future to wrap. * @return void * @task construct */ diff --git a/src/filesystem/linesofalarge/LinesOfALargeFile.php b/src/filesystem/linesofalarge/LinesOfALargeFile.php index e04c4074..9f85d19b 100644 --- a/src/filesystem/linesofalarge/LinesOfALargeFile.php +++ b/src/filesystem/linesofalarge/LinesOfALargeFile.php @@ -29,7 +29,7 @@ final class LinesOfALargeFile extends LinesOfALarge { /** * To construct, pass the path to a file. * - * @param string File path to read. + * @param string $file_name File path to read. * @return void * @task construct */ diff --git a/src/future/FutureIterator.php b/src/future/FutureIterator.php index bb464cd4..593d4942 100644 --- a/src/future/FutureIterator.php +++ b/src/future/FutureIterator.php @@ -52,7 +52,7 @@ final class FutureIterator /** * Create a new iterator over a list of futures. * - * @param list List of @{class:Future}s to resolve. + * @param list $futures List of @{class:Future}s to resolve. * @task basics */ public function __construct(array $futures) { @@ -90,7 +90,7 @@ final class FutureIterator * set of futures to run mostly in parallel, but some futures depend on * others. * - * @param Future @{class:Future} to add to iterator + * @param Future $future @{class:Future} to add to iterator * @task basics */ public function addFuture(Future $future) { @@ -133,8 +133,8 @@ final class FutureIterator * This will echo "Still working..." once per second as long as futures are * resolving. By default, FutureIterator never yields null. * - * @param float Maximum number of seconds to block waiting on futures before - * yielding null. + * @param float $interval Maximum number of seconds to block waiting on + * futures before yielding null. * @return this * * @task config @@ -154,7 +154,7 @@ final class FutureIterator * // Run no more than 4 futures simultaneously. * } * - * @param int Maximum number of simultaneous jobs allowed. + * @param int $max Maximum number of simultaneous jobs allowed. * @return this * * @task config @@ -417,9 +417,9 @@ final class FutureIterator /** * Wait for activity on one of several sockets. * - * @param list List of sockets expected to become readable. - * @param list List of sockets expected to become writable. - * @param float Timeout, in seconds. + * @param list $read_list List of sockets expected to become readable. + * @param list $write_list List of sockets expected to become writable. + * @param float $timeout (optional) Timeout, in seconds. * @return void */ private function waitForSockets( diff --git a/src/future/exec/ExecFuture.php b/src/future/exec/ExecFuture.php index ddf9e515..5c25fc97 100644 --- a/src/future/exec/ExecFuture.php +++ b/src/future/exec/ExecFuture.php @@ -119,7 +119,7 @@ final class ExecFuture extends PhutilExecutableFuture { * * NOTE: Setting this to 0 means "no buffer", not "unlimited buffer". * - * @param int Maximum size of the stdout read buffer. + * @param int $limit Maximum size of the stdout read buffer. * @return this * @task config */ @@ -133,7 +133,7 @@ final class ExecFuture extends PhutilExecutableFuture { * Set a maximum size for the stderr read buffer. * See @{method:setStdoutSizeLimit} for discussion. * - * @param int Maximum size of the stderr read buffer. + * @param int $limit Maximum size of the stderr read buffer. * @return this * @task config */ @@ -153,7 +153,8 @@ final class ExecFuture extends PhutilExecutableFuture { * TODO: We should probably release the read buffer limit during * @{method:resolve}, or otherwise detect this. For now, be careful. * - * @param int|null Maximum buffer size, or `null` for unlimited. + * @param int|null $read_buffer_size Maximum buffer size, or `null` for + * unlimited. * @return this */ public function setReadBufferSize($read_buffer_size) { @@ -233,12 +234,12 @@ final class ExecFuture extends PhutilExecutableFuture { /** * Write data to stdin of the command. * - * @param string Data to write. - * @param bool If true, keep the pipe open for writing. By default, the pipe - * will be closed as soon as possible so that commands which - * listen for EOF will execute. If you want to keep the pipe open - * past the start of command execution, do an empty write with - * `$keep_pipe = true` first. + * @param string $data Data to write. + * @param bool $keep_pipe (optional) If true, keep the pipe open for writing. + * By default, the pipe will be closed as soon as possible so + * that commands which listen for EOF will execute. If you want + * to keep the pipe open past the start of command execution, do + * an empty write with `$keep_pipe = true` first. * @return this * @task interact */ @@ -308,8 +309,8 @@ final class ExecFuture extends PhutilExecutableFuture { * The subprocess will be sent a `TERM` signal, and then a `KILL` signal a * short while later if it fails to exit. * - * @param int Maximum number of seconds this command may execute for before - * it is signaled. + * @param int $seconds Maximum number of seconds this command may execute for + * before it is signaled. * @return this * @task config */ @@ -523,13 +524,13 @@ final class ExecFuture extends PhutilExecutableFuture { * Reads some bytes from a stream, discarding output once a certain amount * has been accumulated. * - * @param resource Stream to read from. - * @param int Maximum number of bytes to return from $stream. If + * @param resource $stream Stream to read from. + * @param int $limit Maximum number of bytes to return from $stream. If * additional bytes are available, they will be read and * discarded. - * @param string Human-readable description of stream, for exception - * message. - * @param int Maximum number of bytes to read. + * @param string $description Human-readable description of stream, for + * exception message. + * @param int $length Maximum number of bytes to read. * @return string The data read from the stream. * @task internal */ diff --git a/src/future/exec/PhutilExecutableFuture.php b/src/future/exec/PhutilExecutableFuture.php index 13e6977d..b4c490b9 100644 --- a/src/future/exec/PhutilExecutableFuture.php +++ b/src/future/exec/PhutilExecutableFuture.php @@ -60,8 +60,9 @@ abstract class PhutilExecutableFuture extends Future { * // Env will have ONLY "X". * $exec->setEnv(array('X' => 'y'), $wipe_process_env = true); * - * @param map Dictionary of environmental variables. - * @param bool Optionally, pass `true` to replace the existing environment. + * @param map $env Dictionary of environmental variables. + * @param bool $wipe_process_env (optional) Pass `true` to replace the + * existing environment. * @return this * * @task config @@ -86,8 +87,8 @@ abstract class PhutilExecutableFuture extends Future { /** * Set the value of a specific environmental variable for this command. * - * @param string Environmental variable name. - * @param string|null New value, or null to remove this variable. + * @param string $key Environmental variable name. + * @param string|null $value New value, or null to remove this variable. * @return this * @task config */ @@ -159,7 +160,7 @@ abstract class PhutilExecutableFuture extends Future { * the subprocess will execute). If not set, the default value is the parent's * current working directory. * - * @param string Directory to execute the subprocess in. + * @param string $cwd Directory to execute the subprocess in. * @return this * @task config */ diff --git a/src/future/exec/execx.php b/src/future/exec/execx.php index ee920aff..5c10f289 100644 --- a/src/future/exec/execx.php +++ b/src/future/exec/execx.php @@ -7,7 +7,7 @@ * * list ($stdout, $stderr) = execx('ls %s', $file); * - * @param string sprintf()-style command pattern to execute. + * @param string $cmd sprintf()-style command pattern to execute. * @param ... Arguments to sprintf pattern. * @return array List of stdout and stderr. */ @@ -27,7 +27,7 @@ function execx($cmd /* , ... */) { * Error flows can often be simplified by using @{function:execx} instead, * which throws an exception when it encounters an error. * - * @param string sprintf()-style command pattern to execute. + * @param string $cmd sprintf()-style command pattern to execute. * @param ... Arguments to sprintf pattern. * @return array List of return code, stdout, and stderr. */ @@ -41,7 +41,7 @@ function exec_manual($cmd /* , ... */) { /** * Wrapper for @{class:PhutilExecPassthru}. * - * @param string sprintf()-style command pattern to execute. + * @param string $cmd sprintf()-style command pattern to execute. * @param ... Arguments to sprintf pattern. * @return int Return code. */ @@ -55,7 +55,7 @@ function phutil_passthru($cmd /* , ... */) { * Return a human-readable signal name (like "SIGINT" or "SIGKILL") for a given * signal number. * - * @param int Signal number. + * @param int $signo Signal number. * @return string Human-readable signal name. */ function phutil_get_signal_name($signo) { diff --git a/src/future/http/BaseHTTPFuture.php b/src/future/http/BaseHTTPFuture.php index 1def346b..a9c6bf93 100644 --- a/src/future/http/BaseHTTPFuture.php +++ b/src/future/http/BaseHTTPFuture.php @@ -37,10 +37,10 @@ abstract class BaseHTTPFuture extends Future { * instantiate it; instead, build a new @{class:HTTPFuture} or * @{class:HTTPSFuture}. * - * @param string Fully-qualified URI to send a request to. - * @param mixed String or array to include in the request. Strings will be - * transmitted raw; arrays will be encoded and sent as - * 'application/x-www-form-urlencoded'. + * @param string $uri Fully-qualified URI to send a request to. + * @param mixed $data (optional) String or array to include in the request. + * Strings will be transmitted raw; arrays will be encoded and + * sent as 'application/x-www-form-urlencoded'. * @task create */ final public function __construct($uri, $data = array()) { @@ -58,7 +58,7 @@ abstract class BaseHTTPFuture extends Future { * out. You can determine if a status is a timeout status by calling * isTimeout() on the status object. * - * @param float Maximum timeout, in seconds. + * @param float $timeout Maximum timeout, in seconds. * @return this * @task config */ @@ -83,7 +83,7 @@ abstract class BaseHTTPFuture extends Future { * Select the HTTP method (e.g., "GET", "POST", "PUT") to use for the request. * By default, requests use "GET". * - * @param string HTTP method name. + * @param string $method HTTP method name. * @return this * @task config */ @@ -124,7 +124,7 @@ abstract class BaseHTTPFuture extends Future { * Set the URI to send the request to. Note that this is also a constructor * parameter. * - * @param string URI to send the request to. + * @param string $uri URI to send the request to. * @return this * @task config */ @@ -151,7 +151,7 @@ abstract class BaseHTTPFuture extends Future { * must be a string (in which case it will be sent raw) or an array (in which * case it will be encoded and sent as 'application/x-www-form-urlencoded'). * - * @param mixed Data to send with the request. + * @param mixed $data Data to send with the request. * @return this * @task config */ @@ -179,8 +179,8 @@ abstract class BaseHTTPFuture extends Future { * Add an HTTP header to the request. The same header name can be specified * more than once, which will cause multiple headers to be sent. * - * @param string Header name, like "Accept-Language". - * @param string Header value, like "en-us". + * @param string $name Header name, like "Accept-Language". + * @param string $value Header value, like "en-us". * @return this * @task config */ @@ -200,8 +200,8 @@ abstract class BaseHTTPFuture extends Future { * * In either case, an array with all (or all matching) headers is returned. * - * @param string|null Optional filter, which selects only headers with that - * name if provided. + * @param string|null $filter (optional) Filter, which selects only headers + * with that name if provided. * @return array List of all (or all matching) headers. * @task config */ @@ -228,7 +228,7 @@ abstract class BaseHTTPFuture extends Future { * HTTP status code outside the 2xx range (notwithstanding other errors such * as connection or transport issues). * - * @param array|null List of expected HTTP status codes. + * @param array|null $status_codes List of expected HTTP status codes. * * @return this * @task config @@ -251,8 +251,8 @@ abstract class BaseHTTPFuture extends Future { /** * Add a HTTP basic authentication header to the request. * - * @param string Username to authenticate with. - * @param PhutilOpaqueEnvelope Password to authenticate with. + * @param string $username Username to authenticate with. + * @param PhutilOpaqueEnvelope $password Password to authenticate with. * @return this * @task config */ @@ -316,7 +316,7 @@ abstract class BaseHTTPFuture extends Future { /** * Parse a raw HTTP response into a tuple. * - * @param string Raw HTTP response. + * @param string $raw_response Raw HTTP response. * @return tuple Valid resolution tuple. * @task internal */ @@ -393,7 +393,7 @@ abstract class BaseHTTPFuture extends Future { /** * Parse an HTTP header block. * - * @param string Raw HTTP headers. + * @param string $head_raw Raw HTTP headers. * @return list List of HTTP header tuples. * @task internal */ @@ -423,8 +423,8 @@ abstract class BaseHTTPFuture extends Future { /** * Find value of the first header with given name. * - * @param list List of headers from `resolve()`. - * @param string Case insensitive header name. + * @param list $headers List of headers from `resolve()`. + * @param string $search Case insensitive header name. * @return string Value of the header or null if not found. * @task resolve */ diff --git a/src/future/http/HTTPSFuture.php b/src/future/http/HTTPSFuture.php index 48824fb1..22f78ea5 100644 --- a/src/future/http/HTTPSFuture.php +++ b/src/future/http/HTTPSFuture.php @@ -39,7 +39,8 @@ final class HTTPSFuture extends BaseHTTPFuture { * cURL needs this to be a file, it doesn't seem to be able to handle a string * which contains the cert. So we make a temporary file and store it there. * - * @param string The multi-line, possibly lengthy, SSL certificate to use. + * @param string $certificate The multi-line, possibly lengthy, SSL + * certificate to use. * @return this */ public function setCABundleFromString($certificate) { @@ -52,7 +53,7 @@ final class HTTPSFuture extends BaseHTTPFuture { /** * Set the SSL certificate to use for this session, given a path. * - * @param string The path to a valid SSL certificate for this session + * @param string $path The path to a valid SSL certificate for this session * @return this */ public function setCABundleFromPath($path) { @@ -73,8 +74,8 @@ final class HTTPSFuture extends BaseHTTPFuture { * Set whether Location headers in the response will be respected. * The default is true. * - * @param boolean true to follow any Location header present in the response, - * false to return the request directly + * @param boolean $follow true to follow any Location header present in the + * response, false to return the request directly * @return this */ public function setFollowLocation($follow) { @@ -95,7 +96,7 @@ final class HTTPSFuture extends BaseHTTPFuture { * Set the fallback CA certificate if one is not specified * for the session, given a path. * - * @param string The path to a valid SSL certificate + * @param string $path The path to a valid SSL certificate * @return void */ public static function setGlobalCABundleFromPath($path) { @@ -105,7 +106,7 @@ final class HTTPSFuture extends BaseHTTPFuture { * Set the fallback CA certificate if one is not specified * for the session, given a string. * - * @param string The certificate + * @param string $certificate The certificate * @return void */ public static function setGlobalCABundleFromString($certificate) { @@ -127,8 +128,8 @@ final class HTTPSFuture extends BaseHTTPFuture { * Load contents of remote URI. Behaves pretty much like * `@file_get_contents($uri)` but doesn't require `allow_url_fopen`. * - * @param string - * @param float + * @param string $uri + * @param float $timeout (optional) * @return string|false */ public static function loadContent($uri, $timeout = null) { @@ -186,10 +187,10 @@ final class HTTPSFuture extends BaseHTTPFuture { /** * Attach a file to the request. * - * @param string HTTP parameter name. - * @param string File content. - * @param string File name. - * @param string File mime type. + * @param string $key HTTP parameter name. + * @param string $data File content. + * @param string $name File name. + * @param string $mime_type File mime type. * @return this */ public function attachFileData($key, $data, $name, $mime_type) { @@ -770,8 +771,9 @@ final class HTTPSFuture extends BaseHTTPFuture { /** * Detect strings which will cause cURL to do horrible, insecure things. * - * @param string Possibly dangerous string. - * @param bool True if this string is being used as part of a query string. + * @param string $string Possibly dangerous string. + * @param bool $is_query_string True if this string is being used as part + * of a query string. * @return void */ private function checkForDangerousCURLMagic($string, $is_query_string) { @@ -828,7 +830,7 @@ final class HTTPSFuture extends BaseHTTPFuture { * * You must write the entire body before starting the request. * - * @param string Raw body. + * @param string $raw_body Raw body. * @return this */ public function write($raw_body) { diff --git a/src/hgdaemon/ArcanistHgClientChannel.php b/src/hgdaemon/ArcanistHgClientChannel.php index 82ce3002..f1559e17 100644 --- a/src/hgdaemon/ArcanistHgClientChannel.php +++ b/src/hgdaemon/ArcanistHgClientChannel.php @@ -50,7 +50,7 @@ final class ArcanistHgClientChannel extends PhutilProtocolChannel { * For a detailed description of the cmdserver protocol, see * @{class:ArcanistHgServerChannel}. * - * @param pair The pair to encode. + * @param pair $argv The pair to encode. * @return string Encoded string for transmission to the client. * * @task protocol @@ -88,7 +88,7 @@ final class ArcanistHgClientChannel extends PhutilProtocolChannel { * '5', * ); * - * @param string Bytes from the server. + * @param string $data Bytes from the server. * @return list> Zero or more complete commands. * * @task protocol diff --git a/src/hgdaemon/ArcanistHgProxyClient.php b/src/hgdaemon/ArcanistHgProxyClient.php index 6aa00e74..af9d8db9 100644 --- a/src/hgdaemon/ArcanistHgProxyClient.php +++ b/src/hgdaemon/ArcanistHgProxyClient.php @@ -41,7 +41,7 @@ final class ArcanistHgProxyClient extends Phobject { * Build a new client. This client is bound to a working copy. A server * must already be running on this working copy for the client to work. * - * @param string Path to a Mercurial working copy. + * @param string $working_copy Path to a Mercurial working copy. * * @task construct */ @@ -56,7 +56,7 @@ final class ArcanistHgProxyClient extends Phobject { /** * When connecting, do not expect the "capabilities" message. * - * @param bool True to skip the "capabilities" message. + * @param bool $skip True to skip the "capabilities" message. * @return this * * @task config @@ -73,7 +73,8 @@ final class ArcanistHgProxyClient extends Phobject { /** * Execute a command (given as a list of arguments) via the command server. * - * @param list A list of command arguments, like "log", "-l", "5". + * @param list $argv A list of command arguments, like "log", "-l", + * "5". * @return tuple Return code, stdout and stderr. * * @task exec diff --git a/src/hgdaemon/ArcanistHgProxyServer.php b/src/hgdaemon/ArcanistHgProxyServer.php index d0d40a9b..b39a15bc 100644 --- a/src/hgdaemon/ArcanistHgProxyServer.php +++ b/src/hgdaemon/ArcanistHgProxyServer.php @@ -52,7 +52,7 @@ final class ArcanistHgProxyServer extends Phobject { * Build a new server. This server is bound to a working copy. The server * is inactive until you @{method:start} it. * - * @param string Path to a Mercurial working copy. + * @param string $working_copy Path to a Mercurial working copy. * * @task construct */ @@ -67,7 +67,7 @@ final class ArcanistHgProxyServer extends Phobject { /** * Disable status messages to stdout. Controlled with `--quiet`. * - * @param bool True to disable status messages. + * @param bool $quiet True to disable status messages. * @return this * * @task config @@ -85,7 +85,7 @@ final class ArcanistHgProxyServer extends Phobject { * You can use `--client-limit 1` with `--xprofile` and `--do-not-daemonize` * to profile the server. * - * @param int Client limit, or 0 to disable limit. + * @param int $limit Client limit, or 0 to disable limit. * @return this * * @task config @@ -100,7 +100,7 @@ final class ArcanistHgProxyServer extends Phobject { * Configure an idle time limit. After this many seconds idle, the server * will exit. Controlled with `--idle-limit`. * - * @param int Idle limit, or 0 to disable limit. + * @param int $limit Idle limit, or 0 to disable limit. * @return this * * @task config @@ -117,7 +117,7 @@ final class ArcanistHgProxyServer extends Phobject { * if the clients are also configured not to expect the message, but slightly * improves performance. Controlled with --skip-hello. * - * @param bool True to skip the "capabilities" message. + * @param bool $skip True to skip the "capabilities" message. * @return this * * @task config @@ -132,7 +132,7 @@ final class ArcanistHgProxyServer extends Phobject { * Configure whether the server runs in the foreground or daemonizes. * Controlled by --do-not-daemonize. Primarily useful for debugging. * - * @param bool True to run in the foreground. + * @param bool $do_not_daemonize True to run in the foreground. * @return this * * @task config @@ -252,8 +252,8 @@ final class ArcanistHgProxyServer extends Phobject { * process all commands we've received here before returning to the main * server loop. * - * @param ArcanistHgClientChannel The client to update. - * @param ArcanistHgServerChannel The Mercurial server. + * @param ArcanistHgClientChannel $client The client to update. + * @param ArcanistHgServerChannel $hg The Mercurial server. * * @task server */ diff --git a/src/hgdaemon/ArcanistHgServerChannel.php b/src/hgdaemon/ArcanistHgServerChannel.php index 22f6b4ab..ccf68834 100644 --- a/src/hgdaemon/ArcanistHgServerChannel.php +++ b/src/hgdaemon/ArcanistHgServerChannel.php @@ -80,7 +80,7 @@ final class ArcanistHgServerChannel extends PhutilProtocolChannel { * -l\0 * 5 * - * @param list List of command arguments. + * @param list $argv List of command arguments. * @return string Encoded string for transmission to the server. * * @task protocol @@ -116,7 +116,7 @@ final class ArcanistHgServerChannel extends PhutilProtocolChannel { * * array('o', ''); * - * @param string Bytes from the server. + * @param string $data Bytes from the server. * @return list> Zero or more complete messages. * * @task protocol diff --git a/src/init/lib/PhutilLibraryConflictException.php b/src/init/lib/PhutilLibraryConflictException.php index 4a9440ed..f7ca4bf6 100644 --- a/src/init/lib/PhutilLibraryConflictException.php +++ b/src/init/lib/PhutilLibraryConflictException.php @@ -30,10 +30,10 @@ final class PhutilLibraryConflictException extends Exception { /** * Create a new library conflict exception. * - * @param string The name of the library which conflicts with an existing - * library. - * @param string The path of the already-loaded library. - * @param string The path of the attempting-to-load library. + * @param string $library The name of the library which conflicts with an + * existing library. + * @param string $old_path The path of the already-loaded library. + * @param string $new_path The path of the attempting-to-load library. * * @task construct */ diff --git a/src/internationalization/PhutilLocale.php b/src/internationalization/PhutilLocale.php index 5ed03a92..402d0970 100644 --- a/src/internationalization/PhutilLocale.php +++ b/src/internationalization/PhutilLocale.php @@ -45,8 +45,8 @@ abstract class PhutilLocale extends Phobject { * Select a gender variant for this locale. By default, locales use a simple * rule with two gender variants, listed in "" order. * - * @param const `PhutilPerson` gender constant. - * @param list List of variants. + * @param const $variant `PhutilPerson` gender constant. + * @param list $translations List of variants. * @return string Variant for use. */ public function selectGenderVariant($variant, array $translations) { @@ -62,8 +62,8 @@ abstract class PhutilLocale extends Phobject { * Select a plural variant for this locale. By default, locales use a simple * rule with two plural variants, listed in "" order. * - * @param int Plurality of the value. - * @param list List of variants. + * @param int $variant Plurality of the value. + * @param list $translations List of variants. * @return string Variant for use. */ public function selectPluralVariant($variant, array $translations) { @@ -121,10 +121,10 @@ abstract class PhutilLocale extends Phobject { * from @{method:shouldPostProcessTranslations}. Activating this callback * incurs a performance penalty. * - * @param string The raw input pattern. - * @param string The selected translation pattern. - * @param list The raw input arguments. - * @param string The translated string. + * @param string $raw_pattern The raw input pattern. + * @param string $translated_pattern The selected translation pattern. + * @param list $args The raw input arguments. + * @param string $result_text The translated string. * @return string Post-processed translation string. */ public function didTranslateString( @@ -195,7 +195,7 @@ abstract class PhutilLocale extends Phobject { /** * Load a specific locale using a locale code. * - * @param string Locale code. + * @param string $locale_code Locale code. * @return PhutilLocale Locale object. */ public static function loadLocale($locale_code) { @@ -216,9 +216,9 @@ abstract class PhutilLocale extends Phobject { /** * Recursively check locale fallbacks for cycles. * - * @param map Map of locales. - * @param PhutilLocale Current locale. - * @param map Map of visited locales. + * @param map $map Map of locales. + * @param PhutilLocale $locale Current locale. + * @param map $seen Map of visited locales. * @return void */ private static function checkLocaleFallback( diff --git a/src/internationalization/PhutilTranslation.php b/src/internationalization/PhutilTranslation.php index 7acac136..7b44b497 100644 --- a/src/internationalization/PhutilTranslation.php +++ b/src/internationalization/PhutilTranslation.php @@ -59,7 +59,7 @@ abstract class PhutilTranslation extends Phobject { * This will compile primary and fallback translations into a single * translation map. * - * @param string Locale code, like "en_US". + * @param string $locale_code Locale code, like "en_US". * @return map Map of all avialable translations. */ public static function getTranslationMapForLocale($locale_code) { diff --git a/src/internationalization/PhutilTranslator.php b/src/internationalization/PhutilTranslator.php index c2b0984a..46ba0dc9 100644 --- a/src/internationalization/PhutilTranslator.php +++ b/src/internationalization/PhutilTranslator.php @@ -64,7 +64,7 @@ final class PhutilTranslator extends Phobject { * '%s owns %s.' => '%2$s is owned by %1$s.', * ); * - * @param array Identifier in key, translation in value. + * @param array $translations Identifier in key, translation in value. * @return PhutilTranslator Provides fluent interface. */ public function setTranslations(array $translations) { @@ -212,8 +212,8 @@ final class PhutilTranslator extends Phobject { /** * Translate date formatted by `$date->format()`. * - * @param string Format accepted by `DateTime::format()`. - * @param DateTime + * @param string $format Format accepted by `DateTime::format()`. + * @param DateTime $date * @return string Formatted and translated date. */ public function translateDate($format, DateTime $date) { @@ -243,8 +243,8 @@ final class PhutilTranslator extends Phobject { * translations of '.' (decimal point) and ',' (thousands separator). Both * these translations must be 1 byte long with PHP < 5.4.0. * - * @param float - * @param int + * @param float $number + * @param int $decimals (optional) * @return string */ public function formatNumber($number, $decimals = 0) { diff --git a/src/internationalization/pht.php b/src/internationalization/pht.php index 1d9a2f7b..5062fafc 100644 --- a/src/internationalization/pht.php +++ b/src/internationalization/pht.php @@ -6,8 +6,9 @@ * `PhutilTranslator::getInstance()->setTranslations()` and language rules set * by `PhutilTranslator::getInstance()->setLocale()`. * - * @param string Translation identifier with `sprintf()` placeholders. - * @param mixed Value to select the variant from (e.g. singular or plural). + * @param string $text Translation identifier with `sprintf()` placeholders. + * @param mixed $variant (optional) Value to select the variant from (e.g. + * singular or plural). Defaults to null. * @param ... Next values referenced from $text. * @return string Translated string with substituted values. */ @@ -20,7 +21,7 @@ function pht($text, $variant = null /* , ... */) { /** * Count all elements in an array, or something in an object. * - * @param array|Countable A countable object. + * @param array|Countable $countable A countable object. * @return PhutilNumber Returns the number of elements in the input * parameter. */ @@ -38,7 +39,8 @@ function phutil_count($countable) { * This function does nothing and only serves as a marker for the static * extractor so it knows particular arguments may vary on gender. * - * @param PhutilPerson Something implementing @{interface:PhutilPerson}. + * @param PhutilPerson $person Something implementing + * @{interface:PhutilPerson}. * @return PhutilPerson The argument, unmodified. */ function phutil_person(PhutilPerson $person) { diff --git a/src/land/engine/ArcanistLandEngine.php b/src/land/engine/ArcanistLandEngine.php index 692946eb..9c2573ba 100644 --- a/src/land/engine/ArcanistLandEngine.php +++ b/src/land/engine/ArcanistLandEngine.php @@ -1420,7 +1420,8 @@ abstract class ArcanistLandEngine * and min is the earliest ancestor. This is done so that non-landing commits * that are descendants of the latest revision will only be rebased once. * - * @param ArcanistLandCommitSet The current commit set to cascade. + * @param ArcanistLandCommitSet $set The current commit set to cascade. + * @param string $into_commit The commit hash that was landed into. */ abstract protected function cascadeState( ArcanistLandCommitSet $set, @@ -1434,7 +1435,7 @@ abstract class ArcanistLandEngine * Prunes the given sets of commits. This should be called after the sets * have been merged. * - * @param array The list of ArcanistLandCommitSet to prune, in order of + * @param array $sets The list of ArcanistLandCommitSet to prune, in order of * min to max commit set, where min is the earliest ancestor and max * is the latest descendant. */ @@ -1445,9 +1446,10 @@ abstract class ArcanistLandEngine * should only be called after all changes have been merged, pruned, and * pushed. * - * @param string The commit hash that was landed into. - * @param ArcanistRepositoryLocalState The local state that was captured - * at the beginning of the land process. This may include stashed changes. + * @param string $into_commit The commit hash that was landed into. + * @param ArcanistRepositoryLocalState $state The local state that was + * captured at the beginning of the land process. This may include stashed + * changes. */ abstract protected function reconcileLocalState( $into_commit, @@ -1457,7 +1459,7 @@ abstract class ArcanistLandEngine * Display information to the user about how to proceed since the land * process was not fully completed. The merged branch has not been pushed. * - * @param string The commit hash that was landed into. + * @param string $into_commit The commit hash that was landed into. */ abstract protected function didHoldChanges($into_commit); diff --git a/src/lexer/PhutilLexer.php b/src/lexer/PhutilLexer.php index 36cc897c..ce461255 100644 --- a/src/lexer/PhutilLexer.php +++ b/src/lexer/PhutilLexer.php @@ -233,8 +233,8 @@ abstract class PhutilLexer extends Phobject { /** * Lex an input string into tokens. * - * @param string Input string. - * @param string Initial lexer state. + * @param string $input Input string. + * @param string $initial_state (optional) Initial lexer state. * @return list List of lexer tokens. * @task tokens */ diff --git a/src/lexer/PhutilShellLexer.php b/src/lexer/PhutilShellLexer.php index d4e8c523..ac17a60a 100644 --- a/src/lexer/PhutilShellLexer.php +++ b/src/lexer/PhutilShellLexer.php @@ -21,7 +21,7 @@ final class PhutilShellLexer extends PhutilLexer { * "\"", * ); * - * @param string Shell command string. + * @param string $string Shell command string. * @return array Parsed argument vector. */ public function splitArguments($string) { diff --git a/src/lint/ArcanistLintMessage.php b/src/lint/ArcanistLintMessage.php index cc9e58fb..749620e5 100644 --- a/src/lint/ArcanistLintMessage.php +++ b/src/lint/ArcanistLintMessage.php @@ -184,7 +184,7 @@ final class ArcanistLintMessage extends Phobject { } /** - * @param dict Keys 'path', 'line', 'char', 'original'. + * @param dict $locations Keys 'path', 'line', 'char', 'original'. */ public function setOtherLocations(array $locations) { assert_instances_of($locations, 'array'); @@ -272,7 +272,8 @@ final class ArcanistLintMessage extends Phobject { * less strict in linters themselves, since they often parse command line * output or XML and will end up with string representations of numbers. * - * @param mixed Integer or digit string. + * @param mixed $value Integer or digit string. + * @param mixed $caller * @return int Integer. */ private function validateInteger($value, $caller) { diff --git a/src/lint/engine/ArcanistLintEngine.php b/src/lint/engine/ArcanistLintEngine.php index add11d15..1ea5b84c 100644 --- a/src/lint/engine/ArcanistLintEngine.php +++ b/src/lint/engine/ArcanistLintEngine.php @@ -291,6 +291,7 @@ abstract class ArcanistLintEngine extends Phobject { /** * @param dict>> + * $results * @return this */ final public function setCachedResults(array $results) { @@ -419,9 +420,9 @@ abstract class ArcanistLintEngine extends Phobject { * construction of the result so it doesn't need to be built multiple * times. * - * @param string Resource identifier. - * @param wild Optionally, default value to return if resource does not - * exist. + * @param string $key Resource identifier. + * @param wild $default (optional) Default value to return if resource + * does not exist. * @return wild Resource, or default value if not present. */ public function getLinterResource($key, $default = null) { @@ -434,8 +435,8 @@ abstract class ArcanistLintEngine extends Phobject { * * See @{method:getLinterResource} for a description of this mechanism. * - * @param string Resource identifier. - * @param wild Resource. + * @param string $key Resource identifier. + * @param wild $value Resource. * @return this */ public function setLinterResource($key, $value) { diff --git a/src/lint/linter/ArcanistBaseXHPASTLinter.php b/src/lint/linter/ArcanistBaseXHPASTLinter.php index f0f44827..83a175bd 100644 --- a/src/lint/linter/ArcanistBaseXHPASTLinter.php +++ b/src/lint/linter/ArcanistBaseXHPASTLinter.php @@ -101,7 +101,7 @@ abstract class ArcanistBaseXHPASTLinter extends ArcanistFutureLinter { /** * Build futures on this linter, for use and to share with other linters. * - * @param list Paths to build futures for. + * @param list $paths Paths to build futures for. * @return list Futures. * @task sharing */ @@ -122,7 +122,7 @@ abstract class ArcanistBaseXHPASTLinter extends ArcanistFutureLinter { /** * Release futures on this linter which are no longer in use elsewhere. * - * @param list Paths to release futures for. + * @param list $paths Paths to release futures for. * @return void * @task sharing */ @@ -152,7 +152,7 @@ abstract class ArcanistBaseXHPASTLinter extends ArcanistFutureLinter { /** * Get a path's tree from the responsible linter. * - * @param string Path to retrieve tree for. + * @param string $path Path to retrieve tree for. * @return XHPASTTree|null Tree, or null if unparseable. * @task sharing */ @@ -188,7 +188,7 @@ abstract class ArcanistBaseXHPASTLinter extends ArcanistFutureLinter { /** * Get a path's parse exception from the responsible linter. * - * @param string Path to retrieve exception for. + * @param string $path Path to retrieve exception for. * @return Exception|null Parse exception, if available. * @task sharing */ @@ -209,8 +209,8 @@ abstract class ArcanistBaseXHPASTLinter extends ArcanistFutureLinter { * Returns all descendant nodes which represent a function call to one of the * specified functions. * - * @param XHPASTNode Root node. - * @param list Function names. + * @param XHPASTNode $root Root node. + * @param list $function_names Function names. * @return AASTNodeList */ protected function getFunctionCalls(XHPASTNode $root, array $function_names) { diff --git a/src/lint/linter/ArcanistChmodLinter.php b/src/lint/linter/ArcanistChmodLinter.php index a8825e72..ceff264b 100644 --- a/src/lint/linter/ArcanistChmodLinter.php +++ b/src/lint/linter/ArcanistChmodLinter.php @@ -117,7 +117,7 @@ final class ArcanistChmodLinter extends ArcanistLinter { /** * Returns the path's shebang. * - * @param string + * @param string $path * @return string|null */ private function getShebang($path) { diff --git a/src/lint/linter/ArcanistExternalLinter.php b/src/lint/linter/ArcanistExternalLinter.php index 8c35e440..24e1c09f 100644 --- a/src/lint/linter/ArcanistExternalLinter.php +++ b/src/lint/linter/ArcanistExternalLinter.php @@ -104,7 +104,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter { * Override default flags with custom flags. If not overridden, flags provided * by @{method:getDefaultFlags} are used. * - * @param list New flags. + * @param list $flags New flags. * @return this * @task bin */ @@ -116,7 +116,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter { /** * Set the binary's version requirement. * - * @param string Version requirement. + * @param string $version Version requirement. * @return this * @task bin */ @@ -151,7 +151,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter { /** * Override the default binary with a new one. * - * @param string New binary. + * @param string $bin New binary. * @return this * @task bin */ @@ -200,7 +200,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter { /** * Set the interpreter, overriding any default. * - * @param string New interpreter. + * @param string $interpreter New interpreter. * @return this * @task bin */ @@ -223,10 +223,10 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter { * you're able to detect a more specific condition.) Otherwise, return a list * of messages. * - * @param string Path to the file being linted. - * @param int Exit code of the linter. - * @param string Stdout of the linter. - * @param string Stderr of the linter. + * @param string $path Path to the file being linted. + * @param int $err Exit code of the linter. + * @param string $stdout Stdout of the linter. + * @param string $stderr Stderr of the linter. * @return list|false List of lint messages, or false * to indicate parser failure. * @task parse @@ -298,7 +298,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter { * of the configured binary to the required version, and if the binary's * version is not supported, throw an exception. * - * @param string Version string to check. + * @param string $version Version string to check. * @return void */ final protected function checkBinaryVersion($version) { @@ -415,7 +415,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter { * * This method is expected to return an already escaped string. * - * @param string Path to the file being linted + * @param string $path Path to the file being linted * @return string The command-ready file argument */ protected function getPathArgumentForLinterFuture($path) { @@ -572,7 +572,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter { * * If the code is not recognized, you should throw an exception. * - * @param string Code specified in configuration. + * @param string $code Code specified in configuration. * @return string Normalized code to use in severity map. */ protected function getLintCodeFromLinterConfigurationKey($code) { diff --git a/src/lint/linter/ArcanistFutureLinter.php b/src/lint/linter/ArcanistFutureLinter.php index 7fad5a55..d5daf196 100644 --- a/src/lint/linter/ArcanistFutureLinter.php +++ b/src/lint/linter/ArcanistFutureLinter.php @@ -47,7 +47,7 @@ abstract class ArcanistFutureLinter extends ArcanistLinter { * This is invoked after a block of futures resolve, and allows linters to * discard or clean up any shared resources they no longer need. * - * @param map Map of paths to resolved futures. + * @param map $futures Map of paths to resolved futures. * @return void */ protected function didResolveLinterFutures(array $futures) { diff --git a/src/lint/linter/ArcanistLinter.php b/src/lint/linter/ArcanistLinter.php index 85a94453..4fc50861 100644 --- a/src/lint/linter/ArcanistLinter.php +++ b/src/lint/linter/ArcanistLinter.php @@ -131,7 +131,7 @@ abstract class ArcanistLinter extends Phobject { * * This ID is assigned automatically by the @{class:ArcanistLintEngine}. * - * @param string Unique linter ID. + * @param string $id Unique linter ID. * @return this * @task state */ @@ -168,7 +168,7 @@ abstract class ArcanistLinter extends Phobject { * Linters which are not parallelizable should normally ignore this callback * and implement @{method:lintPath} instead. * - * @param list A list of paths to be linted + * @param list $paths A list of paths to be linted * @return void * @task exec */ @@ -185,7 +185,7 @@ abstract class ArcanistLinter extends Phobject { * Linters which are parallelizable may want to ignore this callback and * implement @{method:willLintPaths} and @{method:didLintPaths} instead. * - * @param string Path to lint. + * @param string $path Path to lint. * @return void * @task exec */ @@ -202,7 +202,7 @@ abstract class ArcanistLinter extends Phobject { * Linters which are not paralleizable should normally ignore this callback * and implement @{method:lintPath} instead. * - * @param list A list of paths which were linted. + * @param list $paths A list of paths which were linted. * @return void * @task exec */ @@ -288,7 +288,7 @@ abstract class ArcanistLinter extends Phobject { * Filter out paths which this linter doesn't act on (for example, because * they are binaries and the linter doesn't apply to binaries). * - * @param list + * @param list $paths * @return list */ private function filterPaths(array $paths) { @@ -617,7 +617,7 @@ abstract class ArcanistLinter extends Phobject { * * If the code is not recognized, you should throw an exception. * - * @param string Code specified in configuration. + * @param string $code Code specified in configuration. * @return string Normalized code to use in severity map. */ protected function getLintCodeFromLinterConfigurationKey($code) { diff --git a/src/lint/linter/ArcanistScriptAndRegexLinter.php b/src/lint/linter/ArcanistScriptAndRegexLinter.php index 62000c31..7071fc4a 100644 --- a/src/lint/linter/ArcanistScriptAndRegexLinter.php +++ b/src/lint/linter/ArcanistScriptAndRegexLinter.php @@ -324,7 +324,8 @@ final class ArcanistScriptAndRegexLinter extends ArcanistLinter { /** * Get the line and character of the message from the regex match. * - * @param dict Captured groups from regex. + * @param dict $match Captured groups from regex. + * @param string $path * @return pair Line and character of the message. * * @task parse @@ -362,7 +363,7 @@ final class ArcanistScriptAndRegexLinter extends ArcanistLinter { * a nonempty severity name group like 'error', or a group called 'severity' * with a valid name. * - * @param dict Captured groups from regex. + * @param dict $match Captured groups from regex. * @return const @{class:ArcanistLintSeverity} constant. * * @task parse diff --git a/src/lint/linter/ArcanistXHPASTLinter.php b/src/lint/linter/ArcanistXHPASTLinter.php index 636d8569..d5194319 100644 --- a/src/lint/linter/ArcanistXHPASTLinter.php +++ b/src/lint/linter/ArcanistXHPASTLinter.php @@ -29,7 +29,7 @@ final class ArcanistXHPASTLinter extends ArcanistBaseXHPASTLinter { * This is primarily useful for unit tests in which it is desirable to test * linter rules in isolation. By default, all linter rules will be enabled. * - * @param list + * @param list $rules * @return this */ public function setRules(array $rules) { diff --git a/src/lint/linter/__tests__/ArcanistLinterTestCase.php b/src/lint/linter/__tests__/ArcanistLinterTestCase.php index 19d9ce10..75760fbb 100644 --- a/src/lint/linter/__tests__/ArcanistLinterTestCase.php +++ b/src/lint/linter/__tests__/ArcanistLinterTestCase.php @@ -305,8 +305,8 @@ abstract class ArcanistLinterTestCase extends PhutilTestCase { /** * Compare properties of @{class:ArcanistLintMessage} instances. * - * @param wild - * @param wild + * @param wild $x + * @param wild $y * @return bool */ private static function compareLintMessageProperty($x, $y) { diff --git a/src/lint/linter/standards/ArcanistLinterStandard.php b/src/lint/linter/standards/ArcanistLinterStandard.php index 77b0ec79..bed4a1ec 100644 --- a/src/lint/linter/standards/ArcanistLinterStandard.php +++ b/src/lint/linter/standards/ArcanistLinterStandard.php @@ -35,7 +35,7 @@ abstract class ArcanistLinterStandard extends Phobject { /** * Checks whether the linter standard supports a specified linter. * - * @param ArcanistLinter The linter which is being configured. + * @param ArcanistLinter $linter The linter which is being configured. * @return bool True if the linter standard supports the specified * linter, otherwise false. */ @@ -68,8 +68,8 @@ abstract class ArcanistLinterStandard extends Phobject { /** * Load a linter standard by key. * - * @param string - * @param ArcanistLinter + * @param string $key + * @param ArcanistLinter $linter * @return ArcanistLinterStandard */ final public static function getStandard($key, ArcanistLinter $linter) { @@ -100,7 +100,7 @@ abstract class ArcanistLinterStandard extends Phobject { /** * Load all linter standards which support a specified linter. * - * @param ArcanistLinter + * @param ArcanistLinter $linter * @return list */ final public static function loadAllStandardsForLinter( diff --git a/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php b/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php index a7d9ab18..24ccb577 100644 --- a/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php +++ b/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php @@ -45,12 +45,13 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject { * } * return $default; * - * @param string The symbol type. - * @param string The symbol name. - * @param string|null The default result from the main rule engine. + * @param string $type The symbol type. + * @param string $name The symbol name. + * @param string|null $default The default result from the main rule + * engine. * @return string|null Null to accept the name, or a message to reject it - * with. You should return the default value if you don't - * want to specifically provide an override. + * with. You should return the default value if you + * don't want to specifically provide an override. * @task override */ abstract public function lintSymbolName($type, $name, $default); @@ -61,7 +62,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject { /** * Returns true if a symbol name is UpperCamelCase. * - * @param string Symbol name. + * @param string $symbol Symbol name. * @return bool True if the symbol is UpperCamelCase. * @task util */ @@ -72,7 +73,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject { /** * Returns true if a symbol name is lowerCamelCase. * - * @param string Symbol name. + * @param string $symbol Symbol name. * @return bool True if the symbol is lowerCamelCase. * @task util */ @@ -83,7 +84,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject { /** * Returns true if a symbol name is UPPERCASE_WITH_UNDERSCORES. * - * @param string Symbol name. + * @param string $symbol Symbol name. * @return bool True if the symbol is UPPERCASE_WITH_UNDERSCORES. * @task util */ @@ -94,7 +95,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject { /** * Returns true if a symbol name is lowercase_with_underscores. * - * @param string Symbol name. + * @param string $symbol Symbol name. * @return bool True if the symbol is lowercase_with_underscores. * @task util */ @@ -107,7 +108,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject { * the "__" magic-method signifier, to make a symbol appropriate for testing * with methods like @{method:isLowerCamelCase}. * - * @param string Symbol name. + * @param string $symbol Symbol name. * @return string Stripped symbol. * @task util */ @@ -142,7 +143,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject { * the "$", to make a symbol appropriate for testing with methods like * @{method:isLowercaseWithUnderscores}. * - * @param string Symbol name. + * @param string $symbol Symbol name. * @return string Stripped symbol. * @task util */ diff --git a/src/lint/linter/xhpast/ArcanistXHPASTLinterRule.php b/src/lint/linter/xhpast/ArcanistXHPASTLinterRule.php index d6828e28..014f30cd 100644 --- a/src/lint/linter/xhpast/ArcanistXHPASTLinterRule.php +++ b/src/lint/linter/xhpast/ArcanistXHPASTLinterRule.php @@ -144,7 +144,7 @@ abstract class ArcanistXHPASTLinterRule extends Phobject { * * TODO: Improve this and move it to XHPAST proper? * - * @param string The "semantic string" of a single value. + * @param string $string The "semantic string" of a single value. * @return mixed `true` or `false` if the value could be evaluated * statically; `null` if static evaluation was not possible. */ @@ -168,7 +168,7 @@ abstract class ArcanistXHPASTLinterRule extends Phobject { * Returns all descendant nodes which represent an anonymous function * declaration. * - * @param XHPASTNode Root node. + * @param XHPASTNode $root Root node. * @return AASTNodeList */ protected function getAnonymousClosures(XHPASTNode $root) { @@ -187,7 +187,7 @@ abstract class ArcanistXHPASTLinterRule extends Phobject { /** * TODO * - * @param XHPASTNode + * @param XHPASTNode $variable * @return string */ protected function getConcreteVariableString(XHPASTNode $variable) { @@ -205,8 +205,8 @@ abstract class ArcanistXHPASTLinterRule extends Phobject { * Returns all descendant nodes which represent a function call to one of the * specified functions. * - * @param XHPASTNode Root node. - * @param list Function names. + * @param XHPASTNode $root Root node. + * @param list $function_names Function names. * @return AASTNodeList */ protected function getFunctionCalls(XHPASTNode $root, array $function_names) { @@ -228,7 +228,7 @@ abstract class ArcanistXHPASTLinterRule extends Phobject { /** * Get class/method modifiers. * - * @param XHPASTNode A node of type `n_CLASS_DECLARATION` or + * @param XHPASTNode $node A node of type `n_CLASS_DECLARATION` or * `n_METHOD_DECLARATION`. * @return map Class/method modifiers. */ diff --git a/src/moduleutils/PhutilLibraryMapBuilder.php b/src/moduleutils/PhutilLibraryMapBuilder.php index 7997bf57..e0f7afab 100644 --- a/src/moduleutils/PhutilLibraryMapBuilder.php +++ b/src/moduleutils/PhutilLibraryMapBuilder.php @@ -29,7 +29,7 @@ final class PhutilLibraryMapBuilder extends Phobject { /** * Create a new map builder for a library. * - * @param string Path to the library root. + * @param string $root Path to the library root. * * @task map */ @@ -40,7 +40,7 @@ final class PhutilLibraryMapBuilder extends Phobject { /** * Control subprocess parallelism limit. Use `--limit` to set this. * - * @param int Maximum number of subprocesses to run in parallel. + * @param int $limit Maximum number of subprocesses to run in parallel. * @return this * * @task map @@ -103,8 +103,8 @@ final class PhutilLibraryMapBuilder extends Phobject { /** * Get the path to some file in the library. * - * @param string A library-relative path. If omitted, returns the library - * root path. + * @param string $path (optional) A library-relative path. If omitted, + * returns the library root path. * @return string An absolute path. * * @task path @@ -188,8 +188,8 @@ final class PhutilLibraryMapBuilder extends Phobject { /** * Write a symbol map to disk cache. * - * @param dict Symbol map of relative paths to symbols. - * @param dict Source map (like @{method:loadSourceFileMap}). + * @param dict $symbol_map Symbol map of relative paths to symbols. + * @param dict $source_map Source map (like @{method:loadSourceFileMap}). * @return void * * @task symbol @@ -224,7 +224,7 @@ final class PhutilLibraryMapBuilder extends Phobject { * Build a future which returns a `extract-symbols.php` analysis of a source * file. * - * @param string Relative path to the source file to analyze. + * @param string $file Relative path to the source file to analyze. * @return Future Analysis future. * * @task symbol @@ -321,7 +321,7 @@ final class PhutilLibraryMapBuilder extends Phobject { * Convert the symbol analysis of all the source files in the library into * a library map. * - * @param dict Symbol analysis of all source files. + * @param dict $symbol_map Symbol analysis of all source files. * @return dict Library map. * @task source */ @@ -381,7 +381,7 @@ final class PhutilLibraryMapBuilder extends Phobject { /** * Write a finalized library map. * - * @param dict Library map structure to write. + * @param dict $library_map Library map structure to write. * @return void * * @task source diff --git a/src/object/Phobject.php b/src/object/Phobject.php index 4d799306..2effc9de 100644 --- a/src/object/Phobject.php +++ b/src/object/Phobject.php @@ -73,8 +73,9 @@ abstract class Phobject implements Iterator { * useful message if the constant is not defined and allows the constant to * be limited to a maximum length. * - * @param string Name of the constant. - * @param int|null Maximum number of bytes permitted in the value. + * @param string $key Name of the constant. + * @param int|null $byte_limit (optional) Maximum number of bytes permitted + * in the value. * @return string Value of the constant. */ public function getPhobjectClassConstant($key, $byte_limit = null) { diff --git a/src/parser/ArcanistDiffParser.php b/src/parser/ArcanistDiffParser.php index f80917ed..1536b74c 100644 --- a/src/parser/ArcanistDiffParser.php +++ b/src/parser/ArcanistDiffParser.php @@ -1329,7 +1329,7 @@ final class ArcanistDiffParser extends Phobject { * return an incorrect value. Such cases are expected to be * recovered by later rename detection codepaths. * - * @param string Text from a diff line after "diff --git ". + * @param string $paths Text from a diff line after "diff --git ". * @return string Filename being altered, or null for a rename. */ public static function extractGitCommonFilename($paths) { diff --git a/src/parser/PhutilEditorConfig.php b/src/parser/PhutilEditorConfig.php index d2bf93a3..05d326ef 100644 --- a/src/parser/PhutilEditorConfig.php +++ b/src/parser/PhutilEditorConfig.php @@ -41,7 +41,7 @@ final class PhutilEditorConfig extends Phobject { /** * Constructor. * - * @param string The root directory. + * @param string $root The root directory. */ public function __construct($root) { $this->root = $root; @@ -50,8 +50,8 @@ final class PhutilEditorConfig extends Phobject { /** * Get the specified EditorConfig property for the specified path. * - * @param string - * @param string + * @param string $path + * @param string $key * @return wild */ public function getProperty($path, $key) { @@ -100,7 +100,7 @@ final class PhutilEditorConfig extends Phobject { * the future). * - Invalid glob patterns will be silently ignored. * - * @param string + * @param string $path * @return map */ public function getProperties($path) { diff --git a/src/parser/PhutilJSON.php b/src/parser/PhutilJSON.php index 5f43a625..dd6c2fb6 100644 --- a/src/parser/PhutilJSON.php +++ b/src/parser/PhutilJSON.php @@ -16,7 +16,7 @@ final class PhutilJSON extends Phobject { * Encode an object in JSON and pretty-print it. This generates a valid JSON * object with human-readable whitespace and indentation. * - * @param dict An object to encode in JSON. + * @param dict $object An object to encode in JSON. * @return string Pretty-printed object representation. */ public function encodeFormatted($object) { @@ -27,7 +27,7 @@ final class PhutilJSON extends Phobject { /** * Encode a list in JSON and pretty-print it, discarding keys. * - * @param list List to encode in JSON. + * @param list $list List to encode in JSON. * @return string Pretty-printed list representation. */ public function encodeAsList(array $list) { @@ -41,8 +41,8 @@ final class PhutilJSON extends Phobject { /** * Pretty-print a JSON object. * - * @param dict Object to format. - * @param int Current depth, for indentation. + * @param dict $object Object to format. + * @param int $depth Current depth, for indentation. * @return string Pretty-printed value. * @task internal */ @@ -84,8 +84,8 @@ final class PhutilJSON extends Phobject { /** * Pretty-print a JSON list. * - * @param list List to format. - * @param int Current depth, for indentation. + * @param list $array List to format. + * @param int $depth Current depth, for indentation. * @return string Pretty-printed value. * @task internal */ @@ -115,8 +115,8 @@ final class PhutilJSON extends Phobject { /** * Pretty-print a JSON value. * - * @param dict Value to format. - * @param int Current depth, for indentation. + * @param dict $value Value to format. + * @param int $depth Current depth, for indentation. * @return string Pretty-printed value. * @task internal */ @@ -146,7 +146,7 @@ final class PhutilJSON extends Phobject { /** * Render a string corresponding to the current indent depth. * - * @param int Current depth. + * @param int $depth Current depth. * @return string Indentation. * @task internal */ diff --git a/src/parser/PhutilLanguageGuesser.php b/src/parser/PhutilLanguageGuesser.php index 7b0dc6fc..98f1664b 100644 --- a/src/parser/PhutilLanguageGuesser.php +++ b/src/parser/PhutilLanguageGuesser.php @@ -9,7 +9,7 @@ final class PhutilLanguageGuesser extends Phobject { /** * Guess which computer programming language a file is written in. * - * @param string Source text of the file. + * @param string $source Source text of the file. * @return mixed Language string, or null if unable to guess. */ public static function guessLanguage($source) { diff --git a/src/parser/PhutilQueryStringParser.php b/src/parser/PhutilQueryStringParser.php index 90f67f64..4e082537 100644 --- a/src/parser/PhutilQueryStringParser.php +++ b/src/parser/PhutilQueryStringParser.php @@ -33,7 +33,7 @@ final class PhutilQueryStringParser extends Phobject { * * For a more basic parse, see @{method:parseQueryStringToPairList}. * - * @param string Query string. + * @param string $query_string Query string. * @return map Parsed dictionary. */ public function parseQueryString($query_string) { @@ -68,7 +68,7 @@ final class PhutilQueryStringParser extends Phobject { * Use @{method:parseQueryString} to produce a more sophisticated parse which * applies array rules and returns a dictionary. * - * @param string Query string. + * @param string $query_string Query string. * @return list> List of parsed parameters. */ public function parseQueryStringToPairList($query_string) { @@ -110,7 +110,7 @@ final class PhutilQueryStringParser extends Phobject { * * @param string $key * @param string $val - * @param array $input_arr + * @param array &$input_arr */ private function parseQueryKeyToArr($key, $val, array &$input_arr) { if (preg_match('/^[^\[\]]+(?:\[[^\[\]]*\])+$/', $key)) { diff --git a/src/parser/PhutilSimpleOptions.php b/src/parser/PhutilSimpleOptions.php index bcb25a4c..c763051b 100644 --- a/src/parser/PhutilSimpleOptions.php +++ b/src/parser/PhutilSimpleOptions.php @@ -31,7 +31,7 @@ final class PhutilSimpleOptions extends Phobject { * 'eyes' => '2', * ); * - * @param string Input option list. + * @param string $input Input option list. * @return dict Parsed dictionary. * @task parse */ @@ -130,8 +130,8 @@ final class PhutilSimpleOptions extends Phobject { * * legs=4, eyes=2 * - * @param dict Input dictionary. - * @param string Additional characters to escape. + * @param dict $options Input dictionary. + * @param string $escape (optional) Additional characters to escape. * @return string Unparsed option list. */ public function unparse(array $options, $escape = '') { @@ -161,8 +161,8 @@ final class PhutilSimpleOptions extends Phobject { * case insensitive, so "legs=4" has the same meaning as "LEGS=4". If you * set it to be case sensitive, the keys have different meanings. * - * @param bool True to make the parser case sensitive, false (default) to - * make it case-insensitive. + * @param bool $case_sensitive True to make the parser case sensitive, false + * to make it case-insensitive. * @return this * @task config */ diff --git a/src/parser/aast/api/AASTNode.php b/src/parser/aast/api/AASTNode.php index 7b20224a..db25b029 100644 --- a/src/parser/aast/api/AASTNode.php +++ b/src/parser/aast/api/AASTNode.php @@ -363,7 +363,7 @@ abstract class AASTNode extends Phobject { * Determines whether the current node appears //after// a specified node in * the tree. * - * @param AASTNode + * @param AASTNode $node * @return bool */ final public function isAfter(AASTNode $node) { @@ -375,7 +375,7 @@ abstract class AASTNode extends Phobject { * Determines whether the current node appears //before// a specified node in * the tree. * - * @param AASTNode + * @param AASTNode $node * @return bool */ final public function isBefore(AASTNode $node) { @@ -386,7 +386,7 @@ abstract class AASTNode extends Phobject { /** * Determines whether a specified node is a descendant of the current node. * - * @param AASTNode + * @param AASTNode $node * @return bool */ final public function containsDescendant(AASTNode $node) { diff --git a/src/parser/argument/PhutilArgumentParser.php b/src/parser/argument/PhutilArgumentParser.php index 6391fd83..fccb8e9d 100644 --- a/src/parser/argument/PhutilArgumentParser.php +++ b/src/parser/argument/PhutilArgumentParser.php @@ -95,7 +95,7 @@ final class PhutilArgumentParser extends Phobject { * * $args = new PhutilArgumentParser($argv); * - * @param list Argument vector to parse, generally the $argv global. + * @param list $argv Argument vector to parse, generally the $argv global. * @task parse */ public function __construct(array $argv) { @@ -111,9 +111,10 @@ final class PhutilArgumentParser extends Phobject { * @{method:getUnconsumedArgumentVector}. Doing a partial parse can make it * easier to share common flags across scripts or workflows. * - * @param list List of argument specs, see + * @param list $specs List of argument specs, see * @{class:PhutilArgumentSpecification}. - * @param bool Require flags appear before any non-flag arguments. + * @param bool $initial_only (optional) Require flags appear before any + * non-flag arguments. * @return this * @task parse */ @@ -310,7 +311,7 @@ final class PhutilArgumentParser extends Phobject { * user-friendly error. You can also use @{method:printUsageException} to * render the exception in a user-friendly way. * - * @param list List of argument specs, see + * @param list $specs List of argument specs, see * @{class:PhutilArgumentSpecification}. * @return this * @task parse @@ -346,7 +347,7 @@ final class PhutilArgumentParser extends Phobject { * Parse and consume a list of arguments, raising a user-friendly error if * anything remains. See also @{method:parseFull} and @{method:parsePartial}. * - * @param list List of argument specs, see + * @param list $specs List of argument specs, see * @{class:PhutilArgumentSpecification}. * @return this * @task parse @@ -367,7 +368,7 @@ final class PhutilArgumentParser extends Phobject { * * See @{class:PhutilArgumentWorkflow} for details on using workflows. * - * @param list List of argument specs, see + * @param list $workflows List of argument specs, see * @{class:PhutilArgumentSpecification}. * @return this * @task parse @@ -391,7 +392,7 @@ final class PhutilArgumentParser extends Phobject { * * See @{class:PhutilArgumentWorkflow} for details on using workflows. * - * @param list List of @{class:PhutilArgumentWorkflow}s. + * @param list $workflows List of @{class:PhutilArgumentWorkflow}s. * @return PhutilArgumentWorkflow|no Returns the chosen workflow if it is * not executable, or executes it and * exits with a return code if it is. diff --git a/src/parser/argument/PhutilArgumentSpecification.php b/src/parser/argument/PhutilArgumentSpecification.php index 71e583b1..fca3143f 100644 --- a/src/parser/argument/PhutilArgumentSpecification.php +++ b/src/parser/argument/PhutilArgumentSpecification.php @@ -34,7 +34,7 @@ final class PhutilArgumentSpecification extends Phobject { * wildcard setWildcard() * repeat setRepeatable() * - * @param dict Dictionary of quick parameter definitions. + * @param dict $spec Dictionary of quick parameter definitions. * @return PhutilArgumentSpecification Constructed argument specification. */ public static function newQuickSpec(array $spec) { diff --git a/src/parser/xhpast/api/XHPASTNode.php b/src/parser/xhpast/api/XHPASTNode.php index 0f685c5e..94c095dd 100644 --- a/src/parser/xhpast/api/XHPASTNode.php +++ b/src/parser/xhpast/api/XHPASTNode.php @@ -292,7 +292,6 @@ final class XHPASTNode extends AASTNode { * To prevent any possible ambiguity, the returned namespace will always be * prefixed with the namespace separator. * - * @param XHPASTNode The input node. * @return string|null The namespace which contains the input node, or * `null` if no such node exists. */ diff --git a/src/parser/xhpast/api/__tests__/XHPASTNodeTestCase.php b/src/parser/xhpast/api/__tests__/XHPASTNodeTestCase.php index 8e4ecbb1..7dfdc6b3 100644 --- a/src/parser/xhpast/api/__tests__/XHPASTNodeTestCase.php +++ b/src/parser/xhpast/api/__tests__/XHPASTNodeTestCase.php @@ -73,7 +73,7 @@ final class XHPASTNodeTestCase extends PhutilTestCase { * } * ``` * - * @param string The path to the test file. + * @param string $file The path to the test file. * @return pair The first element of the pair is the * `XHPASTTree` contained within the test file. * The second element of the pair is the diff --git a/src/parser/xhpast/bin/PhutilXHPASTBinary.php b/src/parser/xhpast/bin/PhutilXHPASTBinary.php index 5a1a4a13..058ff03c 100644 --- a/src/parser/xhpast/bin/PhutilXHPASTBinary.php +++ b/src/parser/xhpast/bin/PhutilXHPASTBinary.php @@ -71,7 +71,7 @@ final class PhutilXHPASTBinary extends Phobject { /** * Constructs an @{class:ExecFuture} for XHPAST. * - * @param wild Data to pass to the future. + * @param wild $data Data to pass to the future. * @return ExecFuture */ public static function getParserFuture($data) { diff --git a/src/readableserializer/PhutilReadableSerializer.php b/src/readableserializer/PhutilReadableSerializer.php index 7ef9d844..d4362149 100644 --- a/src/readableserializer/PhutilReadableSerializer.php +++ b/src/readableserializer/PhutilReadableSerializer.php @@ -19,7 +19,7 @@ final class PhutilReadableSerializer extends Phobject { * representation of the value; use @{method:printShort} or * @{method:printShallow} to summarize values. * - * @param wild Any value. + * @param wild $value Any value. * @return string Human-readable representation of the value. * @task print */ @@ -43,7 +43,7 @@ final class PhutilReadableSerializer extends Phobject { /** * Print a concise, human readable representation of a value. * - * @param wild Any value. + * @param wild $value Any value. * @return string Human-readable short representation of the value. * @task print */ @@ -86,9 +86,11 @@ final class PhutilReadableSerializer extends Phobject { * * To print any number of member variables, pass null for `$max_members`. * - * @param wild Any value. - * @param int Maximum depth to print for nested arrays and objects. - * @param int Maximum number of values to print at each level. + * @param wild $value Any value. + * @param int $max_depth (optional) Maximum depth to print for nested arrays + * and objects. Defaults to 2. + * @param int $max_members (optional) Maximum number of values to print at + * each level. Defaults to 25. * @return string Human-readable shallow representation of the value. * @task print */ @@ -107,11 +109,12 @@ final class PhutilReadableSerializer extends Phobject { /** * Implementation for @{method:printShallow}. * - * @param wild Any value. - * @param int Maximum depth to print for nested arrays and objects. - * @param int Maximum number of values to print at each level. - * @param int Current depth. - * @param string Indentation string. + * @param wild $value Any value. + * @param int $max_depth Maximum depth to print for nested arrays and + * objects. + * @param int $max_members Maximum number of values to print at each level. + * @param int $depth Current depth. + * @param string $indent Indentation string. * @return string Human-readable shallow representation of the value. * @task internal */ @@ -170,9 +173,9 @@ final class PhutilReadableSerializer extends Phobject { * Adds indentation to the beginning of every line starting from * `$first_line`. * - * @param string Printed value. - * @param string String to indent with. - * @param int Index of first line to indent. + * @param string $value Printed value. + * @param string $indent String to indent with. + * @param int $first_line Index of first line to indent. * @return string * @task internal */ diff --git a/src/repository/api/ArcanistGitAPI.php b/src/repository/api/ArcanistGitAPI.php index 1ff299ec..aa5027ce 100644 --- a/src/repository/api/ArcanistGitAPI.php +++ b/src/repository/api/ArcanistGitAPI.php @@ -82,8 +82,8 @@ final class ArcanistGitAPI extends ArcanistRepositoryAPI { /** * Tests if a child commit is descendant of a parent commit. * If child and parent are the same, it returns false. - * @param Child commit SHA. - * @param Parent commit SHA. + * @param $child Child commit SHA. + * @param $parent Parent commit SHA. * @return bool True if the child is a descendant of the parent. */ private function isDescendant($child, $parent) { @@ -404,7 +404,7 @@ final class ArcanistGitAPI extends ArcanistRepositoryAPI { /** * Translates a symbolic commit (like "HEAD^") to a commit identifier. - * @param string_symbol commit. + * @param string_symbol $symbolic_commit commit. * @return string the commit SHA. */ private function resolveCommit($symbolic_commit) { @@ -457,9 +457,9 @@ final class ArcanistGitAPI extends ArcanistRepositoryAPI { } /** - * @param the base revision - * @param head revision. If this is null, the generated diff will include the - * working copy + * @param $base the base revision + * @param $head (optional) head revision. If this is null, the generated diff + * will include the working copy */ public function getFullGitDiff($base, $head = null) { $options = $this->getDiffFullOptions(); @@ -491,10 +491,10 @@ final class ArcanistGitAPI extends ArcanistRepositoryAPI { } /** - * @param string Path to generate a diff for. - * @param bool If true, detect moves and renames. Otherwise, ignore - * moves/renames; this is useful because it prompts git to - * generate real diff text. + * @param string $path Path to generate a diff for. + * @param bool $detect_moves_and_renames (optional) If true, detect moves + * and renames. Otherwise, ignore moves/renames; this is useful + * because it prompts git to generate real diff text. */ public function getRawDiffText($path, $detect_moves_and_renames = true) { $options = $this->getDiffFullOptions($detect_moves_and_renames); @@ -1452,7 +1452,7 @@ final class ArcanistGitAPI extends ArcanistRepositoryAPI { * Follow the chain of tracking branches upstream until we reach a remote * or cycle locally. * - * @param string Ref to start from. + * @param string $start Ref to start from. * @return ArcanistGitUpstreamPath Path to an upstream. */ public function getPathToUpstream($start) { diff --git a/src/repository/api/ArcanistMercurialAPI.php b/src/repository/api/ArcanistMercurialAPI.php index 7e35a1e3..b27e87b2 100644 --- a/src/repository/api/ArcanistMercurialAPI.php +++ b/src/repository/api/ArcanistMercurialAPI.php @@ -732,8 +732,9 @@ final class ArcanistMercurialAPI extends ArcanistRepositoryAPI { * cause a conflict but this is something the user has to address. * 3. Strip the original commit. * - * @param array The list of child changesets off the original commit. - * @param file The file containing the new commit message. + * @param array $child_nodes The list of child changesets off the original + * commit. + * @param file $tmp_file The file containing the new commit message. */ private function amendNonHeadCommit($child_nodes, $tmp_file) { list($current) = $this->execxLocal( @@ -1053,7 +1054,7 @@ final class ArcanistMercurialAPI extends ArcanistRepositoryAPI { * included with Arcanist. This will not enable other extensions, e.g. * "evolve". * - * @param string The name of the extension to enable. + * @param string $extension The name of the extension to enable. * @return string A new command pattern that includes the necessary flags to * enable the specified extension. */ @@ -1086,10 +1087,10 @@ final class ArcanistMercurialAPI extends ArcanistRepositoryAPI { * Produces the arguments that should be passed to Mercurial command * execution that enables a desired extension. * - * @param string The name of the extension to enable. - * @param string The command pattern that will be run with the extension - * enabled. - * @param array Parameters for the command pattern argument. + * @param string $extension The name of the extension to enable. + * @param string $pattern The command pattern that will be run with the + * extension enabled. + * @param array ... Parameters for the command pattern argument. * @return array An array where the first item is a Mercurial command * pattern that includes the necessary flag for enabling the * desired extension, and all remaining items are parameters diff --git a/src/repository/api/ArcanistRepositoryAPI.php b/src/repository/api/ArcanistRepositoryAPI.php index 48b44f66..dd35db2f 100644 --- a/src/repository/api/ArcanistRepositoryAPI.php +++ b/src/repository/api/ArcanistRepositoryAPI.php @@ -429,7 +429,7 @@ abstract class ArcanistRepositoryAPI extends Phobject { /** * Try to read a scratch file, if it exists and is readable. * - * @param string Scratch file name. + * @param string $path Scratch file name. * @return mixed String for file contents, or false for failure. * @task scratch */ @@ -457,8 +457,8 @@ abstract class ArcanistRepositoryAPI extends Phobject { * Try to write a scratch file, if there's somewhere to put it and we can * write there. * - * @param string Scratch file name to write. - * @param string Data to write. + * @param string $path Scratch file name to write. + * @param string $data Data to write. * @return bool True on success, false on failure. * @task scratch */ @@ -489,7 +489,7 @@ abstract class ArcanistRepositoryAPI extends Phobject { /** * Try to remove a scratch file. * - * @param string Scratch file name to remove. + * @param string $path Scratch file name to remove. * @return bool True if the file was removed successfully. * @task scratch */ @@ -512,7 +512,7 @@ abstract class ArcanistRepositoryAPI extends Phobject { /** * Get a human-readable description of the scratch file location. * - * @param string Scratch file name. + * @param string $path Scratch file name. * @return mixed String, or false on failure. * @task scratch */ @@ -531,7 +531,7 @@ abstract class ArcanistRepositoryAPI extends Phobject { /** * Get the path to a scratch file, if possible. * - * @param string Scratch file name. + * @param string $path Scratch file name. * @return mixed File path, or false on failure. * @task scratch */ diff --git a/src/repository/parser/ArcanistMercurialParser.php b/src/repository/parser/ArcanistMercurialParser.php index 33e59c5c..96ad15e6 100644 --- a/src/repository/parser/ArcanistMercurialParser.php +++ b/src/repository/parser/ArcanistMercurialParser.php @@ -17,7 +17,7 @@ final class ArcanistMercurialParser extends Phobject { * can get less detailed information with @{method:parseMercurialStatus}. In * particular, this will parse copy sources as per "hg status -C". * - * @param string The stdout from running an "hg status" command. + * @param string $stdout The stdout from running an "hg status" command. * @return dict Map of paths to status dictionaries. * @task parse */ @@ -96,7 +96,7 @@ final class ArcanistMercurialParser extends Phobject { * can get more detailed information by invoking * @{method:parseMercurialStatusDetails}. * - * @param string The stdout from running an "hg status" command. + * @param string $stdout The stdout from running an "hg status" command. * @return dict Map of paths to ArcanistRepositoryAPI status flags. * @task parse */ @@ -110,7 +110,7 @@ final class ArcanistMercurialParser extends Phobject { * Parse the output of "hg log". This also parses "hg outgoing", "hg parents", * and other similar commands. This assumes "--style default". * - * @param string The stdout from running an "hg log" command. + * @param string $stdout The stdout from running an "hg log" command. * @return list List of dictionaries with commit information. * @task parse */ @@ -194,7 +194,7 @@ final class ArcanistMercurialParser extends Phobject { /** * Parse the output of "hg branches". * - * @param string The stdout from running an "hg branches" command. + * @param string $stdout The stdout from running an "hg branches" command. * @return list A list of dictionaries with branch information. * @task parse */ diff --git a/src/repository/state/ArcanistRepositoryLocalState.php b/src/repository/state/ArcanistRepositoryLocalState.php index e2c50283..84521fc7 100644 --- a/src/repository/state/ArcanistRepositoryLocalState.php +++ b/src/repository/state/ArcanistRepositoryLocalState.php @@ -211,7 +211,7 @@ abstract class ArcanistRepositoryLocalState /** * Restores changes that were previously stashed by {@method:saveStash()}. * - * @param wild A reference object referring to which previously stashed + * @param wild $ref A reference object referring to which previously stashed * changes to restore, from invoking {@method:saveStash()}. */ protected function restoreStash($ref) { diff --git a/src/symbols/PhutilClassMapQuery.php b/src/symbols/PhutilClassMapQuery.php index 62d567d6..702ba441 100644 --- a/src/symbols/PhutilClassMapQuery.php +++ b/src/symbols/PhutilClassMapQuery.php @@ -60,7 +60,7 @@ final class PhutilClassMapQuery extends Phobject { * Set the ancestor class or interface name to load the concrete descendants * of. * - * @param string Ancestor class or interface name. + * @param string $class Ancestor class or interface name. * @return this * @task config */ @@ -79,9 +79,9 @@ final class PhutilClassMapQuery extends Phobject { * * You must provide a method here to use @{method:setExpandMethod}. * - * @param string Name of the unique key method. - * @param bool If true, then classes which return `null` will be filtered - * from the results. + * @param string $unique_method Name of the unique key method. + * @param bool $filter_null (optional) If true, then classes which return + * `null` will be filtered from the results. * @return this * @task config */ @@ -125,7 +125,7 @@ final class PhutilClassMapQuery extends Phobject { * If a class map uses this pattern, it must also provide a unique key for * each instance with @{method:setUniqueMethod}. * - * @param string Name of the expansion method. + * @param string $expand_method Name of the expansion method. * @return this * @task config */ @@ -141,7 +141,7 @@ final class PhutilClassMapQuery extends Phobject { * The map will be sorted using @{function:msort} and passing this method * name. * - * @param string Name of the sorting method. + * @param string $sort_method Name of the sorting method. * @return this * @task config */ @@ -154,7 +154,7 @@ final class PhutilClassMapQuery extends Phobject { /** * Provide a method to filter the map. * - * @param string Name of the filtering method. + * @param string $filter_method Name of the filtering method. * @return this * @task config */ diff --git a/src/symbols/PhutilSymbolLoader.php b/src/symbols/PhutilSymbolLoader.php index 7f733ee7..795b0803 100644 --- a/src/symbols/PhutilSymbolLoader.php +++ b/src/symbols/PhutilSymbolLoader.php @@ -56,7 +56,7 @@ final class PhutilSymbolLoader { * Select the type of symbol to load, either `class`, `function` or * `interface`. * - * @param string Type of symbol to load. + * @param string $type Type of symbol to load. * @return this * * @task config @@ -71,7 +71,7 @@ final class PhutilSymbolLoader { * Restrict the symbol query to a specific library; only symbols from this * library will be loaded. * - * @param string Library name. + * @param string $library Library name. * @return this * * @task config @@ -90,7 +90,7 @@ final class PhutilSymbolLoader { * Restrict the symbol query to a specific path prefix; only symbols defined * in files below that path will be selected. * - * @param string Path relative to library root, like "apps/cheese/". + * @param string $path Path relative to library root, like "apps/cheese/". * @return this * * @task config @@ -105,7 +105,7 @@ final class PhutilSymbolLoader { * Restrict the symbol query to a single symbol name, e.g. a specific class * or function name. * - * @param string Symbol name. + * @param string $name Symbol name. * @return this * * @task config @@ -121,7 +121,7 @@ final class PhutilSymbolLoader { * strictly select descendants, the base class will not be selected. This * implies loading only classes. * - * @param string Base class name. + * @param string $base Base class name. * @return this * * @task config @@ -139,7 +139,7 @@ final class PhutilSymbolLoader { * NOTE: This currently causes class symbols to load, even if you run * @{method:selectSymbolsWithoutLoading}. * - * @param bool True if the query should load only concrete symbols. + * @param bool $concrete True if the query should load only concrete symbols. * @return this * * @task config @@ -356,7 +356,7 @@ final class PhutilSymbolLoader { * This method implicitly restricts the query to match only concrete * classes. * - * @param list List of constructor arguments. + * @param list $argv List of constructor arguments. * @return map Map of class names to constructed objects. */ public function loadObjects(array $argv = array()) { diff --git a/src/unit/ArcanistUnitTestResult.php b/src/unit/ArcanistUnitTestResult.php index ec25c20f..e40df693 100644 --- a/src/unit/ArcanistUnitTestResult.php +++ b/src/unit/ArcanistUnitTestResult.php @@ -80,7 +80,7 @@ final class ArcanistUnitTestResult extends Phobject { * Callers should pass an integer or a float. For example, pass `3` for * 3 seconds, or `0.125` for 125 milliseconds. * - * @param int|float Duration, in seconds. + * @param int|float $duration Duration, in seconds. * @return this */ public function setDuration($duration) { @@ -132,7 +132,7 @@ final class ArcanistUnitTestResult extends Phobject { /** * Merge several coverage reports into a comprehensive coverage report. * - * @param list List of coverage report strings. + * @param list $coverage List of coverage report strings. * @return string Cumulative coverage report. */ public static function mergeCoverage(array $coverage) { diff --git a/src/unit/engine/CSharpToolsTestEngine.php b/src/unit/engine/CSharpToolsTestEngine.php index 7fd23e0d..746c3739 100644 --- a/src/unit/engine/CSharpToolsTestEngine.php +++ b/src/unit/engine/CSharpToolsTestEngine.php @@ -81,7 +81,7 @@ final class CSharpToolsTestEngine extends XUnitTestEngine { * Overridden version of `buildTestFuture` so that the unit test can be run * via `cscover`, which instruments assemblies and reports on code coverage. * - * @param string Name of the test assembly. + * @param string $test_assembly Name of the test assembly. * @return array The future, output filename and coverage filename * stored in an array. */ @@ -145,8 +145,8 @@ final class CSharpToolsTestEngine extends XUnitTestEngine { /** * Returns coverage results for the unit tests. * - * @param string The name of the coverage file if one was provided by - * `buildTestFuture`. + * @param string $cover_file The name of the coverage file if one was + * provided by `buildTestFuture`. * @return array Code coverage results, or null. */ protected function parseCoverageResult($cover_file) { @@ -161,7 +161,7 @@ final class CSharpToolsTestEngine extends XUnitTestEngine { * result file is XML and can be large depending on what has been instrumented * so we cache it in case it's requested again. * - * @param string The name of the coverage file. + * @param string $cover_file The name of the coverage file. * @return array Code coverage results, or null if not cached. */ private function getCachedResultsIfPossible($cover_file) { @@ -177,8 +177,8 @@ final class CSharpToolsTestEngine extends XUnitTestEngine { /** * Stores the code coverage results in the cache. * - * @param string The name of the coverage file. - * @param array The results to cache. + * @param string $cover_file The name of the coverage file. + * @param array $results The results to cache. */ private function addCachedResults($cover_file, array $results) { if ($this->cachedResults == null) { @@ -192,7 +192,7 @@ final class CSharpToolsTestEngine extends XUnitTestEngine { * the `instrumented` and `executed` tags with this method so that * we can access the data multiple times without a performance hit. * - * @param array The array of XML tags to parse. + * @param array $tags The array of XML tags to parse. * @return array A PHP array containing the data. */ private function processTags($tags) { @@ -210,7 +210,7 @@ final class CSharpToolsTestEngine extends XUnitTestEngine { /** * Reads the code coverage results from the cscover results file. * - * @param string The path to the code coverage file. + * @param string $cover_file The path to the code coverage file. * @return array The code coverage results. */ public function readCoverage($cover_file) { diff --git a/src/unit/engine/PhpunitTestEngine.php b/src/unit/engine/PhpunitTestEngine.php index 4cb89006..30cc84c3 100644 --- a/src/unit/engine/PhpunitTestEngine.php +++ b/src/unit/engine/PhpunitTestEngine.php @@ -118,7 +118,7 @@ final class PhpunitTestEngine extends ArcanistUnitTestEngine { * TODO: Add support for finding tests in testsuite folders from * phpunit.xml configuration. * - * @param string PHP file to locate test cases for. + * @param string $path PHP file to locate test cases for. * @return string|null Path to test cases, or null. */ private function findTestFile($path) { @@ -192,7 +192,7 @@ final class PhpunitTestEngine extends ArcanistUnitTestEngine { * ...or similar. This list will be further pruned by the caller; it is * intentionally filesystem-agnostic to be unit testable. * - * @param string PHP file to locate test cases for. + * @param string $path PHP file to locate test cases for. * @return list List of directories to search for tests in. */ public static function getSearchLocationsForTests($path) { diff --git a/src/unit/engine/XUnitTestEngine.php b/src/unit/engine/XUnitTestEngine.php index d6a20464..9e4eb447 100644 --- a/src/unit/engine/XUnitTestEngine.php +++ b/src/unit/engine/XUnitTestEngine.php @@ -115,7 +115,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine { /** * Applies the discovery rules to the set of paths specified. * - * @param array Array of paths. + * @param array $paths Array of paths. * @return array Array of paths to test projects and assemblies. */ public function mapPathsToResults(array $paths) { @@ -161,7 +161,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine { /** * Builds and runs the specified test assemblies. * - * @param array Array of paths to test project files. + * @param array $test_projects Array of paths to test project files. * @return array Array of test results. */ public function runAllTests(array $test_projects) { @@ -188,7 +188,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine { * This is needed since we build the assemblies as part of the unit tests, but * we can't run any of the unit tests if the build fails. * - * @param array Array of results to check. + * @param array $results Array of results to check. * @return bool If there are any failures in the results. */ private function resultsContainFailures(array $results) { @@ -271,7 +271,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine { * build itself (since the unit tester is about to run each of the tests * individually). * - * @param array Array of test assemblies. + * @param array $test_assemblies Array of test assemblies. * @return array Array of test results. */ private function buildProjects(array $test_assemblies) { @@ -315,7 +315,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine { * Build the future for running a unit test. This can be overridden to enable * support for code coverage via another tool. * - * @param string Name of the test assembly. + * @param string $test_assembly Name of the test assembly. * @return array The future, output filename and coverage filename * stored in an array. */ @@ -345,7 +345,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine { * Run the xUnit test runner on each of the assemblies and parse the * resulting XML. * - * @param array Array of test assemblies. + * @param array $test_assemblies Array of test assemblies. * @return array Array of test results. */ private function testAssemblies(array $test_assemblies) { @@ -395,8 +395,8 @@ class XUnitTestEngine extends ArcanistUnitTestEngine { * coverage directly. Override this method in another class to provide code * coverage information (also see @{class:CSharpToolsUnitEngine}). * - * @param string The name of the coverage file if one was provided by - * `buildTestFuture`. + * @param string $coverage The name of the coverage file if one was + * provided by `buildTestFuture`. * @return array Code coverage results, or null. */ protected function parseCoverageResult($coverage) { @@ -406,9 +406,9 @@ class XUnitTestEngine extends ArcanistUnitTestEngine { /** * Parses the test results from xUnit. * - * @param string The name of the xUnit results file. - * @param string The name of the coverage file if one was provided by - * `buildTestFuture`. This is passed through to + * @param string $xunit_tmp The name of the xUnit results file. + * @param string $coverage The name of the coverage file if one was + * provided by `buildTestFuture`. This is passed through to * `parseCoverageResult`. * @return array Test results. */ diff --git a/src/unit/engine/phutil/PhutilTestCase.php b/src/unit/engine/phutil/PhutilTestCase.php index 81062ff2..e6a06ccd 100644 --- a/src/unit/engine/phutil/PhutilTestCase.php +++ b/src/unit/engine/phutil/PhutilTestCase.php @@ -28,10 +28,11 @@ abstract class PhutilTestCase extends Phobject { /** * Assert that a value is `false`, strictly. The test fails if it is not. * - * @param wild The empirically derived value, generated by executing the - * test. - * @param string A human-readable description of what these values represent, - * and particularly of what a discrepancy means. + * @param wild $result The empirically derived value, generated by + * executing the test. + * @param string $message (optional) A human-readable description of what + * these values represent, and particularly of what a + * discrepancy means. * * @return void * @task assert @@ -49,10 +50,11 @@ abstract class PhutilTestCase extends Phobject { /** * Assert that a value is `true`, strictly. The test fails if it is not. * - * @param wild The empirically derived value, generated by executing the - * test. - * @param string A human-readable description of what these values represent, - * and particularly of what a discrepancy means. + * @param wild $result The empirically derived value, generated by + * executing the test. + * @param string $message (optional) A human-readable description of what + * these values represent, and particularly of what a + * discrepancy means. * * @return void * @task assert @@ -74,12 +76,13 @@ abstract class PhutilTestCase extends Phobject { * compare values. This means values and types must be equal, key order must * be identical in arrays, and objects must be referentially identical. * - * @param wild The theoretically expected value, generated by careful - * reasoning about the properties of the system. - * @param wild The empirically derived value, generated by executing the - * test. - * @param string A human-readable description of what these values represent, - * and particularly of what a discrepancy means. + * @param wild $expect The theoretically expected value, generated by + * careful reasoning about the properties of the system. + * @param wild $result The empirically derived value, generated by + * executing the test. + * @param string $message (optional) A human-readable description of what + * these values represent, and particularly of what a + * discrepancy means. * * @return void * @task assert @@ -132,7 +135,8 @@ abstract class PhutilTestCase extends Phobject { * better indicates intent than using dummy values with assertEqual(). This * causes test failure. * - * @param string Human-readable description of the reason for test failure. + * @param string $message Human-readable description of the reason for + * test failure. * @return void * @task assert */ @@ -145,7 +149,7 @@ abstract class PhutilTestCase extends Phobject { * End this test by asserting that the test should be skipped for some * reason. * - * @param string Reason for skipping this test. + * @param string $message Reason for skipping this test. * @return void * @task assert */ @@ -302,8 +306,8 @@ abstract class PhutilTestCase extends Phobject { /** * This simplest way to assert exceptions are thrown. * - * @param exception The expected exception. - * @param callable The thing which throws the exception. + * @param exception $expected_exception_class The expected exception. + * @param callable $callable The thing which throws the exception. * * @return void * @task exceptions @@ -342,13 +346,13 @@ abstract class PhutilTestCase extends Phobject { * is_a_fruit($input); * } * - * @param map Map of test case labels to test case inputs. - * @param list List of expected results, true to indicate that the case - * is expected to succeed and false to indicate that the case - * is expected to throw. - * @param callable Callback to invoke for each test case. - * @param string Optional exception class to catch, defaults to - * 'Exception'. + * @param map $inputs Map of test case labels to test case inputs. + * @param list $expect List of expected results, true to indicate that + * the case is expected to succeed and false to indicate + * that the case is expected to throw. + * @param callable $callable Callback to invoke for each test case. + * @param string $exception_class (optional) Exception class to catch, + * defaults to 'Exception'. * @return void * @task exceptions */ @@ -432,11 +436,11 @@ abstract class PhutilTestCase extends Phobject { * * For cases where your inputs are not scalar, use @{method:tryTestCases}. * - * @param map Map of scalar test inputs to expected success (true + * @param map $map Map of scalar test inputs to expected success (true * expects success, false expects an exception). - * @param callable Callback to invoke for each test case. - * @param string Optional exception class to catch, defaults to - * 'Exception'. + * @param callable $callable Callback to invoke for each test case. + * @param string $exception_class (optional) Exception class to catch, + * defaults to 'Exception'. * @return void * @task exceptions */ @@ -483,7 +487,8 @@ abstract class PhutilTestCase extends Phobject { /** * This hook is invoked once per test, before the test method is invoked. * - * @param string Method name of the test which will be invoked. + * @param string $test_method_name Method name of the test which will be + * invoked. * @return void * @task hook */ @@ -495,7 +500,7 @@ abstract class PhutilTestCase extends Phobject { /** * This hook is invoked once per test, after the test method is invoked. * - * @param string Method name of the test which was invoked. + * @param string $test_method_name Method name of the test which was invoked. * @return void * @task hook */ @@ -508,7 +513,7 @@ abstract class PhutilTestCase extends Phobject { * This hook is invoked once, before any test cases execute. It gives you * an opportunity to perform setup steps for the entire suite of test cases. * - * @param list List of test cases to be run. + * @param list $test_cases List of test cases to be run. * @return void * @task hook */ @@ -520,7 +525,7 @@ abstract class PhutilTestCase extends Phobject { /** * This hook is invoked once, after all test cases execute. * - * @param list List of test cases that ran. + * @param list $test_cases List of test cases that ran. * @return void * @task hook */ @@ -544,7 +549,7 @@ abstract class PhutilTestCase extends Phobject { /** * Mark the currently-running test as a failure. * - * @param string Human-readable description of problems. + * @param string $reason Human-readable description of problems. * @return void * * @task internal @@ -557,7 +562,7 @@ abstract class PhutilTestCase extends Phobject { /** * This was a triumph. I'm making a note here: HUGE SUCCESS. * - * @param string Human-readable overstatement of satisfaction. + * @param string $reason Human-readable overstatement of satisfaction. * @return void * * @task internal @@ -570,7 +575,7 @@ abstract class PhutilTestCase extends Phobject { /** * Mark the current running test as skipped. * - * @param string Description for why this test was skipped. + * @param string $reason Description for why this test was skipped. * @return void * @task internal */ @@ -852,9 +857,10 @@ abstract class PhutilTestCase extends Phobject { * * This method throws and does not return. * - * @param string Human readable description of the expected value. - * @param string The actual value. - * @param string|null Optional assertion message. + * @param string $expect_description Human readable description of the + * expected value. + * @param string $actual_result The actual value. + * @param string|null $message Optional assertion message. * @return void * @task internal */ diff --git a/src/unit/parser/ArcanistTestResultParser.php b/src/unit/parser/ArcanistTestResultParser.php index 9a4c41fc..2b43fc3d 100644 --- a/src/unit/parser/ArcanistTestResultParser.php +++ b/src/unit/parser/ArcanistTestResultParser.php @@ -40,8 +40,8 @@ abstract class ArcanistTestResultParser extends Phobject { * Parse test results from provided input and return an array of * @{class:ArcanistUnitTestResult}. * - * @param string Path to test. - * @param string String containing test results. + * @param string $path Path to test. + * @param string $test_results String containing test results. * @return array */ abstract public function parseTestResults($path, $test_results); diff --git a/src/upload/ArcanistFileDataRef.php b/src/upload/ArcanistFileDataRef.php index 99ed03d9..c1aa4d56 100644 --- a/src/upload/ArcanistFileDataRef.php +++ b/src/upload/ArcanistFileDataRef.php @@ -40,7 +40,7 @@ final class ArcanistFileDataRef extends Phobject { * This name does not correspond to a path on disk, and is purely for * human consumption. * - * @param string Filename. + * @param string $name Filename. * @return this * @task config */ @@ -65,7 +65,7 @@ final class ArcanistFileDataRef extends Phobject { * data, or by calling @{method:setPath} and providing a path to a file on * disk. * - * @param bytes Blob of file data. + * @param bytes $data Blob of file data. * @task config */ public function setData($data) { @@ -91,7 +91,7 @@ final class ArcanistFileDataRef extends Phobject { * The path itself only provides data. If you want to name the file, you * should also call @{method:setName}. * - * @param string Path on disk to a file containing data to upload. + * @param string $path Path on disk to a file containing data to upload. * @return this * @task config */ @@ -133,7 +133,7 @@ final class ArcanistFileDataRef extends Phobject { * you want to upload a temporary file instead, you can specify an epoch * timestamp. The file will be deleted after this time. * - * @param int Epoch timestamp to retain the file until. + * @param int $epoch Epoch timestamp to retain the file until. * @return this * @task config */ diff --git a/src/upload/ArcanistFileUploader.php b/src/upload/ArcanistFileUploader.php index 2af3ae25..cc4217be 100644 --- a/src/upload/ArcanistFileUploader.php +++ b/src/upload/ArcanistFileUploader.php @@ -46,8 +46,8 @@ final class ArcanistFileUploader extends Phobject { * You can optionally provide an explicit key which will be used to identify * the file. After adding files, upload them with @{method:uploadFiles}. * - * @param ArcanistFileDataRef File data to upload. - * @param null|string Optional key to use to identify this file. + * @param ArcanistFileDataRef $file File data to upload. + * @param null|string $key (optional) Key to use to identify this file. * @return this * @task add */ diff --git a/src/utils/AbstractDirectedGraph.php b/src/utils/AbstractDirectedGraph.php index 24611c14..4e7db69a 100644 --- a/src/utils/AbstractDirectedGraph.php +++ b/src/utils/AbstractDirectedGraph.php @@ -55,7 +55,7 @@ abstract class AbstractDirectedGraph extends Phobject { * acceptable for your application) or throw an exception if you can't satisfy * this requirement. * - * @param list A list of nodes. + * @param list $nodes A list of nodes. * @return dict A map of nodes to the nodes reachable along their edges. * There must be an entry for each node you were provided. * @task build @@ -68,7 +68,8 @@ abstract class AbstractDirectedGraph extends Phobject { * edges that a user is trying to create here, or the initial set of edges * you know about. * - * @param dict A map of nodes to the nodes reachable along their edges. + * @param dict $nodes A map of nodes to the nodes reachable along their + * edges * @return this * @task build */ @@ -282,7 +283,7 @@ abstract class AbstractDirectedGraph extends Phobject { * NOTE: This only detects cycles reachable from a node. It does not detect * cycles in the entire graph. * - * @param scalar The node to walk from, looking for graph cycles. + * @param scalar $node The node to walk from, looking for graph cycles. * @return list|null Returns null if no cycles are reachable from the node, * or a list of nodes that form a cycle. * @task cycle @@ -312,8 +313,8 @@ abstract class AbstractDirectedGraph extends Phobject { * Internal cycle detection implementation. Recursively walks the graph, * keeping track of where it's been, and returns the first cycle it finds. * - * @param scalar The node to walk from. - * @param list Previously visited nodes. + * @param scalar $node The node to walk from. + * @param list $visited Previously visited nodes. * @return null|list Null if no cycles are found, or a list of nodes * which cycle. * @task cycle diff --git a/src/utils/CaseInsensitiveArray.php b/src/utils/CaseInsensitiveArray.php index 5f8cae53..66e43c5f 100644 --- a/src/utils/CaseInsensitiveArray.php +++ b/src/utils/CaseInsensitiveArray.php @@ -50,7 +50,7 @@ final class CaseInsensitiveArray extends PhutilArray { /** * Construct a new array object. * - * @param array The input array. + * @param array $data (optional) The input array. */ public function __construct(array $data = array()) { foreach ($data as $key => $value) { @@ -111,7 +111,7 @@ final class CaseInsensitiveArray extends PhutilArray { * [[http://php.net/manual/en/book.strings.php | string transformation]] * functions. * - * @param string The input key. + * @param string $key The input key. * @return string The transformed key. */ private function transformKey($key) { diff --git a/src/utils/PhutilBufferedIterator.php b/src/utils/PhutilBufferedIterator.php index 3f40b65d..598629f7 100644 --- a/src/utils/PhutilBufferedIterator.php +++ b/src/utils/PhutilBufferedIterator.php @@ -61,7 +61,7 @@ abstract class PhutilBufferedIterator extends Phobject implements Iterator { /** * Configure the page size. Note that implementations may ignore this. * - * @param int Page size. + * @param int $size Page size. * @return this * @task config */ diff --git a/src/utils/PhutilCallbackFilterIterator.php b/src/utils/PhutilCallbackFilterIterator.php index c1a95a4d..1eb367ea 100644 --- a/src/utils/PhutilCallbackFilterIterator.php +++ b/src/utils/PhutilCallbackFilterIterator.php @@ -7,8 +7,8 @@ final class PhutilCallbackFilterIterator extends FilterIterator { private $callback; /** - * @param Iterator - * @param callable Signature: (mixed $current): bool. + * @param Iterator $iterator + * @param callable $callback Signature: (mixed $current): bool. */ public function __construct(Iterator $iterator, $callback) { parent::__construct($iterator); diff --git a/src/utils/PhutilChunkedIterator.php b/src/utils/PhutilChunkedIterator.php index a002c5fe..d4a66894 100644 --- a/src/utils/PhutilChunkedIterator.php +++ b/src/utils/PhutilChunkedIterator.php @@ -12,8 +12,8 @@ final class PhutilChunkedIterator extends Phobject implements Iterator { private $current; /** - * @param Iterator - * @param int + * @param Iterator $iterator + * @param int $size */ public function __construct(Iterator $iterator, $size) { $this->iterator = $iterator; diff --git a/src/utils/PhutilRope.php b/src/utils/PhutilRope.php index 31d7aa27..76a26b41 100644 --- a/src/utils/PhutilRope.php +++ b/src/utils/PhutilRope.php @@ -19,7 +19,7 @@ final class PhutilRope extends Phobject { /** * Append a string to the rope. * - * @param string String to append. + * @param string $string String to append. * @return this */ public function append($string) { @@ -70,7 +70,7 @@ final class PhutilRope extends Phobject { /** * Get prefix bytes of the rope, up to some maximum size. * - * @param int Maximum number of bytes to read. + * @param int $length Maximum number of bytes to read. * @return string Bytes. */ public function getPrefixBytes($length) { @@ -108,7 +108,7 @@ final class PhutilRope extends Phobject { /** * Remove a specified number of bytes from the head of the rope. * - * @param int Bytes to remove. + * @param int $remove Bytes to remove. * @return this */ public function removeBytesFromHead($remove) { diff --git a/src/utils/PhutilSystem.php b/src/utils/PhutilSystem.php index d2c053a5..4b1a98b9 100644 --- a/src/utils/PhutilSystem.php +++ b/src/utils/PhutilSystem.php @@ -106,7 +106,7 @@ final class PhutilSystem extends Phobject { * See @{method:getSystemMemoryInformation}. This method is used to get memory * information on Linux. * - * @param string Raw `/proc/meminfo`. + * @param string $data Raw `/proc/meminfo`. * @return map Parsed memory information. * @task memory */ @@ -159,7 +159,7 @@ final class PhutilSystem extends Phobject { * See @{method:getSystemMemoryInformation}. This method is used to get memory * information on Mac OS X. * - * @param string Raw `vm_stat` output. + * @param string $data Raw `vm_stat` output. * @return map Parsed memory information. * @task memory */ diff --git a/src/utils/utf8.php b/src/utils/utf8.php index 7ba7b11e..ef1b2551 100644 --- a/src/utils/utf8.php +++ b/src/utils/utf8.php @@ -8,7 +8,7 @@ * * This function treats overlong encodings as invalid. * - * @param string String to convert to valid UTF-8. + * @param string $string String to convert to valid UTF-8. * @return string String with invalid UTF-8 byte subsequences replaced with * U+FFFD. */ @@ -78,8 +78,8 @@ function phutil_utf8ize($string) { * types silently truncate strings which contain characters outside of this * set. * - * @param string String to test for being valid UTF-8 with only characters in - * the basic multilingual plane. + * @param string $string String to test for being valid UTF-8 with only + * characters in the basic multilingual plane. * @return bool True if the string is valid UTF-8 with only BMP characters. */ function phutil_is_utf8_with_only_bmp_characters($string) { @@ -90,7 +90,7 @@ function phutil_is_utf8_with_only_bmp_characters($string) { /** * Determine if a string is valid UTF-8. * - * @param string Some string which may or may not be valid UTF-8. + * @param string $string Some string which may or may not be valid UTF-8. * @return bool True if the string is valid UTF-8. */ function phutil_is_utf8($string) { @@ -116,9 +116,9 @@ function phutil_is_utf8($string) { * that function can use more performant mechanisms if they are available on * the system. * - * @param string Some string which may or may not be valid UTF-8. - * @param bool True to require all characters be part of the basic - * multilingual plane (no more than 3-bytes long). + * @param string $string Some string which may or may not be valid UTF-8. + * @param bool $only_bmp (optional) True to require all characters be part + * of the basic multilingual plane (no more than 3-bytes long). * @return bool True if the string is valid UTF-8. */ function phutil_is_utf8_slowly($string, $only_bmp = false) { @@ -284,7 +284,7 @@ function phutil_is_utf8_slowly($string, $only_bmp = false) { /** * Find the character length of a UTF-8 string. * - * @param string A valid utf-8 string. + * @param string $string A valid utf-8 string. * @return int The character length of the string. */ function phutil_utf8_strlen($string) { @@ -314,7 +314,7 @@ function phutil_utf8_strlen($string) { * * NOTE: This function is VERY slow. * - * @param string A valid UTF-8 string. + * @param string $string A valid UTF-8 string. * @return int The console display length of the string. */ function phutil_utf8_console_strlen($string) { @@ -370,7 +370,7 @@ function phutil_utf8_console_strlen($string) { * * Most languages use spaces to separate words, but these languages do not. * - * @param string String to examine, in UTF8. + * @param string $string String to examine, in UTF8. * @return bool True if the string contains Chinese, Japanese, or Korean * characters. */ @@ -427,8 +427,9 @@ function phutil_utf8_is_cjk($string) { * Split a UTF-8 string into an array of characters. Combining characters are * also split. * - * @param string A valid utf-8 string. - * @param int|null Stop processing after examining this many bytes. + * @param string $string A valid utf-8 string. + * @param int|null $byte_limit (optional) Stop processing after examining this + * many bytes. * @return list A list of characters in the string. */ function phutil_utf8v($string, $byte_limit = null) { @@ -492,7 +493,7 @@ function phutil_utf8v($string, $byte_limit = null) { /** * Split a UTF-8 string into an array of codepoints (as integers). * - * @param string A valid UTF-8 string. + * @param string $string A valid UTF-8 string. * @return list A list of codepoints, as integers. */ function phutil_utf8v_codepoints($string) { @@ -541,7 +542,7 @@ function phutil_utf8v_codepoints($string) { /** * Convert a Unicode codepoint into a UTF8-encoded string. * - * @param int Unicode codepoint. + * @param int $codepoint Unicode codepoint. * @return string UTF8 encoding. */ function phutil_utf8_encode_codepoint($codepoint) { @@ -573,7 +574,8 @@ function phutil_utf8_encode_codepoint($codepoint) { /** * Hard-wrap a block of UTF-8 text with embedded HTML tags and entities. * - * @param string An HTML string with tags and entities. + * @param string $string An HTML string with tags and entities. + * @param int $width Width of the hard-wrapped lines * @return list List of hard-wrapped lines. */ function phutil_utf8_hard_wrap_html($string, $width) { @@ -628,8 +630,8 @@ function phutil_utf8_hard_wrap_html($string, $width) { /** * Hard-wrap a block of UTF-8 text with no embedded HTML tags and entities. * - * @param string A non HTML string - * @param int Width of the hard-wrapped lines + * @param string $string A non HTML string + * @param int $width Width of the hard-wrapped lines * @return list List of hard-wrapped lines. */ function phutil_utf8_hard_wrap($string, $width) { @@ -677,9 +679,9 @@ function phutil_utf8_hard_wrap($string, $width) { * encoding name identifies a real encoding but the string is not actually * encoded with that encoding. * - * @param string String to re-encode. - * @param string Target encoding name, like "UTF-8". - * @param string Source encoding name, like "ISO-8859-1". + * @param string $string String to re-encode. + * @param string $to_encoding Target encoding name, like "UTF-8". + * @param string $from_encoding Source encoding name, like "ISO-8859-1". * @return string Input string, with converted character encoding. * * @phutil-external-symbol function mb_convert_encoding @@ -740,7 +742,7 @@ function phutil_utf8_convert($string, $to_encoding, $from_encoding) { * completely destroy inputs, so it just has to be better than that. Similar to * @{function:ucwords}. * - * @param string UTF-8 input string. + * @param string $str UTF-8 input string. * @return string Input, in some semblance of title case. */ function phutil_utf8_ucwords($str) { @@ -780,7 +782,7 @@ function phutil_utf8_ucwords($str) { * Convert a string to lower case in a UTF8-aware way. Similar to * @{function:strtolower}. * - * @param string UTF-8 input string. + * @param string $str UTF-8 input string. * @return string Input, in some semblance of lower case. * * @phutil-external-symbol function mb_convert_case @@ -808,7 +810,7 @@ function phutil_utf8_strtolower($str) { * Convert a string to upper case in a UTF8-aware way. Similar to * @{function:strtoupper}. * - * @param string UTF-8 input string. + * @param string $str UTF-8 input string. * @return string Input, in some semblance of upper case. * * @phutil-external-symbol function mb_convert_case @@ -833,8 +835,8 @@ function phutil_utf8_strtoupper($str) { * Replace characters in a string in a UTF-aware way. Similar to * @{function:strtr}. * - * @param string UTF-8 input string. - * @param map Map of characters to replace. + * @param string $str UTF-8 input string. + * @param map $map Map of characters to replace. * @return string Input with translated characters. */ function phutil_utf8_strtr($str, array $map) { @@ -854,7 +856,7 @@ function phutil_utf8_strtr($str, array $map) { /** * Determine if a given unicode character is a combining character or not. * - * @param string A single unicode character. + * @param string $character A single unicode character. * @return boolean True or false. */ function phutil_utf8_is_combining_character($character) { @@ -882,7 +884,7 @@ function phutil_utf8_is_combining_character($character) { * Split a UTF-8 string into an array of characters. Combining characters * are not split. * - * @param string A valid utf-8 string. + * @param string $string A valid utf-8 string. * @return list A list of characters in the string. */ function phutil_utf8v_combined($string) { @@ -897,7 +899,7 @@ function phutil_utf8v_combined($string) { * This is a low-level method which can allow other operations to do less work. * If you have a string, call @{method:phutil_utf8v_combined} instead. * - * @param list List of UTF-8 characters. + * @param list $characters List of UTF-8 characters. * @return list List of UTF-8 strings with combining characters merged. */ function phutil_utf8v_combine_characters(array $characters) { @@ -961,7 +963,7 @@ function phutil_get_system_locale() { /** * Test if a system locale (LC_ALL) is available on the system. * - * @param string Locale name like "en_US.UTF-8". + * @param string $locale Locale name like "en_US.UTF-8". * @return bool True if the locale is available. */ function phutil_is_system_locale_available($locale) { @@ -976,7 +978,7 @@ function phutil_is_system_locale_available($locale) { /** * Set the system locale (LC_ALL) to a particular value. * - * @param string New locale setting. + * @param string $locale New locale setting. * @return void */ function phutil_set_system_locale($locale) { diff --git a/src/utils/utils.php b/src/utils/utils.php index 7043d9b8..58aa9c7a 100644 --- a/src/utils/utils.php +++ b/src/utils/utils.php @@ -27,10 +27,10 @@ function id($x) { * a default if it does not. This function allows you to concisely access an * index which may or may not exist without raising a warning. * - * @param array Array to access. - * @param scalar Index to access in the array. - * @param wild Default value to return if the key is not present in the - * array. + * @param array $array Array to access. + * @param scalar $key Index to access in the array. + * @param wild $default (optional) Default value to return if the key is + * not present in the array. * @return wild If `$array[$key]` exists, that value is returned. If not, * $default is returned without raising a warning. */ @@ -57,9 +57,9 @@ function idx(array $array, $key, $default = null) { * `$dict['a']['b']['c']`, if it exists. If it does not, or any intermediate * value is not itself an array, it returns the defualt value. * - * @param array Array to access. - * @param list List of keys to access, in sequence. - * @param wild Default value to return. + * @param array $map Array to access. + * @param list $path List of keys to access, in sequence. + * @param wild $default (optional) Default value to return. * @return wild Accessed value, or default if the value is not accessible. */ function idxv(array $map, array $path, $default = null) { @@ -126,13 +126,14 @@ function idxv(array $map, array $path, $default = null) { * See also @{function:ipull}, which works similarly but accesses array indexes * instead of calling methods. * - * @param list Some list of objects. - * @param string|null Determines which **values** will appear in the result - * array. Use a string like 'getName' to store the - * value of calling the named method in each value, or - * ##null## to preserve the original objects. - * @param string|null Determines how **keys** will be assigned in the result - * array. Use a string like 'getID' to use the result + * @param list $list Some list of objects. + * @param string|null $method Determines which **values** will appear in + * the result array. Use a string like 'getName' to + * store the value of calling the named method in each + * value, or ##null## to preserve the original objects. + * @param string|null $key_method (optional) Determines how **keys** will + * be assigned in the result array. + * Use a string like 'getID' to use the result * of calling the named method as each object's key, or * `null` to preserve the original keys. * @return dict A dictionary with keys and values derived according @@ -199,15 +200,16 @@ function mpull(array $list, $method, $key_method = null) { * See also @{function:mpull}, which works similarly but calls object methods * instead of accessing object properties. * - * @param list Some list of objects. - * @param string|null Determines which **values** will appear in the result - * array. Use a string like 'name' to store the value of - * accessing the named property in each value, or - * `null` to preserve the original objects. - * @param string|null Determines how **keys** will be assigned in the result - * array. Use a string like 'id' to use the result of - * accessing the named property as each object's key, or - * `null` to preserve the original keys. + * @param list $list Some list of objects. + * @param string|null $property Determines which **values** will appear in + * the result array. Use a string like 'name' to store + * the value of accessing the named property in each + * value, or `null` to preserve the original objects. + * @param string|null $key_property (optional) Determines how **keys** will + * be assigned in the result array. Use a string like + * 'id' to use the result of accessing the named property + * as each object's key, or `null` to preserve the + * original keys. * @return dict A dictionary with keys and values derived according * to whatever you passed as `$property` and * `$key_property`. @@ -249,14 +251,15 @@ function ppull(array $list, $property, $key_property = null) { * * See @{function:mpull} for more usage examples. * - * @param list Some list of arrays. - * @param scalar|null Determines which **values** will appear in the result - * array. Use a scalar to select that index from each - * array, or null to preserve the arrays unmodified as - * values. - * @param scalar|null Determines which **keys** will appear in the result - * array. Use a scalar to select that index from each - * array, or null to preserve the array keys. + * @param list $list Some list of arrays. + * @param scalar|null $index Determines which **values** will appear in the + * result array. Use a scalar to select that index from + * each array, or null to preserve the arrays unmodified + * as values. + * @param scalar|null $key_index (optional) Determines which **keys** will + * appear in the result array. Use a scalar to select + * that index from each array, or null to preserve the + * array keys. * @return dict A dictionary with keys and values derived according * to whatever you passed for `$index` and `$key_index`. */ @@ -300,11 +303,12 @@ function ipull(array $list, $index, $key_index = null) { * See also @{function:igroup}, which works the same way but operates on * array indexes. * - * @param list List of objects to group by some property. - * @param string Name of a method, like 'getType', to call on each object - * in order to determine which group it should be placed into. - * @param ... Zero or more additional method names, to subgroup the - * groups. + * @param list $list List of objects to group by some property. + * @param string $by Name of a method, like 'getType', to call on each + * object in order to determine which group it should be + * placed into. + * @param ... (optional) Zero or more additional method names, to + * subgroup the groups. * @return dict Dictionary mapping distinct method returns to lists of * all objects which returned that value. */ @@ -340,11 +344,11 @@ function mgroup(array $list, $by /* , ... */) { * as @{function:mgroup}, except it operates on the values of array indexes * rather than the return values of method calls. * - * @param list List of arrays to group by some index value. - * @param string Name of an index to select from each array in order to + * @param list $list List of arrays to group by some index value. + * @param string $by Name of an index to select from each array in order to * determine which group it should be placed into. - * @param ... Zero or more additional indexes names, to subgroup the - * groups. + * @param ... (optional) Zero or more additional indexes names, to + * subgroup the groups. * @return dict Dictionary mapping distinct index values to lists of * all objects which had that value at the index. */ @@ -387,9 +391,9 @@ function igroup(array $list, $by /* , ... */) { * * NOTE: This method does not take the list by reference; it returns a new list. * - * @param list List of objects to sort by some property. - * @param string Name of a method to call on each object; the return values - * will be used to sort the list. + * @param list $list List of objects to sort by some property. + * @param string $method Name of a method to call on each object; the return + * values will be used to sort the list. * @return list Objects ordered by the return values of the method calls. */ function msort(array $list, $method) { @@ -428,9 +432,9 @@ function msort(array $list, $method) { * * This sort is stable, well-behaved, and more efficient than `usort()`. * - * @param list List of objects to sort. - * @param string Name of a method to call on each object. The method must - * return a @{class:PhutilSortVector}. + * @param list $list List of objects to sort. + * @param string $method Name of a method to call on each object. The method + * must return a @{class:PhutilSortVector}. * @return list Objects ordered by the vectors. */ function msortv(array $list, $method) { @@ -480,8 +484,8 @@ function msortv_internal(array $list, $method, $flags) { * @{function:msort}, but operates on a list of arrays instead of a list of * objects. * - * @param list List of arrays to sort by some index value. - * @param string Index to access on each object; the return values + * @param list $list List of arrays to sort by some index value. + * @param string $index Index to access on each object; the return values * will be used to sort the list. * @return list Arrays ordered by the index values. */ @@ -515,10 +519,10 @@ function isort(array $list, $index) { * * mfilter($list, 'hasChildren', true); * - * @param array List of objects to filter. - * @param string A method name. - * @param bool Optionally, pass true to drop objects which pass the - * filter instead of keeping them. + * @param array $list List of objects to filter. + * @param string $method A method name. + * @param bool $negate (optional) Pass true to drop objects which pass + * the filter instead of keeping them. * @return array List of objects which pass the filter. */ function mfilter(array $list, $method, $negate = false) { @@ -560,10 +564,10 @@ function mfilter(array $list, $method, $negate = false) { * * ifilter($list, 'username', true); * - * @param array List of arrays to filter. - * @param scalar The index. - * @param bool Optionally, pass true to drop arrays which pass the - * filter instead of keeping them. + * @param array $list List of arrays to filter. + * @param scalar $index The index. + * @param bool $negate (optional) Pass true to drop arrays which pass + * the filter instead of keeping them. * @return array List of arrays which pass the filter. */ function ifilter(array $list, $index, $negate = false) { @@ -599,8 +603,8 @@ function ifilter(array $list, $index, $negate = false) { * uses: either reducing a large dictionary to a smaller one, or changing the * key order on an existing dictionary. * - * @param dict Dictionary of key-value pairs to select from. - * @param list List of keys to select. + * @param dict $dict Dictionary of key-value pairs to select from. + * @param list $keys List of keys to select. * @return dict Dictionary of only those key-value pairs where the key was * present in the list of keys to select. Ordering is * determined by the list order. @@ -620,8 +624,8 @@ function array_select_keys(array $dict, array $keys) { * Checks if all values of array are instances of the passed class. Throws * `InvalidArgumentException` if it isn't true for any value. * - * @param array - * @param string Name of the class or 'array' to check arrays. + * @param array $arr + * @param string $class Name of the class or 'array' to check arrays. * @return array Returns passed array. */ function assert_instances_of(array $arr, $class) { @@ -658,8 +662,8 @@ function assert_instances_of(array $arr, $class) { /** * Assert that two arrays have the exact same keys, in any order. * - * @param map Array with expected keys. - * @param map Array with actual keys. + * @param map $expect Array with expected keys. + * @param map $actual Array with actual keys. * @return void */ function assert_same_keys(array $expect, array $actual) { @@ -690,7 +694,7 @@ function assert_same_keys(array $expect, array $actual) { /** * Assert that passed data can be converted to string. * - * @param string Assert that this data is valid. + * @param string $parameter Assert that this data is valid. * @return void * * @task assert @@ -793,8 +797,8 @@ function nonempty(/* ... */) { * constructors can be invoked with `call_user_func_array()`, and may give your * class a cleaner and more descriptive API. * - * @param string The name of a class. - * @param list Array of arguments to pass to its constructor. + * @param string $class_name The name of a class. + * @param list $argv Array of arguments to pass to its constructor. * @return obj A new object of the specified class, constructed by passing * the argument vector to its constructor. */ @@ -813,7 +817,7 @@ function newv($class_name, array $argv) { * choke if you pass it some non-referenceable value like the return value of * a function. * - * @param array Array to retrieve the first element from. + * @param array $arr Array to retrieve the first element from. * @return wild The first value of the array. */ function head(array $arr) { @@ -825,7 +829,7 @@ function head(array $arr) { * that it won't warn you if you pass some non-referencable array to * it -- e.g., the result of some other array operation. * - * @param array Array to retrieve the last element from. + * @param array $arr Array to retrieve the last element from. * @return wild The last value of the array. */ function last(array $arr) { @@ -835,7 +839,7 @@ function last(array $arr) { /** * Returns the first key of an array. * - * @param array Array to retrieve the first key from. + * @param array $arr Array to retrieve the first key from. * @return int|string The first key of the array. */ function head_key(array $arr) { @@ -846,7 +850,7 @@ function head_key(array $arr) { /** * Returns the last key of an array. * - * @param array Array to retrieve the last key from. + * @param array $arr Array to retrieve the last key from. * @return int|string The last key of the array. */ function last_key(array $arr) { @@ -865,7 +869,7 @@ function last_key(array $arr) { * merge them with this function than by calling array_merge() in a loop, * because using a loop generates an intermediary array on each iteration. * - * @param list Vector of arrays to merge. + * @param list $arrayv Vector of arrays to merge. * @return list Arrays, merged with array_merge() semantics. */ function array_mergev(array $arrayv) { @@ -902,7 +906,8 @@ function array_mergev(array $arrayv) { * of SVN, Git or Mercurial do on any OS. * * @param string|PhutilSafeHTML $corpus Block of text to be split into lines. - * @param bool If true, retain line endings in result strings. + * @param bool $retain_endings (optional) If true, retain line endings in + * result strings. * @return list List of lines. * * @phutil-external-symbol class PhutilSafeHTML @@ -952,7 +957,7 @@ function phutil_split_lines($corpus, $retain_endings = true) { * * $result = array_fuse($list); * - * @param list List of scalars. + * @param list $list (optional) List of scalars. * @return dict Dictionary with inputs mapped to themselves. */ function array_fuse(array $list = null) { @@ -977,8 +982,8 @@ function array_fuse(array $list = null) { * * This function does not preserve keys. * - * @param wild Element to interleave. - * @param list List of elements to be interleaved. + * @param wild $interleave Element to interleave. + * @param list $array List of elements to be interleaved. * @return list Original list with the new element interleaved. */ function array_interleave($interleave, array $array) { @@ -1005,7 +1010,7 @@ function phutil_is_hiphop_runtime() { /** * Converts a string to a loggable one, with unprintables and newlines escaped. * - * @param string Any string. + * @param string $string Any string. * @return string String with control and newline characters escaped, suitable * for printing on a single log line. */ @@ -1056,8 +1061,8 @@ function phutil_loggable_string($string) { * when a zero-length write is caused by EAGAIN and return `0` only if the * write really should be retried. * - * @param resource Socket or pipe stream. - * @param string Bytes to write. + * @param resource $stream Socket or pipe stream. + * @param string $bytes Bytes to write. * @return bool|int Number of bytes written, or `false` on any error (including * errors which `fwrite()` can not detect, like a broken pipe). */ @@ -1136,7 +1141,7 @@ function phutil_fwrite_nonblocking_stream($stream, $bytes) { * * ...which is self-documenting and difficult to make a mistake with. * - * @param string Human readable description of a unit quantity. + * @param string $description Human readable description of a unit quantity. * @return int Quantity of specified unit. */ function phutil_units($description) { @@ -1279,7 +1284,8 @@ function phutil_units($description) { * Compute the number of microseconds that have elapsed since an earlier * timestamp (from `microtime(true)`). * - * @param double Microsecond-precision timestamp, from `microtime(true)`. + * @param double $timestamp Microsecond-precision timestamp, from + * `microtime(true)`. * @return int Elapsed microseconds. */ function phutil_microseconds_since($timestamp) { @@ -1301,8 +1307,8 @@ function phutil_microseconds_since($timestamp) { /** * Decode a JSON dictionary. * - * @param string A string which ostensibly contains a JSON-encoded list or - * dictionary. + * @param string $string A string which ostensibly contains a JSON-encoded + * list or dictionary. * @return mixed Decoded list/dictionary. */ function phutil_json_decode($string) { @@ -1322,7 +1328,7 @@ function phutil_json_decode($string) { /** * Encode a value in JSON, raising an exception if it can not be encoded. * - * @param wild A value to encode. + * @param wild $value A value to encode. * @return string JSON representation of the value. */ function phutil_json_encode($value) { @@ -1362,8 +1368,8 @@ function phutil_json_encode($value) { /** * Produce a human-readable explanation why a value can not be JSON-encoded. * - * @param wild Value to validate. - * @param string Path within the object to provide context. + * @param wild $value Value to validate. + * @param string $path (optional) Path within the object to provide context. * @return string|null Explanation of why it can't be encoded, or null. */ function phutil_validate_json($value, $path = '') { @@ -1435,7 +1441,7 @@ function phutil_validate_json($value, $path = '') { /** * Decode an INI string. * - * @param string + * @param string $string * @return mixed */ function phutil_ini_decode($string) { @@ -1508,7 +1514,7 @@ function phutil_ini_decode($string) { * output. For example, when `git fetch` fails, the output includes credentials * for authenticated HTTP remotes. * - * @param string Some block of text. + * @param string $string Some block of text. * @return string A similar block of text, but with credentials that could * be identified censored. */ @@ -1523,7 +1529,7 @@ function phutil_censor_credentials($string) { * This function is intended to behave similarly to PHP's `var_export` function, * but the output is intended to follow our style conventions. * - * @param wild The variable you want to export. + * @param wild $var The variable you want to export. * @return string */ function phutil_var_export($var) { @@ -1570,8 +1576,8 @@ function phutil_var_export($var) { /** * An improved version of `fnmatch`. * - * @param string A glob pattern. - * @param string A path. + * @param string $glob A glob pattern. + * @param string $path A path. * @return bool */ function phutil_fnmatch($glob, $path) { @@ -1655,8 +1661,8 @@ function phutil_fnmatch($glob, $path) { * It is questionable how practical these attacks are, but they are possible * in theory and defusing them is straightforward. * - * @param string First hash. - * @param string Second hash. + * @param string $u First hash. + * @param string $v Second hash. * @return bool True if hashes are identical. */ function phutil_hashes_are_identical($u, $v) { @@ -1686,7 +1692,7 @@ function phutil_hashes_are_identical($u, $v) { /** * Build a query string from a dictionary. * - * @param map Dictionary of parameters. + * @param map $parameters Dictionary of parameters. * @return string HTTP query string. */ function phutil_build_http_querystring(array $parameters) { @@ -1701,7 +1707,7 @@ function phutil_build_http_querystring(array $parameters) { /** * Build a query string from a list of parameter pairs. * - * @param list> List of pairs. + * @param list> $pairs List of pairs. * @return string HTTP query string. */ function phutil_build_http_querystring_from_pairs(array $pairs) { @@ -1733,8 +1739,8 @@ function phutil_build_http_querystring_from_pairs(array $pairs) { * * Scalar values are converted to strings. Nonscalar values raise exceptions. * - * @param scalar HTTP parameter key. - * @param scalar HTTP parameter value. + * @param scalar $key HTTP parameter key. + * @param scalar $value HTTP parameter value. * @return pair Key and value as strings. */ function phutil_http_parameter_pair($key, $value) { @@ -1800,7 +1806,7 @@ function phutil_decode_mime_header($header) { * We also reject arrays. PHP casts them to the string "Array". This behavior * is, charitably, evil. * - * @param wild Any value which aspires to be represented as a string. + * @param wild $value Any value which aspires to be represented as a string. * @return string String representation of the provided value. */ function phutil_string_cast($value) { @@ -1837,7 +1843,7 @@ function phutil_string_cast($value) { * This is similar to "get_type()", but describes objects and arrays in more * detail. * - * @param wild Anything. + * @param wild $value Anything. * @return string Human-readable description of the value's type. */ function phutil_describe_type($value) { @@ -1885,7 +1891,7 @@ function phutil_is_natural_list(array $list) { * you have more information, like you know the format of the suffix). For infix * URI components, use @{function:phutil_escape_uri_path_component} instead. * - * @param string Some string. + * @param string $string Some string. * @return string URI encoded string, except for '/'. */ function phutil_escape_uri($string) { @@ -1909,7 +1915,7 @@ function phutil_escape_uri($string) { * @{function:phutil_unescape_uri_path_component} before it can be used in the * application. * - * @param string Some string. + * @param string $string Some string. * @return string URI encoded string that is safe for infix composition. */ function phutil_escape_uri_path_component($string) { @@ -1927,7 +1933,7 @@ function phutil_escape_uri_path_component($string) { * which is added to survive the implied unescaping performed by the webserver * when interpreting the request. * - * @param string Some string emitted + * @param string $string Some string emitted * from @{function:phutil_escape_uri_path_component} and * then accessed via a web server. * @return string Original string. @@ -2109,7 +2115,7 @@ function phutil_raise_preg_exception($function, array $argv) { * This method raises an exception if passed a value which is neither null * nor a string. * - * @param Value to test. + * @param $value Value to test. * @return bool True if the parameter is a nonempty string. */ function phutil_nonempty_string($value) { @@ -2143,7 +2149,7 @@ function phutil_nonempty_string($value) { * * This method raises an exception if passed any other value. * - * @param Value to test. + * @param $value Value to test. * @return bool True if the parameter is a nonempty, stringlike value. */ function phutil_nonempty_stringlike($value) { @@ -2193,7 +2199,7 @@ function phutil_nonempty_stringlike($value) { * * This method raises an exception if passed any other value. * - * @param Value to test. + * @param $value Value to test. * @return bool True if the parameter is a nonempty, scalar value. */ function phutil_nonempty_scalar($value) { diff --git a/src/utils/viewutils.php b/src/utils/viewutils.php index b660de42..4a056757 100644 --- a/src/utils/viewutils.php +++ b/src/utils/viewutils.php @@ -24,9 +24,9 @@ function phutil_format_relative_time($duration) { * seconds, but unlike phabricator_format_relative_time, does so for more than * just the largest unit. * - * @param int Duration in seconds. - * @param int Levels to render - will render the three highest levels, ie: - * 5 h, 37 m, 1 s + * @param int $duration Duration in seconds. + * @param int $levels (optional) Levels to render. By default, renders the + * three highest levels, ie: 5 h, 37 m, 1 s * @return string Human-readable description. */ function phutil_format_relative_time_detailed($duration, $levels = 2) { @@ -73,7 +73,7 @@ function phutil_format_relative_time_detailed($duration, $levels = 2) { * Format a byte count for human consumption, e.g. "10MB" instead of * "10485760". * - * @param int Number of bytes. + * @param int $bytes Number of bytes. * @return string Human-readable description. */ function phutil_format_bytes($bytes) { @@ -88,7 +88,7 @@ function phutil_format_bytes($bytes) { /** * Parse a human-readable byte description (like "6MB") into an integer. * - * @param string Human-readable description. + * @param string $input Human-readable description. * @return int Number of represented bytes. */ function phutil_parse_bytes($input) { diff --git a/src/workflow/ArcanistDiffWorkflow.php b/src/workflow/ArcanistDiffWorkflow.php index a7d11fde..3c0afa84 100644 --- a/src/workflow/ArcanistDiffWorkflow.php +++ b/src/workflow/ArcanistDiffWorkflow.php @@ -1803,7 +1803,7 @@ EOTEXT * errors (e.g., if the user typed a reviewer name incorrectly) and a * summary of the commits themselves. * - * @param dict Local commit information. + * @param dict $local Local commit information. * @return list Complex output, see summary. * @task message */ @@ -2398,8 +2398,8 @@ EOTEXT /** * Update an arbitrary diff property. * - * @param string Diff property name. - * @param string Diff property value. + * @param string $name Diff property name. + * @param string $data Diff property value. * @return void * * @task diffprop diff --git a/src/workflow/ArcanistUnitWorkflow.php b/src/workflow/ArcanistUnitWorkflow.php index db01d000..d7b6b53f 100644 --- a/src/workflow/ArcanistUnitWorkflow.php +++ b/src/workflow/ArcanistUnitWorkflow.php @@ -352,8 +352,8 @@ EOTEXT * Raise a tailored error when a unit test engine returns results in an * invalid format. * - * @param ArcanistUnitTestEngine The engine. - * @param wild Results from the engine. + * @param ArcanistUnitTestEngine $engine The engine. + * @param wild $results Results from the engine. */ private function validateUnitEngineResults( ArcanistUnitTestEngine $engine, diff --git a/src/workflow/ArcanistWorkflow.php b/src/workflow/ArcanistWorkflow.php index 3b8242cb..9522812b 100644 --- a/src/workflow/ArcanistWorkflow.php +++ b/src/workflow/ArcanistWorkflow.php @@ -315,8 +315,8 @@ abstract class ArcanistWorkflow extends Phobject { * * NOTE: You can not call this after a conduit has been established. * - * @param string The URI to open a conduit to when @{method:establishConduit} - * is called. + * @param string $conduit_uri The URI to open a conduit to when + * @{method:establishConduit} is called. * @return this * @task conduit */ @@ -407,7 +407,8 @@ abstract class ArcanistWorkflow extends Phobject { * NOTE: You can not call this method after calling * @{method:authenticateConduit}. * - * @param dict A credential dictionary, see @{method:authenticateConduit}. + * @param dict $credentials A credential dictionary, see + * @{method:authenticateConduit}. * @return this * @task conduit */ @@ -1415,8 +1416,8 @@ abstract class ArcanistWorkflow extends Phobject { * change list is meaningless (for example, because the path is a directory * or binary file). * - * @param string Path within the repository. - * @param string Change selection mode (see ArcanistDiffHunk). + * @param string $path Path within the repository. + * @param string $mode Change selection mode (see ArcanistDiffHunk). * @return list|null List of changed line numbers, or null to indicate that * the path is not a line-oriented text file. */ @@ -1568,7 +1569,7 @@ abstract class ArcanistWorkflow extends Phobject { * Write a message to stderr so that '--json' flags or stdout which is meant * to be piped somewhere aren't disrupted. * - * @param string Message to write to stderr. + * @param string $msg Message to write to stderr. * @return void */ final protected function writeStatusMessage($msg) { @@ -1620,9 +1621,10 @@ abstract class ArcanistWorkflow extends Phobject { * This method takes the user's selections and returns the paths that the * workflow should act upon. * - * @param list List of explicitly provided paths. - * @param string|null Revision name, if provided. - * @param mask Mask of ArcanistRepositoryAPI flags to exclude. + * @param list $paths List of explicitly provided paths. + * @param string|null $rev Revision name, if provided. + * @param mask $omit_mask (optional) Mask of ArcanistRepositoryAPI + * flags to exclude. * Defaults to ArcanistRepositoryAPI::FLAG_UNTRACKED. * @return list List of paths the workflow should act on. */ @@ -1684,7 +1686,7 @@ abstract class ArcanistWorkflow extends Phobject { /** * Try to read a scratch file, if it exists and is readable. * - * @param string Scratch file name. + * @param string $path Scratch file name. * @return mixed String for file contents, or false for failure. * @task scratch */ @@ -1699,7 +1701,7 @@ abstract class ArcanistWorkflow extends Phobject { /** * Try to read a scratch JSON file, if it exists and is readable. * - * @param string Scratch file name. + * @param string $path Scratch file name. * @return array Empty array for failure. * @task scratch */ @@ -1716,8 +1718,8 @@ abstract class ArcanistWorkflow extends Phobject { * Try to write a scratch file, if there's somewhere to put it and we can * write there. * - * @param string Scratch file name to write. - * @param string Data to write. + * @param string $path Scratch file name to write. + * @param string $data Data to write. * @return bool True on success, false on failure. * @task scratch */ @@ -1733,8 +1735,8 @@ abstract class ArcanistWorkflow extends Phobject { * Try to write a scratch JSON file, if there's somewhere to put it and we can * write there. * - * @param string Scratch file name to write. - * @param array Data to write. + * @param string $path Scratch file name to write. + * @param array $data Data to write. * @return bool True on success, false on failure. * @task scratch */ @@ -1746,7 +1748,7 @@ abstract class ArcanistWorkflow extends Phobject { /** * Try to remove a scratch file. * - * @param string Scratch file name to remove. + * @param string $path Scratch file name to remove. * @return bool True if the file was removed successfully. * @task scratch */ @@ -1761,7 +1763,7 @@ abstract class ArcanistWorkflow extends Phobject { /** * Get a human-readable description of the scratch file location. * - * @param string Scratch file name. + * @param string $path Scratch file name. * @return mixed String, or false on failure. * @task scratch */ @@ -1776,7 +1778,7 @@ abstract class ArcanistWorkflow extends Phobject { /** * Get the path to a scratch file, if possible. * - * @param string Scratch file name. + * @param string $path Scratch file name. * @return mixed File path, or false on failure. * @task scratch */ @@ -2057,7 +2059,7 @@ abstract class ArcanistWorkflow extends Phobject { * of a particular class. Normally this is used to implement an `--engine` * flag from the CLI. * - * @param string Optional explicit engine class name. + * @param string $engine_class (optional) Explicit engine class name. * @return ArcanistLintEngine Constructed engine. */ protected function newLintEngine($engine_class = null) { @@ -2108,7 +2110,7 @@ abstract class ArcanistWorkflow extends Phobject { * of a particular class. Normally this is used to implement an `--engine` * flag from the CLI. * - * @param string Optional explicit engine class name. + * @param string $engine_class (optional) Explicit engine class name. * @return ArcanistUnitTestEngine Constructed engine. */ protected function newUnitTestEngine($engine_class = null) { diff --git a/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php b/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php index 82a98cbb..d7858681 100644 --- a/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php +++ b/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php @@ -51,10 +51,11 @@ final class ArcanistWorkingCopyIdentity extends Phobject { * This method attempts to be robust against all sorts of possible * misconfiguration. * - * @param string Path to load information for, usually the current working - * directory (unless running unit tests). - * @param map|null Pass `null` to locate and load a `.arcconfig` file if one - * exists. Pass a map to use it to set configuration. + * @param string $path Path to load information for, usually the current + * working directory (unless running unit tests). + * @param map|null $config Pass `null` to locate and load a `.arcconfig` + * file if one exists. Pass a map to use it to set + * configuration. * @return ArcanistWorkingCopyIdentity Constructed working copy identity. */ private static function newFromPathWithConfig($path, $config) { @@ -245,8 +246,8 @@ final class ArcanistWorkingCopyIdentity extends Phobject { * configuration sources. See @{method:getConfigFromAnySource} to read from * user configuration. * - * @param key Key to read. - * @param wild Default value if key is not found. + * @param key $key Key to read. + * @param wild $default (Optional) Default value if key is not found. * @return wild Value, or default value if not found. * * @task config diff --git a/src/xsprintf/csprintf.php b/src/xsprintf/csprintf.php index ead744a8..0818d34c 100644 --- a/src/xsprintf/csprintf.php +++ b/src/xsprintf/csprintf.php @@ -27,7 +27,7 @@ * Generally, you should invoke shell commands via @{function:execx} rather * than by calling @{function:csprintf} directly. * - * @param string sprintf()-style format string. + * @param string $pattern sprintf()-style format string. * @param ... Zero or more arguments. * @return PhutilCommandString Formatted string, escaped appropriately for * shell contexts. @@ -40,8 +40,8 @@ function csprintf($pattern /* , ... */) { /** * Version of @{function:csprintf} that takes a vector of arguments. * - * @param string sprintf()-style format string. - * @param list List of zero or more arguments to csprintf(). + * @param string $pattern sprintf()-style format string. + * @param list $argv List of zero or more arguments to csprintf(). * @return PhutilCommandString Formatted string, escaped appropriately for * shell contexts. */ diff --git a/src/xsprintf/pregsprintf.php b/src/xsprintf/pregsprintf.php index 05ac86f4..f227b6e4 100644 --- a/src/xsprintf/pregsprintf.php +++ b/src/xsprintf/pregsprintf.php @@ -9,9 +9,9 @@ * %R Raw * Inserts a raw regular expression. * - * @param string sprintf()-style format string. - * @param string Flags to use with the regular expression. - * @param ... Zero or more arguments. + * @param string $pattern sprintf()-style format string. + * @param string (optional) Flags to use with the regular expression. + * @param ... (optional) Zero or more arguments. * @return string Formatted string. */ function pregsprintf($pattern /* , ... */) { diff --git a/src/xsprintf/xsprintf.php b/src/xsprintf/xsprintf.php index cdc0c9ed..ec2a6a08 100644 --- a/src/xsprintf/xsprintf.php +++ b/src/xsprintf/xsprintf.php @@ -26,10 +26,10 @@ * ...the callback will be invoked twice, at string positions 5 ("M") and 19 * ("C"), with values "moon" and "cheese" respectively. * - * @param string The name of a callback to pass conversions to. - * @param wild Optional userdata to pass to the callback. For + * @param string $callback The name of a callback to pass conversions to. + * @param wild $userdata Optional userdata to pass to the callback. For * @{function:qsprintf}, this is the database connection. - * @param list List of arguments, with the `sprintf()` pattern in + * @param list $argv List of arguments, with the `sprintf()` pattern in * position 0. * @return string Formatted string. */ @@ -118,12 +118,12 @@ function xsprintf($callback, $userdata, array $argv) { * For example implementations, see @{function:xsprintf_command}, * @{function:xsprintf_javascript} and @{function:xsprintf_query}. * - * @param wild Arbitrary, optional userdata. This is whatever userdata - * was passed to @{function:xsprintf}. - * @param string The pattern string being parsed. - * @param int The current character position in the string. - * @param wild The value to convert. - * @param int The string length. + * @param wild $userdata Arbitrary, optional userdata. This is whatever + * userdata was passed to @{function:xsprintf}. + * @param string &$pattern The pattern string being parsed. + * @param int &$pos The current character position in the string. + * @param wild &$value The value to convert. + * @param int &$length The string length. */ function xsprintf_callback_example( $userdata,