From 9d087e8bf059875aa72c5ac34518a57510fba30a Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Fri, 17 Oct 2025 01:00:48 +0200 Subject: [PATCH] Misc PhpDoc additions or improvements Summary: Side effect of random stuff I've been poking and trying to understand what it may do. Test Plan: Read code, check parameter and return types, e.g. via gettype() or get_class(). Reviewers: O1 Blessed Committers, valerio.bozzolan, mainframe98 Reviewed By: O1 Blessed Committers, valerio.bozzolan, mainframe98 Subscribers: mainframe98, tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D26433 --- .../auth/revoker/PhabricatorAuthRevoker.php | 3 ++ .../remarkup/DiffusionCommitRemarkupRule.php | 3 ++ .../DiffusionRepositoryByIDRemarkupRule.php | 3 ++ .../DiffusionRepositoryRemarkupRule.php | 3 ++ .../mail/PhabricatorPeopleMailEngine.php | 3 ++ .../people/query/PhabricatorPeopleQuery.php | 4 +++ .../pholio/remarkup/PholioRemarkupRule.php | 3 ++ .../project/query/PhabricatorProjectQuery.php | 4 +++ .../project/remarkup/ProjectRemarkupRule.php | 3 ++ .../PhabricatorRepositoryGraphCache.php | 2 +- .../storage/PhabricatorRepository.php | 16 +++++++++ ...habricatorApplicationTransactionEditor.php | 3 ++ .../PhabricatorTypeaheadDatasource.php | 21 +++++++++++- .../rule/PhabricatorObjectRemarkupRule.php | 33 +++++++++++++++++++ src/view/phui/PHUIPropertyListView.php | 6 ++++ 15 files changed, 108 insertions(+), 2 deletions(-) diff --git a/src/applications/auth/revoker/PhabricatorAuthRevoker.php b/src/applications/auth/revoker/PhabricatorAuthRevoker.php index a18cd39ad5..b9208d7311 100644 --- a/src/applications/auth/revoker/PhabricatorAuthRevoker.php +++ b/src/applications/auth/revoker/PhabricatorAuthRevoker.php @@ -28,6 +28,9 @@ abstract class PhabricatorAuthRevoker return $this->getPhobjectClassConstant('REVOKERKEY'); } + /** + * @return array + */ final public static function getAllRevokers() { return id(new PhutilClassMapQuery()) ->setAncestorClass(self::class) diff --git a/src/applications/diffusion/remarkup/DiffusionCommitRemarkupRule.php b/src/applications/diffusion/remarkup/DiffusionCommitRemarkupRule.php index 4d2d130c32..f52ef01e9d 100644 --- a/src/applications/diffusion/remarkup/DiffusionCommitRemarkupRule.php +++ b/src/applications/diffusion/remarkup/DiffusionCommitRemarkupRule.php @@ -10,6 +10,9 @@ final class DiffusionCommitRemarkupRule extends PhabricatorObjectRemarkupRule { return true; } + /** + * @return string Regex which defines a valid object ID + */ protected function getObjectIDPattern() { return PhabricatorRepositoryCommitPHIDType::getCommitObjectNamePattern(); } diff --git a/src/applications/diffusion/remarkup/DiffusionRepositoryByIDRemarkupRule.php b/src/applications/diffusion/remarkup/DiffusionRepositoryByIDRemarkupRule.php index c5b76fd3a3..896d2a75b2 100644 --- a/src/applications/diffusion/remarkup/DiffusionRepositoryByIDRemarkupRule.php +++ b/src/applications/diffusion/remarkup/DiffusionRepositoryByIDRemarkupRule.php @@ -7,6 +7,9 @@ final class DiffusionRepositoryByIDRemarkupRule return 'R'; } + /** + * @return string Regex which defines a valid object ID + */ protected function getObjectIDPattern() { return '[0-9]+'; } diff --git a/src/applications/diffusion/remarkup/DiffusionRepositoryRemarkupRule.php b/src/applications/diffusion/remarkup/DiffusionRepositoryRemarkupRule.php index c845b64a46..cfbf6bd07f 100644 --- a/src/applications/diffusion/remarkup/DiffusionRepositoryRemarkupRule.php +++ b/src/applications/diffusion/remarkup/DiffusionRepositoryRemarkupRule.php @@ -7,6 +7,9 @@ final class DiffusionRepositoryRemarkupRule return 'r'; } + /** + * @return string Regex which defines a valid object ID + */ protected function getObjectIDPattern() { return '[A-Z]+'; } diff --git a/src/applications/people/mail/PhabricatorPeopleMailEngine.php b/src/applications/people/mail/PhabricatorPeopleMailEngine.php index 6b7aa7818e..9f578a5f70 100644 --- a/src/applications/people/mail/PhabricatorPeopleMailEngine.php +++ b/src/applications/people/mail/PhabricatorPeopleMailEngine.php @@ -25,6 +25,9 @@ abstract class PhabricatorPeopleMailEngine return $this; } + /** + * @return PhabricatorUser + */ final public function getRecipient() { if (!$this->recipient) { throw new PhutilInvalidStateException('setRecipient'); diff --git a/src/applications/people/query/PhabricatorPeopleQuery.php b/src/applications/people/query/PhabricatorPeopleQuery.php index c5e44b3778..7ead8c8264 100644 --- a/src/applications/people/query/PhabricatorPeopleQuery.php +++ b/src/applications/people/query/PhabricatorPeopleQuery.php @@ -100,6 +100,10 @@ final class PhabricatorPeopleQuery return $this; } + /** + * Set a prefix to query in a LIKE clause of the query + * @param array $prefixes String prefixes to search for + */ public function withNamePrefixes(array $prefixes) { $this->namePrefixes = $prefixes; return $this; diff --git a/src/applications/pholio/remarkup/PholioRemarkupRule.php b/src/applications/pholio/remarkup/PholioRemarkupRule.php index 00025b6326..f33be810a1 100644 --- a/src/applications/pholio/remarkup/PholioRemarkupRule.php +++ b/src/applications/pholio/remarkup/PholioRemarkupRule.php @@ -6,6 +6,9 @@ final class PholioRemarkupRule extends PhabricatorObjectRemarkupRule { return 'M'; } + /** + * @return string Regex which defines a valid object ID + */ protected function getObjectIDPattern() { // Match "M123", "M123/456", and "M123/456/". Users can hit the latter // forms when clicking comment anchors on a mock page. diff --git a/src/applications/project/query/PhabricatorProjectQuery.php b/src/applications/project/query/PhabricatorProjectQuery.php index b901036726..574fd0c5ed 100644 --- a/src/applications/project/query/PhabricatorProjectQuery.php +++ b/src/applications/project/query/PhabricatorProjectQuery.php @@ -83,6 +83,10 @@ final class PhabricatorProjectQuery return $this; } + /** + * Set a prefix to query in a LIKE clause of the query + * @param array $prefixes String prefixes to search for + */ public function withNamePrefixes(array $prefixes) { $this->namePrefixes = $prefixes; return $this; diff --git a/src/applications/project/remarkup/ProjectRemarkupRule.php b/src/applications/project/remarkup/ProjectRemarkupRule.php index 98e6d0f86f..f280b68ddc 100644 --- a/src/applications/project/remarkup/ProjectRemarkupRule.php +++ b/src/applications/project/remarkup/ProjectRemarkupRule.php @@ -21,6 +21,9 @@ final class ProjectRemarkupRule extends PhabricatorObjectRemarkupRule { return $tag; } + /** + * @return string Regex which defines a valid object ID + */ protected function getObjectIDPattern() { // NOTE: This rule matches monograms with internal periods, // like `#domain.com`, but does not match monograms with terminal diff --git a/src/applications/repository/graphcache/PhabricatorRepositoryGraphCache.php b/src/applications/repository/graphcache/PhabricatorRepositoryGraphCache.php index e725211a8e..53b304ce97 100644 --- a/src/applications/repository/graphcache/PhabricatorRepositoryGraphCache.php +++ b/src/applications/repository/graphcache/PhabricatorRepositoryGraphCache.php @@ -62,7 +62,7 @@ final class PhabricatorRepositoryGraphCache extends Phobject { /** - * Search the graph cache for the most modification to a path. + * Search the graph cache for the most recent modification to a path. * * @param int $commit_id The commit ID to search ancestors of. * @param int $path_id The path ID to search for changes to. diff --git a/src/applications/repository/storage/PhabricatorRepository.php b/src/applications/repository/storage/PhabricatorRepository.php index f4a6eaf949..030b65b793 100644 --- a/src/applications/repository/storage/PhabricatorRepository.php +++ b/src/applications/repository/storage/PhabricatorRepository.php @@ -1053,6 +1053,10 @@ final class PhabricatorRepository extends PhabricatorRepositoryDAO return array_keys($this->getDetail('close-commits-filter', array())); } + /** + * Set Refs which should not automatically get closed via commits. + * This usually includes the name of the main development branch. + */ public function setPermanentRefRules(array $rules) { $rules = array_fill_keys($rules, true); $this->setDetail('close-commits-filter', $rules); @@ -1063,6 +1067,18 @@ final class PhabricatorRepository extends PhabricatorRepositoryDAO return array_keys($this->getDetail('branch-filter', array())); } + /** + * The "Track Only" feature has been deprecated since 2019 in + * https://secure.phabricator.com/T13277 and + * https://we.phorge.it/rPc33f544e741775c52c223bc435331bc3422231ee + * "Track Only" rules can be moved to "Permanent Refs" and/or "Fetch Only". + * The only use case left may be for performance reasons limiting what is + * fetched from an observed remote with tens of thousands of branches. + * + * You can find all repositories which still use this deprecated setting via + * SELECT * FROM phabricator_repository.repository WHERE + * JSON_LENGTH(JSON_EXTRACT(details, '$.branch-filter')) > 0; + */ public function setTrackOnlyRules(array $rules) { $rules = array_fill_keys($rules, true); $this->setDetail('branch-filter', $rules); diff --git a/src/applications/transactions/editor/PhabricatorApplicationTransactionEditor.php b/src/applications/transactions/editor/PhabricatorApplicationTransactionEditor.php index 46cf482963..c1d99c42c5 100644 --- a/src/applications/transactions/editor/PhabricatorApplicationTransactionEditor.php +++ b/src/applications/transactions/editor/PhabricatorApplicationTransactionEditor.php @@ -5363,6 +5363,9 @@ abstract class PhabricatorApplicationTransactionEditor return true; } + /** + * Get an entire object's history (via the "!history" email command) + */ private function buildHistoryMail(PhabricatorLiskDAO $object) { $viewer = $this->requireActor(); $recipient_phid = $this->getActingAsPHID(); diff --git a/src/applications/typeahead/datasource/PhabricatorTypeaheadDatasource.php b/src/applications/typeahead/datasource/PhabricatorTypeaheadDatasource.php index 2e01034c64..6189a09c92 100644 --- a/src/applications/typeahead/datasource/PhabricatorTypeaheadDatasource.php +++ b/src/applications/typeahead/datasource/PhabricatorTypeaheadDatasource.php @@ -198,6 +198,10 @@ abstract class PhabricatorTypeaheadDatasource extends Phobject { return array_values($tokens); } + /** + * Break search term entered in typeahead field into string tokens + * @return array + */ public function getTokens() { return self::tokenizeString($this->getRawQuery()); } @@ -379,6 +383,12 @@ abstract class PhabricatorTypeaheadDatasource extends Phobject { /** + * Return available function tokens for this typeahead datasource, with each + * key being the function name (e.g. any, not, null, only) and each value + * being another array containing name, summary, description. See the + * "Function Quick Reference" in the Typeahead Function Help for details. + * + * @return array|null> * @task functions */ public function getDatasourceFunctions() { @@ -387,6 +397,12 @@ abstract class PhabricatorTypeaheadDatasource extends Phobject { /** + * Return all function tokens for typeahead datasources, with each key being + * the function name (e.g. any, not, null, only) and each value being another + * array containing name, summary, description. See the + * "Function Quick Reference" in the Typeahead Function Help for details. + * + * @return array> * @task functions */ public function getAllDatasourceFunctions() { @@ -616,7 +632,10 @@ abstract class PhabricatorTypeaheadDatasource extends Phobject { /** - * @return array + * Get the function tokens entered in the typeahead field, + * e.g. "not" or "any" + * + * @return array * @task functions */ public function getFunctionStack() { diff --git a/src/infrastructure/markup/rule/PhabricatorObjectRemarkupRule.php b/src/infrastructure/markup/rule/PhabricatorObjectRemarkupRule.php index 1dbf47cc51..cc89d69e49 100644 --- a/src/infrastructure/markup/rule/PhabricatorObjectRemarkupRule.php +++ b/src/infrastructure/markup/rule/PhabricatorObjectRemarkupRule.php @@ -20,6 +20,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { return preg_match('/^\w/', $prefix); } + /** + * @return string Regex which defines a valid object ID + */ protected function getObjectIDPattern() { return '[1-9]\d*'; } @@ -35,6 +38,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { return $this->getObjectNamePrefix().$id; } + /** + * @return array + */ protected function loadHandles(array $objects) { $phids = mpull($objects, 'getPHID'); @@ -63,6 +69,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { return $uri; } + /** + * @return string|PhutilSafeHTML|PHUITagView + */ protected function renderObjectRefForAnyMedia( $object, PhabricatorObjectHandle $handle, @@ -88,6 +97,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { } + /** + * @return PHUITagView + */ protected function renderObjectRef( $object, PhabricatorObjectHandle $handle, @@ -111,6 +123,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { return $this->renderHovertag($text, $href, $attr); } + /** + * @return string|PhutilSafeHTML|PHUITagView + */ protected function renderObjectEmbedForAnyMedia( $object, PhabricatorObjectHandle $handle, @@ -135,6 +150,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { return $this->renderObjectEmbed($object, $handle, $options); } + /** + * @return PhutilSafeHTML|string|array + */ protected function renderObjectEmbed( $object, PhabricatorObjectHandle $handle, @@ -142,6 +160,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { return $this->renderDefaultObjectEmbed($object, $handle); } + /** + * @return PhutilSafeHTML|string|array + */ final protected function renderDefaultObjectEmbed( $object, PhabricatorObjectHandle $handle) { @@ -157,6 +178,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { return $this->renderHovertag($name, $href, $attr); } + /** + * @return PhutilSafeHTML + */ protected function renderObjectTagForMail( $text, $href, @@ -182,6 +206,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { $text); } + /** + * @return PhutilSafeHTML|string|array + */ protected function renderHovertag($name, $href, array $attr = array()) { return id(new PHUITagView()) ->setName($name) @@ -206,6 +233,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { return $text; } + /** + * @return string Regex + */ private function getObjectEmbedPattern() { if ($this->embedPattern === null) { $prefix = $this->getObjectNamePrefix(); @@ -219,6 +249,9 @@ abstract class PhabricatorObjectRemarkupRule extends PhutilRemarkupRule { return $this->embedPattern; } + /** + * @return string Regex + */ private function getObjectReferencePattern() { if ($this->referencePattern === null) { $prefix = $this->getObjectNamePrefix(); diff --git a/src/view/phui/PHUIPropertyListView.php b/src/view/phui/PHUIPropertyListView.php index dfa98edd98..9c444297c2 100644 --- a/src/view/phui/PHUIPropertyListView.php +++ b/src/view/phui/PHUIPropertyListView.php @@ -109,6 +109,12 @@ final class PHUIPropertyListView extends AphrontView { $this->invokedWillRenderEvent = true; } + /** + * Whether there are any properties to display in the list view. + * Useful to e.g. display an explanation via PHUIInfoView if false. + * + * @return bool + */ public function hasAnyProperties() { $this->invokeWillRenderEvent(); -- 2.51.2