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

src/aphront/configuration/AphrontApplicationConfiguration.php

@@ -512,8 +512,8 @@ final class AphrontApplicationConfiguration
    *
    * @param list<AphrontRoutingMap> $maps List of routing maps.
    * @param string $path Path to route.
-   * @return pair<AphrontController,dict> Controller and dictionary of request
-   *                                      parameters.
+   * @return pair<AphrontController,dict>|null Controller and dictionary of
+   *   request parameters, or null if no paths to route were found.
    * @task routing
    */
   private function routePath(array $maps, $path) {

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() {

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<string>  List of timestamp and URI.
+   * @param   string                 $cookie Raw cookie value.
+   * @return  list<int,string>|null  List of timestamp and URI, or null if the
+   *   cookie is empty or null.
    *
    * @task next
    */

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(

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(

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() {

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/';

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;

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;

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() {

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())

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) {