Correct PHPDoc @return value of methods that can return null

Summary:
Make the PHPDoc @return say so when the method can also return null instead of an, array, string, or int.
(In case of `getCommandHelp()`, return an empty string as child implementations do return strings.)

Test Plan: Read the code; run static code analysis.

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/D25805

src/filesystem/Filesystem.php

@@ -1091,7 +1091,7 @@ final class Filesystem extends Phobject {
    * the configured `$PATH`.
    *
    * @param   string  $binary Binary name, like `'git'` or `'svn'`.
-   * @return  string  The full binary path if it is present, or null.
+   * @return  string|null  The full binary path if it is present, or null.
    * @task    exec
    */
   public static function resolveBinary($binary) {

src/future/http/BaseHTTPFuture.php

@@ -425,7 +425,7 @@ abstract class BaseHTTPFuture extends Future {
    *
    * @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.
+   * @return string|null Value of the header or null if not found.
    * @task resolve
    */
   public static function getHeader(array $headers, $search) {

src/lint/ArcanistLintMessage.php

@@ -274,7 +274,7 @@ final class ArcanistLintMessage extends Phobject {
    *
    * @param mixed $value Integer or digit string.
    * @param mixed $caller
-   * @return int Integer.
+   * @return int|null Integer, or null if $value is null
    */
   private function validateInteger($value, $caller) {
     if ($value === null) {

src/parser/ArcanistDiffParser.php

@@ -1330,7 +1330,7 @@ final class ArcanistDiffParser extends Phobject {
    * recovered by later rename detection codepaths.
    *
    * @param string $paths Text from a diff line after "diff --git ".
-   * @return string Filename being altered, or null for a rename.
+   * @return string|null Filename being altered, or null for a rename.
    */
   public static function extractGitCommonFilename($paths) {
     $matches = null;

src/unit/ArcanistUnitTestResult.php

@@ -133,7 +133,8 @@ final class ArcanistUnitTestResult extends Phobject {
    * Merge several coverage reports into a comprehensive coverage report.
    *
    * @param list $coverage List of coverage report strings.
-   * @return string Cumulative coverage report.
+   * @return string|null Cumulative coverage report, or null if $coverage is
+   *   null.
    */
   public static function mergeCoverage(array $coverage) {
     if (empty($coverage)) {

src/unit/engine/CSharpToolsTestEngine.php

@@ -162,7 +162,7 @@ final class CSharpToolsTestEngine extends XUnitTestEngine {
    * so we cache it in case it's requested again.
    *
    * @param  string  $cover_file The name of the coverage file.
-   * @return array   Code coverage results, or null if not cached.
+   * @return array|null   Code coverage results, or null if not cached.
    */
   private function getCachedResultsIfPossible($cover_file) {
     if ($this->cachedResults == null) {

src/unit/engine/XUnitTestEngine.php

@@ -397,7 +397,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine {
    *
    * @param  string  $coverage The name of the coverage file if one was
    *                 provided by `buildTestFuture`.
-   * @return array   Code coverage results, or null.
+   * @return array|null   Code coverage results, or null.
    */
   protected function parseCoverageResult($coverage) {
     return null;

src/utils/PhutilRope.php

@@ -55,7 +55,7 @@ final class PhutilRope extends Phobject {
   /**
    * Get an arbitrary, nonempty prefix of the rope.
    *
-   * @return string Some rope prefix.
+   * @return string|null Some rope prefix.
    */
   public function getAnyPrefix() {
     $result = reset($this->buffers);

src/utils/viewutils.php

@@ -89,7 +89,7 @@ function phutil_format_bytes($bytes) {
  * Parse a human-readable byte description (like "6MB") into an integer.
  *
  * @param string  $input Human-readable description.
- * @return int    Number of represented bytes.
+ * @return int|null  Number of represented bytes.
  */
 function phutil_parse_bytes($input) {
   $bytes = trim($input);