From 403fb8a852146d569b5e6978be03a740a00144ee Mon Sep 17 00:00:00 2001 From: Andre Klapper Date: Fri, 11 Apr 2025 11:48:00 +0200 Subject: [PATCH] PHPDoc: Fix @return string for methods which can also return null Summary: Correct docs. Test Plan: Read the method code, run static code analysis (PHPStan) which complains "should return string but returns null". 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/D25958 --- .../configuration/AphrontApplicationConfiguration.php | 4 ++-- .../httpparametertype/AphrontHTTPParameterType.php | 2 +- src/applications/auth/constants/PhabricatorCookies.php | 5 +++-- .../config/option/PhabricatorApplicationConfigOptions.php | 2 +- src/applications/diffusion/request/DiffusionRequest.php | 8 +++++--- .../metamta/command/MetaMTAEmailTransactionCommand.php | 2 +- src/applications/phame/storage/PhameBlog.php | 4 ++-- .../policy/capability/PhabricatorPolicyCapability.php | 4 ++-- .../transactions/editfield/PhabricatorEditField.php | 2 +- .../customfield/field/PhabricatorCustomField.php | 7 +++---- src/infrastructure/edges/query/PhabricatorEdgeQuery.php | 2 +- .../policy/PhabricatorCursorPagedPolicyAwareQuery.php | 5 +++-- 12 files changed, 25 insertions(+), 22 deletions(-) diff --git a/src/aphront/configuration/AphrontApplicationConfiguration.php b/src/aphront/configuration/AphrontApplicationConfiguration.php index af05993e2b..12917c34f4 100644 --- a/src/aphront/configuration/AphrontApplicationConfiguration.php +++ b/src/aphront/configuration/AphrontApplicationConfiguration.php @@ -512,8 +512,8 @@ final class AphrontApplicationConfiguration * * @param list $maps List of routing maps. * @param string $path Path to route. - * @return pair Controller and dictionary of request - * parameters. + * @return pair|null Controller and dictionary of + * request parameters, or null if no paths to route were found. * @task routing */ private function routePath(array $maps, $path) { diff --git a/src/aphront/httpparametertype/AphrontHTTPParameterType.php b/src/aphront/httpparametertype/AphrontHTTPParameterType.php index d149ee01dc..c9c415bf78 100644 --- a/src/aphront/httpparametertype/AphrontHTTPParameterType.php +++ b/src/aphront/httpparametertype/AphrontHTTPParameterType.php @@ -299,7 +299,7 @@ abstract class AphrontHTTPParameterType extends Phobject { * * See @{method:getDefaultValue}. If unspecified, the default is `null`. * - * @return wild Default value. + * @return wild|null Default value (null if unspecified). * @task impl */ protected function getParameterDefault() { diff --git a/src/applications/auth/constants/PhabricatorCookies.php b/src/applications/auth/constants/PhabricatorCookies.php index 7a54eb3dc0..7332409ca4 100644 --- a/src/applications/auth/constants/PhabricatorCookies.php +++ b/src/applications/auth/constants/PhabricatorCookies.php @@ -155,8 +155,9 @@ final class PhabricatorCookies extends Phobject { /** * Parse a Next URI cookie into its components. * - * @param string $cookie Raw cookie value. - * @return list List of timestamp and URI. + * @param string $cookie Raw cookie value. + * @return list|null List of timestamp and URI, or null if the + * cookie is empty or null. * * @task next */ diff --git a/src/applications/config/option/PhabricatorApplicationConfigOptions.php b/src/applications/config/option/PhabricatorApplicationConfigOptions.php index e8aea20ba7..babe52341c 100644 --- a/src/applications/config/option/PhabricatorApplicationConfigOptions.php +++ b/src/applications/config/option/PhabricatorApplicationConfigOptions.php @@ -67,7 +67,7 @@ abstract class PhabricatorApplicationConfigOptions extends Phobject { * * @param PhabricatorConfigOption $option Option being rendered. * @param AphrontRequest $request Active request. - * @return wild Additional contextual description + * @return wild|null Additional contextual description * information. */ public function renderContextualDescription( diff --git a/src/applications/diffusion/request/DiffusionRequest.php b/src/applications/diffusion/request/DiffusionRequest.php index 62107c74fe..5eb113e0f8 100644 --- a/src/applications/diffusion/request/DiffusionRequest.php +++ b/src/applications/diffusion/request/DiffusionRequest.php @@ -56,8 +56,9 @@ abstract class DiffusionRequest extends Phobject { * - `commit` Optional, commit identifier. * - `line` Optional, line range. * - * @param map $data See documentation. - * @return DiffusionRequest New request object. + * @param map $data See documentation. + * @return DiffusionRequest|null New request object, or null if none is + * found. * @task new */ final public static function newFromDictionary(array $data) { @@ -136,7 +137,8 @@ abstract class DiffusionRequest extends Phobject { * @param string $identifier Repository identifier. * @param PhabricatorUser $viewer Viewing user. * @param bool $need_edit (optional) - * @return DiffusionRequest New request object. + * @return DiffusionRequest New request object, or null if no repository is + * found. * @task new */ private static function newFromIdentifier( diff --git a/src/applications/metamta/command/MetaMTAEmailTransactionCommand.php b/src/applications/metamta/command/MetaMTAEmailTransactionCommand.php index 4a7102595f..511edb85d3 100644 --- a/src/applications/metamta/command/MetaMTAEmailTransactionCommand.php +++ b/src/applications/metamta/command/MetaMTAEmailTransactionCommand.php @@ -34,7 +34,7 @@ abstract class MetaMTAEmailTransactionCommand extends Phobject { * * This can be as long as necessary to explain the command. * - * @return string Human-readable remarkup of whatever length is desired. + * @return string|null Human-readable remarkup of whatever length is desired. * @task docs */ public function getCommandDescription() { diff --git a/src/applications/phame/storage/PhameBlog.php b/src/applications/phame/storage/PhameBlog.php index 8ab5c2747e..0092d07d9a 100644 --- a/src/applications/phame/storage/PhameBlog.php +++ b/src/applications/phame/storage/PhameBlog.php @@ -111,9 +111,9 @@ final class PhameBlog extends PhameDAO * Makes sure a given custom blog uri is properly configured in DNS * to point at this Phabricator instance. If there is an error in * the configuration, return a string describing the error and how - * to fix it. If there is no error, return an empty string. + * to fix it. If there is no error, return null. * - * @return string + * @return string|null */ public function validateCustomDomain($domain_full_uri) { $example_domain = 'http://blog.example.com/'; diff --git a/src/applications/policy/capability/PhabricatorPolicyCapability.php b/src/applications/policy/capability/PhabricatorPolicyCapability.php index 2bb1ce4238..7792ee5041 100644 --- a/src/applications/policy/capability/PhabricatorPolicyCapability.php +++ b/src/applications/policy/capability/PhabricatorPolicyCapability.php @@ -36,8 +36,8 @@ abstract class PhabricatorPolicyCapability extends Phobject { * - You do not have permission to edit this object. * - You do not have permission to create new tasks. * - * @return string Human-readable name describing what failing a check for this - * capability prevents the user from doing. + * @return string|null Human-readable name describing what failing a check + * for this capability prevents the user from doing. */ public function describeCapabilityRejection() { return null; diff --git a/src/applications/transactions/editfield/PhabricatorEditField.php b/src/applications/transactions/editfield/PhabricatorEditField.php index 4e17bf006c..1f7ac41b2a 100644 --- a/src/applications/transactions/editfield/PhabricatorEditField.php +++ b/src/applications/transactions/editfield/PhabricatorEditField.php @@ -575,7 +575,7 @@ abstract class PhabricatorEditField extends Phobject { * * @param AphrontRequest $request Request to read from. * @param string $key Key to read. - * @return wild Value read from request. + * @return wild|null Value read from request. */ protected function getInitialValueFromSubmit(AphrontRequest $request, $key) { return null; diff --git a/src/infrastructure/customfield/field/PhabricatorCustomField.php b/src/infrastructure/customfield/field/PhabricatorCustomField.php index 436db6ab02..b5c83f1eed 100644 --- a/src/infrastructure/customfield/field/PhabricatorCustomField.php +++ b/src/infrastructure/customfield/field/PhabricatorCustomField.php @@ -587,7 +587,7 @@ abstract class PhabricatorCustomField extends Phobject { * If the field value is a scalar, it can be returned unmodified. If not, * it should be serialized (for example, using JSON). * - * @return string Serialized field value. + * @return string|null Serialized field value. * @task storage */ public function getValueForStorage() { @@ -686,9 +686,8 @@ abstract class PhabricatorCustomField extends Phobject { * * The value of the index is not used. * - * Return null from this method if the field can not be ordered. - * - * @return PhabricatorCustomFieldIndexStorage A single index to order by. + * @return PhabricatorCustomFieldIndexStorage|null A single index to order + * by, or null if this field cannot be ordered. * @task appsearch */ public function buildOrderIndex() { diff --git a/src/infrastructure/edges/query/PhabricatorEdgeQuery.php b/src/infrastructure/edges/query/PhabricatorEdgeQuery.php index 40894d56ec..ca93e22ac7 100644 --- a/src/infrastructure/edges/query/PhabricatorEdgeQuery.php +++ b/src/infrastructure/edges/query/PhabricatorEdgeQuery.php @@ -142,7 +142,7 @@ final class PhabricatorEdgeQuery extends PhabricatorQuery { * @param string $src_phid Source PHID. * @param string $edge_type Edge type constant. * @param string $dest_phid Destination PHID. - * @return wild Edge annotation (or null). + * @return wild|null Edge annotation, or null. */ public static function loadSingleEdgeData($src_phid, $edge_type, $dest_phid) { $edges = id(new PhabricatorEdgeQuery()) diff --git a/src/infrastructure/query/policy/PhabricatorCursorPagedPolicyAwareQuery.php b/src/infrastructure/query/policy/PhabricatorCursorPagedPolicyAwareQuery.php index f20a29f19b..5b7d4f9742 100644 --- a/src/infrastructure/query/policy/PhabricatorCursorPagedPolicyAwareQuery.php +++ b/src/infrastructure/query/policy/PhabricatorCursorPagedPolicyAwareQuery.php @@ -433,7 +433,7 @@ abstract class PhabricatorCursorPagedPolicyAwareQuery * this is the case, return the alias for the primary table the query * uses; generally the object table which has `id` and `phid` columns. * - * @return string Alias for the primary table. + * @return string|null Alias for the primary table, or null. */ protected function getPrimaryTableAlias() { return null; @@ -3140,7 +3140,8 @@ abstract class PhabricatorCursorPagedPolicyAwareQuery * @{method:withSpacePHIDs}. * * @param AphrontDatabaseConnection $conn Database connection. - * @return string Part of a WHERE clause. + * @return string|null Part of a WHERE clause, or null when there is no + * object or the object is not an instance of PhabricatorSpacesInterface. * @task spaces */ private function buildSpacesWhereClause(AphrontDatabaseConnection $conn) {