diff --git a/src/aphront/configuration/AphrontApplicationConfiguration.php b/src/aphront/configuration/AphrontApplicationConfiguration.php
--- a/src/aphront/configuration/AphrontApplicationConfiguration.php
+++ b/src/aphront/configuration/AphrontApplicationConfiguration.php
@@ -512,8 +512,8 @@
*
* @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) {
diff --git a/src/aphront/httpparametertype/AphrontHTTPParameterType.php b/src/aphront/httpparametertype/AphrontHTTPParameterType.php
--- a/src/aphront/httpparametertype/AphrontHTTPParameterType.php
+++ b/src/aphront/httpparametertype/AphrontHTTPParameterType.php
@@ -299,7 +299,7 @@
*
* 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
--- a/src/applications/auth/constants/PhabricatorCookies.php
+++ b/src/applications/auth/constants/PhabricatorCookies.php
@@ -155,8 +155,9 @@
/**
* 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
*/
diff --git a/src/applications/config/option/PhabricatorApplicationConfigOptions.php b/src/applications/config/option/PhabricatorApplicationConfigOptions.php
--- a/src/applications/config/option/PhabricatorApplicationConfigOptions.php
+++ b/src/applications/config/option/PhabricatorApplicationConfigOptions.php
@@ -67,7 +67,7 @@
*
* @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
--- a/src/applications/diffusion/request/DiffusionRequest.php
+++ b/src/applications/diffusion/request/DiffusionRequest.php
@@ -56,8 +56,9 @@
* - `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 @@
* @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
--- a/src/applications/metamta/command/MetaMTAEmailTransactionCommand.php
+++ b/src/applications/metamta/command/MetaMTAEmailTransactionCommand.php
@@ -34,7 +34,7 @@
*
* 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
--- a/src/applications/phame/storage/PhameBlog.php
+++ b/src/applications/phame/storage/PhameBlog.php
@@ -111,9 +111,9 @@
* 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
--- a/src/applications/policy/capability/PhabricatorPolicyCapability.php
+++ b/src/applications/policy/capability/PhabricatorPolicyCapability.php
@@ -36,8 +36,8 @@
* - 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
--- a/src/applications/transactions/editfield/PhabricatorEditField.php
+++ b/src/applications/transactions/editfield/PhabricatorEditField.php
@@ -575,7 +575,7 @@
*
* @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
--- a/src/infrastructure/customfield/field/PhabricatorCustomField.php
+++ b/src/infrastructure/customfield/field/PhabricatorCustomField.php
@@ -587,7 +587,7 @@
* 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 @@
*
* 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
--- a/src/infrastructure/edges/query/PhabricatorEdgeQuery.php
+++ b/src/infrastructure/edges/query/PhabricatorEdgeQuery.php
@@ -142,7 +142,7 @@
* @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
--- a/src/infrastructure/query/policy/PhabricatorCursorPagedPolicyAwareQuery.php
+++ b/src/infrastructure/query/policy/PhabricatorCursorPagedPolicyAwareQuery.php
@@ -433,7 +433,7 @@
* 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 @@
* @{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) {