Promote 2024.35 to stable

src/channel/PhutilChannel.php

@@ -65,7 +65,7 @@ abstract class PhutilChannel extends Phobject {
    *
    * The default implementation accepts bytes.
    *
-   * @param   wild  Data to write to the channel, normally bytes.
+   * @param   wild $bytes Data to write to the channel, normally bytes.
    * @return  this
    *
    * @task io
@@ -90,8 +90,8 @@ abstract class PhutilChannel extends Phobject {
    * Wait for any activity on a list of channels. Convenience wrapper around
    * @{method:waitForActivity}.
    *
-   * @param   list<PhutilChannel>   A list of channels to wait for.
+   * @param   list<PhutilChannel>   $channels A list of channels to wait for.
-   * @param   dict                  Options, see above.
+   * @param   dict                  $options (optional) Options, see above.
    * @return  void
    *
    * @task wait
@@ -119,8 +119,9 @@ abstract class PhutilChannel extends Phobject {
    * NOTE: Extra streams must be //streams//, not //sockets//, because this
    * method uses `stream_select()`, not `socket_select()`.
    *
-   * @param list<PhutilChannel> List of channels to wait for reads on.
+   * @param list<PhutilChannel> $reads List of channels to wait for reads on.
-   * @param list<PhutilChannel> List of channels to wait for writes on.
+   * @param list<PhutilChannel> $writes List of channels to wait for writes on.
+   * @param   dict              $options (optional) Options, see above.
    * @return void
    *
    * @task wait
@@ -245,7 +246,7 @@ abstract class PhutilChannel extends Phobject {
    * Set a channel name. This is primarily intended to allow you to debug
    * channel code more easily, by naming channels something meaningful.
    *
-   * @param string Channel name.
+   * @param string $name Channel name.
    * @return this
    *
    * @task impl
@@ -313,7 +314,7 @@ abstract class PhutilChannel extends Phobject {
   /**
    * Read from the channel's underlying I/O.
    *
-   * @param int Maximum number of bytes to read.
+   * @param int $length Maximum number of bytes to read.
    * @return string Bytes, if available.
    *
    * @task impl
@@ -324,7 +325,7 @@ abstract class PhutilChannel extends Phobject {
   /**
    * Write to the channel's underlying I/O.
    *
-   * @param string Bytes to write.
+   * @param string $bytes Bytes to write.
    * @return int Number of bytes written.
    *
    * @task impl
@@ -361,7 +362,8 @@ abstract class PhutilChannel extends Phobject {
    * block once the buffer reaches this size until the in-process buffer is
    * consumed.
    *
-   * @param int|null Maximum read buffer size, or `null` for a limitless buffer.
+   * @param int|null $size Maximum read buffer size, or `null` for a limitless
+   *   buffer.
    * @return this
    * @task impl
    */

src/channel/PhutilChannelChannel.php

@@ -53,10 +53,12 @@ abstract class PhutilChannelChannel extends PhutilChannel {
 
   protected function readBytes($length) {
     $this->throwOnRawByteOperations();
+    return ''; // Never returned but makes static code analyzers happy
   }
 
   protected function writeBytes($bytes) {
     $this->throwOnRawByteOperations();
+    return -1; // Never returned but makes static code analyzers happy
   }
 
   protected function getReadSockets() {

src/channel/PhutilExecChannel.php

@@ -57,7 +57,7 @@ final class PhutilExecChannel extends PhutilChannel {
    * because @{class:ExecFuture} closes stdin by default when futures start.
    * If stdin has been closed, you will be unable to write on the channel.
    *
-   * @param ExecFuture Future to use as an underlying I/O source.
+   * @param ExecFuture $future Future to use as an underlying I/O source.
    * @task construct
    */
   public function __construct(ExecFuture $future) {
@@ -162,7 +162,7 @@ final class PhutilExecChannel extends PhutilChannel {
    * You can set a handler which does nothing to effectively ignore and discard
    * any output on stderr.
    *
-   * @param callable Handler to invoke when stderr data is received.
+   * @param callable $handler Handler to invoke when stderr data is received.
    * @return this
    */
   public function setStderrHandler($handler) {

src/channel/PhutilProtocolChannel.php

@@ -46,7 +46,7 @@ abstract class PhutilProtocolChannel extends PhutilChannelChannel {
   /**
    * Write a message to the channel.
    *
-   * @param wild    Some message.
+   * @param wild   $message Some message.
    * @return this
    *
    * @task io
@@ -61,7 +61,7 @@ abstract class PhutilProtocolChannel extends PhutilChannelChannel {
    * Add a message to the queue. While you normally do not need to do this,
    * you can use it to inject out-of-band messages.
    *
-   * @param wild    Some message.
+   * @param wild   $message Some message.
    * @return this
    *
    * @task io
@@ -78,7 +78,7 @@ abstract class PhutilProtocolChannel extends PhutilChannelChannel {
   /**
    * Encode a message for transmission.
    *
-   * @param   wild    Some message.
+   * @param   wild    $message Some message.
    * @return  string  The message serialized into a wire format for
    *                  transmission.
    *
@@ -100,7 +100,7 @@ abstract class PhutilProtocolChannel extends PhutilChannelChannel {
    * a parser in this method, and store parser state on the object to be able
    * to process incoming data in small chunks.
    *
-   * @param   string      One or more bytes from the underlying channel.
+   * @param   string      $data One or more bytes from the underlying channel.
    * @return  list<wild>  Zero or more parsed messages.
    *
    * @task protocol

src/channel/PhutilSocketChannel.php

@@ -33,9 +33,10 @@ final class PhutilSocketChannel extends PhutilChannel {
    * `stream_socket_server()` or similar, not a //plain// socket from
    * `socket_create()` or similar.
    *
-   * @param socket  Socket (stream socket, not plain socket). If only one
+   * @param socket  $read_socket Socket (stream socket, not plain socket). If
-   *                socket is provided, it is used for reading and writing.
+   *                only one socket is provided, it is used for reading and
-   * @param socket? Optional write socket.
+   *                writing.
+   * @param socket  $write_socket (optional) Write socket.
    *
    * @task construct
    */

src/conduit/ConduitClient.php

@@ -206,7 +206,7 @@ final class ConduitClient extends Phobject {
    * This implicit port behavior is similar to what browsers do, so it is less
    * likely to get us into trouble with webserver configurations.
    *
-   * @param bool True to include the port explicitly.
+   * @param bool $with_explicit_port True to include the port explicitly.
    * @return string String describing the host for the request.
    */
   private function newHostString($with_explicit_port) {

src/configuration/ArcanistConfigurationManager.php

@@ -50,8 +50,8 @@ final class ArcanistConfigurationManager extends Phobject {
    * arguments ("runtime").
    * The precedence is runtime > local > project > user > system
    *
-   * @param key   Key to read.
+   * @param key   $key Key to read.
-   * @param wild  Default value if key is not found.
+   * @param wild  $default (optional) Default value if key is not found.
    * @return wild Value, or default value if not found.
    *
    * @task config
@@ -71,7 +71,7 @@ final class ArcanistConfigurationManager extends Phobject {
    * The map is ordered by the canonical sources precedence, which is:
    * runtime > local > project > user > system
    *
-   * @param key   Key to read
+   * @param key    $key Key to read
    * @return array Mapping of source => value read. Sources with no value are
    *               not in the array.
    *
@@ -135,8 +135,8 @@ final class ArcanistConfigurationManager extends Phobject {
    * Sets a runtime config value that takes precedence over any static
    * config values.
    *
-   * @param key   Key to set.
+   * @param key   $key Key to set.
-   * @param value The value of the key.
+   * @param value $value The value of the key.
    *
    * @task config
    */

src/console/PhutilConsole.php

@@ -56,7 +56,7 @@ final class PhutilConsole extends Phobject {
   /**
    * Set the active console.
    *
-   * @param PhutilConsole
+   * @param PhutilConsole $console
    * @return void
    * @task construct
    */

src/console/PhutilInteractiveEditor.php

@@ -31,7 +31,7 @@ final class PhutilInteractiveEditor extends Phobject {
   /**
    * Constructs an interactive editor, using the text of a document.
    *
-   * @param  string  Document text.
+   * @param  string $content Document text.
    * @return $this
    *
    * @task   create
@@ -171,7 +171,7 @@ final class PhutilInteractiveEditor extends Phobject {
    * opens. By default, the cursor will be positioned at the start of the
    * content.
    *
-   * @param  int   Line number where the cursor should be positioned.
+   * @param  int   $offset Line number where the cursor should be positioned.
    * @return $this
    *
    * @task config
@@ -198,7 +198,7 @@ final class PhutilInteractiveEditor extends Phobject {
    * Set the document name. Depending on the editor, this may be exposed to
    * the user and can give them a sense of what they're editing.
    *
-   * @param  string  Document name.
+   * @param  string $name Document name.
    * @return $this
    *
    * @task config
@@ -228,7 +228,7 @@ final class PhutilInteractiveEditor extends Phobject {
   /**
    * Set the text content to be edited.
    *
-   * @param  string  New content.
+   * @param  string $content New content.
    * @return $this
    *
    * @task config
@@ -255,7 +255,7 @@ final class PhutilInteractiveEditor extends Phobject {
    * Set the fallback editor program to be used if the env variable $EDITOR
    * is not available and there is no `editor` binary in PATH.
    *
-   * @param  string  Command-line editing program (e.g. 'emacs', 'vi')
+   * @param  string $editor Command-line editing program (e.g. 'emacs', 'vi')
    * @return $this
    *
    * @task config
@@ -270,7 +270,7 @@ final class PhutilInteractiveEditor extends Phobject {
    * Set the preferred editor program. If set, this will override all other
    * sources of editor configuration, like $EDITOR.
    *
-   * @param  string  Command-line editing program (e.g. 'emacs', 'vi')
+   * @param  string $editor Command-line editing program (e.g. 'emacs', 'vi')
    * @return $this
    *
    * @task config
@@ -284,7 +284,7 @@ final class PhutilInteractiveEditor extends Phobject {
    * Set the message that identifies the task for which the editor is being
    * launched, displayed to the user prior to it being launched.
    *
-   * @param  string  The message to display to the user.
+   * @param  string $task_message The message to display to the user.
    * @return $this
    *
    * @task config

src/console/format.php

@@ -94,9 +94,9 @@ function phutil_console_prompt($prompt, $history = '') {
  * Soft wrap text for display on a console, respecting UTF8 character boundaries
  * and ANSI color escape sequences.
  *
- * @param   string  Text to wrap.
+ * @param   string  $text Text to wrap.
- * @param   int     Optional indent level.
+ * @param   int     $indent (optional) Indent level. Defaults to 0.
- * @param   bool    True to also indent the first line.
+ * @param   bool    $with_prefix (Optional) True to also indent the first line.
  * @return  string  Wrapped text.
  */
 function phutil_console_wrap($text, $indent = 0, $with_prefix = true) {

src/console/view/PhutilConsoleTable.php

@@ -219,7 +219,7 @@ final class PhutilConsoleTable extends PhutilConsoleView {
   /**
    * Get the width of a specific column, including padding.
    *
-   * @param  string
+   * @param  string $key
    * @return int
    */
   protected function getWidth($key) {
@@ -265,7 +265,7 @@ final class PhutilConsoleTable extends PhutilConsoleView {
   /**
    * Format cells into an entire row.
    *
-   * @param  list<string>
+   * @param  list<string> $columns
    * @return string
    */
   protected function formatRow(array $columns) {

src/console/view/PhutilConsoleView.php

@@ -57,7 +57,7 @@ abstract class PhutilConsoleView extends Phobject {
   /**
    * Reduce a view to a list of simple, unnested parts.
    *
-   * @param wild Any drawable view.
+   * @param wild $view Any drawable view.
    * @return list<wild> List of unnested drawables.
    * @task draw
    */
@@ -84,7 +84,7 @@ abstract class PhutilConsoleView extends Phobject {
 
 
   /**
-   * @param list<wild> List of views, one per line.
+   * @param list<wild> $parts List of views, one per line.
    * @return wild Each view rendered on a separate line.
    */
   final protected function drawLines(array $parts) {

src/differential/ArcanistDifferentialCommitMessage.php

@@ -111,7 +111,7 @@ final class ArcanistDifferentialCommitMessage extends Phobject {
   /**
    * Extract the revision ID from a commit message.
    *
-   * @param string Raw commit message.
+   * @param string $corpus Raw commit message.
    * @return int|null Revision ID, if the commit message contains one.
    */
   private function parseRevisionIDFromRawCorpus($corpus) {

src/error/PhutilErrorHandler.php

@@ -88,7 +88,7 @@ final class PhutilErrorHandler extends Phobject {
    * can use @{class:PhutilProxyException} to nest exceptions; after PHP 5.3
    * all exceptions are nestable.
    *
-   * @param   Exception|Throwable       Exception to unnest.
+   * @param   Exception|Throwable       $ex Exception to unnest.
    * @return  Exception|Throwable|null  Previous exception, if one exists.
    * @task    exutil
    */
@@ -106,7 +106,7 @@ final class PhutilErrorHandler extends Phobject {
   /**
    * Find the most deeply nested exception from a possibly-nested exception.
    *
-   * @param   Exception|Throwable     A possibly-nested exception.
+   * @param   Exception|Throwable     $ex A possibly-nested exception.
    * @return  Exception|Throwable     Deepest exception in the nest.
    * @task    exutil
    */
@@ -126,7 +126,7 @@ final class PhutilErrorHandler extends Phobject {
    * Adds an error trap. Normally you should not invoke this directly;
    * @{class:PhutilErrorTrap} registers itself on construction.
    *
-   * @param PhutilErrorTrap Trap to add.
+   * @param PhutilErrorTrap $trap Trap to add.
    * @return void
    * @task trap
    */
@@ -140,7 +140,7 @@ final class PhutilErrorHandler extends Phobject {
    * Removes an error trap. Normally you should not invoke this directly;
    * @{class:PhutilErrorTrap} deregisters itself on destruction.
    *
-   * @param PhutilErrorTrap Trap to remove.
+   * @param PhutilErrorTrap $trap Trap to remove.
    * @return void
    * @task trap
    */
@@ -179,11 +179,11 @@ final class PhutilErrorHandler extends Phobject {
    * This handler converts E_NOTICE messages from uses of undefined variables
    * into @{class:RuntimeException}s.
    *
-   * @param int Error code.
+   * @param int $num Error code.
-   * @param string Error message.
+   * @param string $str Error message.
-   * @param string File where the error occurred.
+   * @param string $file File where the error occurred.
-   * @param int Line on which the error occurred.
+   * @param int $line Line on which the error occurred.
-   * @param wild Error context information.
+   * @param wild $ctx (optional) Error context information.
    * @return void
    * @task internal
    */
@@ -278,7 +278,7 @@ final class PhutilErrorHandler extends Phobject {
    * ##set_exception_handler()##. You should not call this function directly;
    * to print exceptions, pass the exception object to @{function:phlog}.
    *
-   * @param Exception|Throwable Uncaught exception object.
+   * @param Exception|Throwable $ex Uncaught exception object.
    * @return void
    * @task internal
    */
@@ -304,7 +304,7 @@ final class PhutilErrorHandler extends Phobject {
   /**
    * Output a stacktrace to the PHP error log.
    *
-   * @param trace A stacktrace, e.g. from debug_backtrace();
+   * @param trace $trace A stacktrace, e.g. from debug_backtrace();
    * @return void
    * @task internal
    */
@@ -319,7 +319,7 @@ final class PhutilErrorHandler extends Phobject {
   /**
    * Format a stacktrace for output.
    *
-   * @param trace A stacktrace, e.g. from debug_backtrace();
+   * @param trace $trace A stacktrace, e.g. from debug_backtrace();
    * @return string Human-readable trace.
    * @task internal
    */
@@ -382,9 +382,9 @@ final class PhutilErrorHandler extends Phobject {
    * dispatched to the listener; this method also prints them to the PHP error
    * log.
    *
-   * @param const Event type constant.
+   * @param const $event Event type constant.
-   * @param wild Event value.
+   * @param wild $value Event value.
-   * @param dict Event metadata.
+   * @param dict $metadata Event metadata.
    * @return void
    * @task internal
    */
@@ -560,7 +560,7 @@ final class PhutilErrorHandler extends Phobject {
    * all of the places an exception came from, even if it came from multiple
    * origins and has been aggregated or proxied.
    *
-   * @param Exception|Throwable Exception to retrieve a trace for.
+   * @param Exception|Throwable $ex Exception to retrieve a trace for.
    * @return list<wild> List of stack frames.
    */
   public static function getExceptionTrace($ex) {

src/error/phlog.php

@@ -5,8 +5,8 @@
  * forwards it to registered listeners. This is essentially a more powerful
  * version of `error_log()`.
  *
- * @param  wild  Any value you want printed to the error log or other registered
+ * @param  wild  $value Any value you want printed to the error log or other
- *               logs/consoles.
+ *               registered logs/consoles.
  * @param  ...   Other values to be logged.
  * @return wild  Passed $value.
  */
@@ -52,15 +52,15 @@ function phlog($value/* , ... */) {
  * you don't want to display these, test for `@` being in effect by checking if
  * `error_reporting() === 0` before displaying the error.
  *
- * @param  const  A PhutilErrorHandler constant, like PhutilErrorHandler::ERROR,
+ * @param  const  $event A PhutilErrorHandler constant, like
- *                which indicates the event type (e.g. error, exception,
+ *                PhutilErrorHandler::ERROR, which indicates the event type
- *                user message).
+ *                (e.g. error, exception, user message).
- * @param  wild   The event value, like the Exception object for an exception
+ * @param  wild   $value The event value, like the Exception object for an
- *                event, an error string for an error event, or some user object
+ *                exception event, an error string for an error event, or some
- *                for user messages.
+ *                user object for user messages.
- * @param  dict   A dictionary of metadata about the event. The keys 'file',
+ * @param  dict   $metadata A dictionary of metadata about the event. The keys
- *                'line' and 'trace' are always available. Other keys may be
+ *                'file', 'line' and 'trace' are always available. Other keys
- *                present, depending on the event type.
+ *                may be present, depending on the event type.
  * @return void
  */
 function phutil_error_listener_example($event, $value, array $metadata) {

src/filesystem/FileFinder.php

@@ -31,7 +31,7 @@ final class FileFinder extends Phobject {
   /**
    * Create a new FileFinder.
    *
-   * @param string Root directory to find files beneath.
+   * @param string $root Root directory to find files beneath.
    * @return this
    * @task create
    */
@@ -106,7 +106,7 @@ final class FileFinder extends Phobject {
 
   /**
    * @task config
-   * @param string Either "php", "shell", or the empty string.
+   * @param string $mode Either "php", "shell", or the empty string.
    */
   public function setForceMode($mode) {
     $this->forceMode = $mode;

src/filesystem/FileList.php

@@ -26,7 +26,7 @@ final class FileList extends Phobject {
   /**
    * Build a new FileList from an array of paths, e.g. from $argv.
    *
-   * @param  list  List of relative or absolute file paths.
+   * @param  list $paths List of relative or absolute file paths.
    * @return this
    * @task create
    */
@@ -46,10 +46,11 @@ final class FileList extends Phobject {
    * Determine if a path is one of the paths in the list. Note that an empty
    * file list is considered to contain every file.
    *
-   * @param  string  Relative or absolute system file path.
+   * @param  string  $path Relative or absolute system file path.
-   * @param  bool    If true, consider the path to be contained in the list if
+   * @param  bool    $allow_parent_directory (optional) If true, consider the
-   *                 the list contains a parent directory. If false, require
+   *                 path to be contained in the list if the list contains a
-   *                 that the path be part of the list explicitly.
+   *                 parent directory. If false, require that the path be part
+   *                 of the list explicitly.
    * @return bool    If true, the file is in the list.
    * @task test
    */

src/filesystem/Filesystem.php

@@ -25,8 +25,8 @@ final class Filesystem extends Phobject {
    * Read a file in a manner similar to file_get_contents(), but throw detailed
    * exceptions on failure.
    *
-   * @param  string  File path to read. This file must exist and be readable,
+   * @param  string  $path File path to read. This file must exist and be
-   *                 or an exception will be thrown.
+   *                 readable, or an exception will be thrown.
    * @return string  Contents of the specified file.
    *
    * @task   file
@@ -79,9 +79,9 @@ final class Filesystem extends Phobject {
    * detailed exceptions on failure. If the file already exists, it will be
    * overwritten.
    *
-   * @param  string  File path to write. This file must be writable and its
+   * @param  string  $path File path to write. This file must be writable and
-   *                 parent directory must exist.
+   *                 its parent directory must exist.
-   * @param  string  Data to write.
+   * @param  string  $data Data to write.
    *
    * @task   file
    */
@@ -106,8 +106,8 @@ final class Filesystem extends Phobject {
    * file without needing locking; any given read of the file is guaranteed to
    * be self-consistent and not see partial file contents.
    *
-   * @param string file path to write
+   * @param string $path file path to write
-   * @param string data to write
+   * @param string $data data to write
    *
    * @return boolean indicating whether the file was changed by this function.
    */
@@ -159,10 +159,10 @@ final class Filesystem extends Phobject {
    * exists, e.g. "example.bak", "example.bak.1", "example.bak.2", etc. (Don't
    * rely on this exact behavior, of course.)
    *
-   * @param   string  Suggested filename, like "example.bak". This name will
+   * @param   string  $base Suggested filename, like "example.bak". This name
-   *                  be used if it does not exist, or some similar name will
+   *                  will be used if it does not exist, or some similar name
-   *                  be chosen if it does.
+   *                  will be chosen if it does.
-   * @param   string  Data to write to the file.
+   * @param   string  $data Data to write to the file.
    * @return  string  Path to a newly created and written file which did not
    *                  previously exist, like "example.bak.3".
    * @task file
@@ -207,9 +207,9 @@ final class Filesystem extends Phobject {
    * Append to a file without having to deal with file handles, with
    * detailed exceptions on failure.
    *
-   * @param  string  File path to write. This file must be writable or its
+   * @param  string  $path File path to write. This file must be writable or
-   *                 parent directory must exist and be writable.
+   *                 its parent directory must exist and be writable.
-   * @param  string  Data to write.
+   * @param  string  $data Data to write.
    *
    * @task   file
    */
@@ -253,9 +253,9 @@ final class Filesystem extends Phobject {
   /**
    * Copy a file, preserving file attributes (if relevant for the OS).
    *
-   * @param string  File path to copy from.  This file must exist and be
+   * @param string  $from File path to copy from.  This file must exist and be
    *                readable, or an exception will be thrown.
-   * @param string  File path to copy to.  If a file exists at this path
+   * @param string  $to File path to copy to.  If a file exists at this path
    *                already, it wll be overwritten.
    *
    * @task  file
@@ -301,7 +301,7 @@ final class Filesystem extends Phobject {
   /**
    * Remove a file or directory.
    *
-   * @param  string    File to a path or directory to remove.
+   * @param  string $path File to a path or directory to remove.
    * @return void
    *
    * @task   file
@@ -327,8 +327,8 @@ final class Filesystem extends Phobject {
   /**
    * Rename a file or directory.
    *
-   * @param string    Old path.
+   * @param string $old Old path.
-   * @param string    New path.
+   * @param string $new New path.
    *
    * @task file
    */
@@ -351,7 +351,7 @@ final class Filesystem extends Phobject {
    * Internal. Recursively remove a file or an entire directory. Implements
    * the core function of @{method:remove} in a way that works on Windows.
    *
-   * @param  string    File to a path or directory to remove.
+   * @param  string $path File to a path or directory to remove.
    * @return void
    *
    * @task file
@@ -381,9 +381,9 @@ final class Filesystem extends Phobject {
   /**
    * Change the permissions of a file or directory.
    *
-   * @param  string    Path to the file or directory.
+   * @param  string $path  Path to the file or directory.
-   * @param  int       Permission umask. Note that umask is in octal, so you
+   * @param  int    $umask Permission umask. Note that umask is in octal, so
-   *                   should specify it as, e.g., `0777', not `777'.
+   *                   you should specify it as, e.g., `0777', not `777'.
    * @return void
    *
    * @task   file
@@ -405,7 +405,7 @@ final class Filesystem extends Phobject {
   /**
    * Get the last modified time of a file
    *
-   * @param string Path to file
+   * @param string $path Path to file
    * @return int Time last modified
    *
    * @task file
@@ -432,7 +432,7 @@ final class Filesystem extends Phobject {
    * Read random bytes from /dev/urandom or equivalent. See also
    * @{method:readRandomCharacters}.
    *
-   * @param   int     Number of bytes to read.
+   * @param   int     $number_of_bytes Number of bytes to read.
    * @return  string  Random bytestring of the provided length.
    *
    * @task file
@@ -530,7 +530,7 @@ final class Filesystem extends Phobject {
    * output (a-z, 0-9) so it's appropriate for use in URIs and other contexts
    * where it needs to be human readable.
    *
-   * @param   int     Number of characters to read.
+   * @param   int     $number_of_characters Number of characters to read.
    * @return  string  Random character string of the provided length.
    *
    * @task file
@@ -563,8 +563,8 @@ final class Filesystem extends Phobject {
    *
    * This method uses less-entropic random sources under older versions of PHP.
    *
-   * @param int Minimum value, inclusive.
+   * @param int $min Minimum value, inclusive.
-   * @param int Maximum value, inclusive.
+   * @param int $max Maximum value, inclusive.
    */
   public static function readRandomInteger($min, $max) {
     if (!is_int($min)) {
@@ -612,9 +612,9 @@ final class Filesystem extends Phobject {
    * Identify the MIME type of a file. This returns only the MIME type (like
    * text/plain), not the encoding (like charset=utf-8).
    *
-   * @param string Path to the file to examine.
+   * @param string $path Path to the file to examine.
-   * @param string Optional default mime type to return if the file's mime
+   * @param string $default (optional) default mime type to return if the
-   *               type can not be identified.
+   *               file's mime type can not be identified.
    * @return string File mime type.
    *
    * @task file
@@ -693,11 +693,12 @@ final class Filesystem extends Phobject {
    * Create a directory in a manner similar to mkdir(), but throw detailed
    * exceptions on failure.
    *
-   * @param  string    Path to directory. The parent directory must exist and
+   * @param  string    $path Path to directory. The parent directory must exist
-   *                   be writable.
+   *                   and be writable.
-   * @param  int       Permission umask. Note that umask is in octal, so you
+   * @param  int       $umask Permission umask. Note that umask is in octal, so
-   *                   should specify it as, e.g., `0777', not `777'.
+   *                   you should specify it as, e.g., `0777', not `777'.
-   * @param  boolean   Recursively create directories. Default to false.
+   * @param  boolean   $recursive (optional) Recursively create directories.
+   *                   Defaults to false.
    * @return string    Path to the created directory.
    *
    * @task   directory
@@ -752,11 +753,13 @@ final class Filesystem extends Phobject {
    * responsible for removing it (e.g., with Filesystem::remove())
    * when you are done with it.
    *
-   * @param  string    Optional directory prefix.
+   * @param  string    $prefix (optional) directory prefix.
-   * @param  int       Permissions to create the directory with. By default,
+   * @param  int       $umask (optional) Permissions to create the directory
-   *                   these permissions are very restrictive (0700).
+   *                   with. By default, these permissions are very restrictive
-   * @param  string    Optional root directory. If not provided, the system
+   *                   (0700).
-   *                   temporary directory (often "/tmp") will be used.
+   * @param  string    $root_directory (optional) Root directory. If not
+   *                   provided, the system temporary directory (often "/tmp")
+   *                   will be used.
    * @return string    Path to newly created temporary directory.
    *
    * @task   directory
@@ -814,8 +817,9 @@ final class Filesystem extends Phobject {
   /**
    * List files in a directory.
    *
-   * @param  string    Path, absolute or relative to PWD.
+   * @param  string    $path Path, absolute or relative to PWD.
-   * @param  bool      If false, exclude files beginning with a ".".
+   * @param  bool      $include_hidden If false, exclude files beginning with
+   *                   a ".".
    *
    * @return array     List of files and directories in the specified
    *                   directory, excluding `.' and `..'.
@@ -850,8 +854,8 @@ final class Filesystem extends Phobject {
    * Return all directories between a path and the specified root directory
    * (defaulting to "/"). Iterating over them walks from the path to the root.
    *
-   * @param  string        Path, absolute or relative to PWD.
+   * @param  string        $path Path, absolute or relative to PWD.
-   * @param  string        The root directory.
+   * @param  string        $root (optional) The root directory.
    * @return list<string>  List of parent paths, including the provided path.
    * @task   directory
    */
@@ -924,7 +928,7 @@ final class Filesystem extends Phobject {
   /**
    * Checks if a path is specified as an absolute path.
    *
-   * @param  string
+   * @param  string $path
    * @return bool
    */
   public static function isAbsolutePath($path) {
@@ -940,8 +944,8 @@ final class Filesystem extends Phobject {
    * default PWD), following parent symlinks and removing artifacts. If the
    * path is itself a symlink it is left unresolved.
    *
-   * @param  string    Path, absolute or relative to PWD.
+   * @param  string    $path Path, absolute or relative to PWD.
-   * @return string    Canonical, absolute path.
+   * @return string    $relative_to (optional) Canonical, absolute path.
    *
    * @task   path
    */
@@ -1009,8 +1013,8 @@ final class Filesystem extends Phobject {
    * symlinks and removing artifacts. Both paths must exists for the relation
    * to obtain. A path is always a descendant of itself as long as it exists.
    *
-   * @param  string   Child path, absolute or relative to PWD.
+   * @param  string   $path Child path, absolute or relative to PWD.
-   * @param  string   Root path, absolute or relative to PWD.
+   * @param  string   $root Root path, absolute or relative to PWD.
    * @return bool     True if resolved child path is in fact a descendant of
    *                  resolved root path and both exist.
    * @task   path
@@ -1031,8 +1035,8 @@ final class Filesystem extends Phobject {
    * guaranteed that you can use resolvePath() to restore a path to its
    * canonical format.
    *
-   * @param  string    Path, absolute or relative to PWD.
+   * @param  string    $path Path, absolute or relative to PWD.
-   * @param  string    Optionally, working directory to make files readable
+   * @param  string    $pwd (optional) Working directory to make files readable
    *                   relative to.
    * @return string    Human-readable path.
    *
@@ -1060,7 +1064,7 @@ final class Filesystem extends Phobject {
    * file_exists() in that it returns true for symlinks. This method does not
    * attempt to resolve paths before testing them.
    *
-   * @param   string  Test for the existence of this path.
+   * @param   string  $path Test for the existence of this path.
    * @return  bool    True if the path exists in the filesystem.
    * @task    path
    */
@@ -1073,7 +1077,7 @@ final class Filesystem extends Phobject {
    * Determine if an executable binary (like `git` or `svn`) exists within
    * the configured `$PATH`.
    *
-   * @param   string  Binary name, like `'git'` or `'svn'`.
+   * @param   string  $binary Binary name, like `'git'` or `'svn'`.
    * @return  bool    True if the binary exists and is executable.
    * @task    exec
    */
@@ -1086,7 +1090,7 @@ final class Filesystem extends Phobject {
    * Locates the full path that an executable binary (like `git` or `svn`) is at
    * the configured `$PATH`.
    *
-   * @param   string  Binary name, like `'git'` or `'svn'`.
+   * @param   string  $binary Binary name, like `'git'` or `'svn'`.
    * @return  string  The full binary path if it is present, or null.
    * @task    exec
    */
@@ -1129,8 +1133,8 @@ final class Filesystem extends Phobject {
    * resolvePath() only resolves symlinks in parent directories, not the
    * path itself.
    *
-   * @param string First path to test for equivalence.
+   * @param string $u First path to test for equivalence.
-   * @param string Second path to test for equivalence.
+   * @param string $v Second path to test for equivalence.
    * @return bool  True if both paths are equivalent, i.e. reference the same
    *               entity in the filesystem.
    * @task path
@@ -1171,7 +1175,7 @@ final class Filesystem extends Phobject {
    * Assert that something (e.g., a file, directory, or symlink) exists at a
    * specified location.
    *
-   * @param  string    Assert that this path exists.
+   * @param  string $path Assert that this path exists.
    * @return void
    *
    * @task   assert
@@ -1223,7 +1227,7 @@ final class Filesystem extends Phobject {
   /**
    * Assert that nothing exists at a specified location.
    *
-   * @param  string    Assert that this path does not exist.
+   * @param  string $path Assert that this path does not exist.
    * @return void
    *
    * @task   assert
@@ -1240,7 +1244,7 @@ final class Filesystem extends Phobject {
   /**
    * Assert that a path represents a file, strictly (i.e., not a directory).
    *
-   * @param  string    Assert that this path is a file.
+   * @param  string $path Assert that this path is a file.
    * @return void
    *
    * @task   assert
@@ -1257,7 +1261,7 @@ final class Filesystem extends Phobject {
   /**
    * Assert that a path represents a directory, strictly (i.e., not a file).
    *
-   * @param  string    Assert that this path is a directory.
+   * @param  string $path Assert that this path is a directory.
    * @return void
    *
    * @task   assert
@@ -1274,7 +1278,7 @@ final class Filesystem extends Phobject {
   /**
    * Assert that a file or directory exists and is writable.
    *
-   * @param  string    Assert that this path is writable.
+   * @param  string $path Assert that this path is writable.
    * @return void
    *
    * @task   assert
@@ -1291,7 +1295,7 @@ final class Filesystem extends Phobject {
   /**
    * Assert that a file or directory exists and is readable.
    *
-   * @param  string    Assert that this path is readable.
+   * @param  string $path Assert that this path is readable.
    * @return void
    *
    * @task   assert

src/filesystem/FilesystemException.php

@@ -11,8 +11,8 @@ final class FilesystemException extends Exception {
   /**
    * Create a new FilesystemException, providing a path and a message.
    *
-   * @param  string  Path that caused the failure.
+   * @param  string $path Path that caused the failure.
-   * @param  string  Description of the failure.
+   * @param  string $message Description of the failure.
    */
   public function __construct($path, $message) {
     $this->path = $path;

src/filesystem/PhutilDeferredLog.php

@@ -55,9 +55,9 @@ final class PhutilDeferredLog extends Phobject {
    *
    *   $log = new PhutilDeferredLog('/some/file.log', '[%T] %u');
    *
-   * @param string|null The file the entry should be written to, or null to
+   * @param string|null $file The file the entry should be written to, or null
-   *                    create a log object which does not write anywhere.
+   *                    to create a log object which does not write anywhere.
-   * @param string      The log entry format.
+   * @param string      $format The log entry format.
    * @task log
    */
   public function __construct($file, $format) {
@@ -85,7 +85,7 @@ final class PhutilDeferredLog extends Phobject {
    * When the log is written, the "%T" and "%u" variables will be replaced with
    * the values you provide.
    *
-   * @param dict  Map of variables to values.
+   * @param dict  $map Map of variables to values.
    * @return this
    * @task log
    */
@@ -98,8 +98,9 @@ final class PhutilDeferredLog extends Phobject {
   /**
    * Get existing log data.
    *
-   * @param   string  Log data key.
+   * @param   string  $key Log data key.
-   * @param   wild    Default to return if data does not exist.
+   * @param   wild    $default (optional) Default to return if data does not
+   *   exist.
    * @return  wild    Data, or default if data does not exist.
    * @task log
    */
@@ -114,8 +115,8 @@ final class PhutilDeferredLog extends Phobject {
    *
    * NOTE: You can not change the file after the log writes.
    *
-   * @param string|null File where the entry should be written to, or null to
+   * @param string|null $file File where the entry should be written to, or
-   *                    prevent writes.
+   *                    null to prevent writes.
    * @return this
    * @task log
    */

src/filesystem/PhutilFileLock.php

@@ -29,7 +29,7 @@ final class PhutilFileLock extends PhutilLock {
   /**
    * Create a new lock on a lockfile. The file need not exist yet.
    *
-   * @param   string          The lockfile to use.
+   * @param   string          $lockfile The lockfile to use.
    * @return  PhutilFileLock  New lock object.
    *
    * @task construct
@@ -59,7 +59,7 @@ final class PhutilFileLock extends PhutilLock {
    * If the lock is already held, this method throws. You can test the lock
    * status with @{method:isLocked}.
    *
-   * @param  float  Seconds to block waiting for the lock.
+   * @param  float $wait Seconds to block waiting for the lock.
    * @return void
    *
    * @task lock

src/filesystem/PhutilLock.php

@@ -41,7 +41,7 @@ abstract class PhutilLock extends Phobject {
    * Build a new lock, given a lock name. The name should be globally unique
    * across all locks.
    *
-   * @param string Globally unique lock name.
+   * @param string $name Globally unique lock name.
    * @task construct
    */
   protected function __construct($name) {
@@ -55,7 +55,7 @@ abstract class PhutilLock extends Phobject {
   /**
    * Acquires the lock, or throws @{class:PhutilLockException} if it fails.
    *
-   * @param  float  Seconds to block waiting for the lock.
+   * @param  float $wait Seconds to block waiting for the lock.
    * @return void
    * @task impl
    */
@@ -88,7 +88,7 @@ abstract class PhutilLock extends Phobject {
   /**
    * Get a named lock, if it has been registered.
    *
-   * @param string Lock name.
+   * @param string $name Lock name.
    * @task registry
    */
   protected static function getLock($name) {
@@ -99,7 +99,7 @@ abstract class PhutilLock extends Phobject {
   /**
    * Register a lock for cleanup when the process exits.
    *
-   * @param PhutilLock Lock to register.
+   * @param PhutilLock $lock Lock to register.
    * @task registry
    */
   protected static function registerLock(PhutilLock $lock) {
@@ -144,8 +144,8 @@ abstract class PhutilLock extends Phobject {
    * If the lock is already held by this process, this method throws. You can
    * test the lock status with @{method:isLocked}.
    *
-   * @param  float  Seconds to block waiting for the lock. By default, do not
+   * @param  float $wait (optional) Seconds to block waiting for the lock. By
-   *                block.
+   *               default, do not block.
    * @return this
    *
    * @task lock

src/filesystem/TempFile.php

@@ -27,11 +27,13 @@ final class TempFile extends Phobject {
   /**
    * Create a new temporary file.
    *
-   * @param string? Filename hint. This is useful if you intend to edit the
+   * @param string  $filename (optional) Filename hint. This is useful if you
-   *                file with an interactive editor, so the user's editor shows
+   *                intend to edit the file with an interactive editor, so the
-   *                "commit-message" instead of "p3810hf-1z9b89bas".
+   *                user's editor shows "commit-message" instead of
-   * @param string? Root directory to hold the file. If omitted, the system
+   *                "p3810hf-1z9b89bas".
-   *                temporary directory (often "/tmp") will be used by default.
+   * @param string  $root_directory (optional) Root directory to hold the file.
+   *                If omitted, the system temporary directory (often "/tmp")
+   *                will be used by default.
    * @task create
    */
   public function __construct($filename = null, $root_directory = null) {
@@ -60,7 +62,7 @@ final class TempFile extends Phobject {
    * Normally, the file is deleted when this object passes out of scope. You
    * can set it to be preserved instead.
    *
-   * @param bool True to preserve the file after object destruction.
+   * @param bool $preserve True to preserve the file after object destruction.
    * @return this
    * @task config
    */

src/filesystem/linesofalarge/LinesOfALarge.php

@@ -56,7 +56,7 @@ abstract class LinesOfALarge extends Phobject implements Iterator {
    * without looking for delimiters. You can use this to stream a large file or
    * the output of a command which returns a large amount of data.
    *
-   * @param string|null A one-byte delimiter character.
+   * @param string|null $character A one-byte delimiter character.
    * @return this
    * @task config
    */

src/filesystem/linesofalarge/LinesOfALargeExecFuture.php

@@ -34,7 +34,7 @@ final class LinesOfALargeExecFuture extends LinesOfALarge {
   /**
    * To construct, pass an @{class:ExecFuture}.
    *
-   * @param ExecFuture Future to wrap.
+   * @param ExecFuture $future Future to wrap.
    * @return void
    * @task construct
    */

src/filesystem/linesofalarge/LinesOfALargeFile.php

@@ -29,7 +29,7 @@ final class LinesOfALargeFile extends LinesOfALarge {
   /**
    * To construct, pass the path to a file.
    *
-   * @param string File path to read.
+   * @param string $file_name File path to read.
    * @return void
    * @task construct
    */

src/future/FutureIterator.php

@@ -52,7 +52,7 @@ final class FutureIterator
   /**
    * Create a new iterator over a list of futures.
    *
-   * @param list  List of @{class:Future}s to resolve.
+   * @param list $futures List of @{class:Future}s to resolve.
    * @task basics
    */
   public function __construct(array $futures) {
@@ -90,7 +90,7 @@ final class FutureIterator
    * set of futures to run mostly in parallel, but some futures depend on
    * others.
    *
-   * @param Future  @{class:Future} to add to iterator
+   * @param Future $future @{class:Future} to add to iterator
    * @task basics
    */
   public function addFuture(Future $future) {
@@ -133,8 +133,8 @@ final class FutureIterator
    * This will echo "Still working..." once per second as long as futures are
    * resolving. By default, FutureIterator never yields null.
    *
-   * @param float Maximum number of seconds to block waiting on futures before
+   * @param float $interval Maximum number of seconds to block waiting on
-   *              yielding null.
+   *              futures before yielding null.
    * @return this
    *
    * @task config
@@ -154,7 +154,7 @@ final class FutureIterator
    *    // Run no more than 4 futures simultaneously.
    *  }
    *
-   * @param int Maximum number of simultaneous jobs allowed.
+   * @param int $max Maximum number of simultaneous jobs allowed.
    * @return this
    *
    * @task config
@@ -417,9 +417,9 @@ final class FutureIterator
   /**
    * Wait for activity on one of several sockets.
    *
-   * @param  list  List of sockets expected to become readable.
+   * @param  list  $read_list List of sockets expected to become readable.
-   * @param  list  List of sockets expected to become writable.
+   * @param  list  $write_list List of sockets expected to become writable.
-   * @param  float Timeout, in seconds.
+   * @param  float $timeout (optional) Timeout, in seconds.
    * @return void
    */
   private function waitForSockets(

src/future/exec/ExecFuture.php

@@ -119,7 +119,7 @@ final class ExecFuture extends PhutilExecutableFuture {
    *
    * NOTE: Setting this to 0 means "no buffer", not "unlimited buffer".
    *
-   * @param int Maximum size of the stdout read buffer.
+   * @param int $limit Maximum size of the stdout read buffer.
    * @return this
    * @task config
    */
@@ -133,7 +133,7 @@ final class ExecFuture extends PhutilExecutableFuture {
    * Set a maximum size for the stderr read buffer.
    * See @{method:setStdoutSizeLimit} for discussion.
    *
-   * @param int Maximum size of the stderr read buffer.
+   * @param int $limit Maximum size of the stderr read buffer.
    * @return this
    * @task config
    */
@@ -153,7 +153,8 @@ final class ExecFuture extends PhutilExecutableFuture {
    * TODO: We should probably release the read buffer limit during
    * @{method:resolve}, or otherwise detect this. For now, be careful.
    *
-   * @param int|null Maximum buffer size, or `null` for unlimited.
+   * @param int|null $read_buffer_size Maximum buffer size, or `null` for
+   *   unlimited.
    * @return this
    */
   public function setReadBufferSize($read_buffer_size) {
@@ -233,12 +234,12 @@ final class ExecFuture extends PhutilExecutableFuture {
   /**
    * Write data to stdin of the command.
    *
-   * @param string Data to write.
+   * @param string $data Data to write.
-   * @param bool If true, keep the pipe open for writing. By default, the pipe
+   * @param bool $keep_pipe (optional) If true, keep the pipe open for writing.
-   *             will be closed as soon as possible so that commands which
+   *             By default, the pipe will be closed as soon as possible so
-   *             listen for EOF will execute. If you want to keep the pipe open
+   *             that commands which listen for EOF will execute. If you want
-   *             past the start of command execution, do an empty write with
+   *             to keep the pipe open past the start of command execution, do
-   *             `$keep_pipe = true` first.
+   *             an empty write with `$keep_pipe = true` first.
    * @return this
    * @task interact
    */
@@ -308,8 +309,8 @@ final class ExecFuture extends PhutilExecutableFuture {
    * The subprocess will be sent a `TERM` signal, and then a `KILL` signal a
    * short while later if it fails to exit.
    *
-   * @param int Maximum number of seconds this command may execute for before
+   * @param int $seconds Maximum number of seconds this command may execute for
-   *  it is signaled.
+   *  before it is signaled.
    * @return this
    * @task config
    */
@@ -523,13 +524,13 @@ final class ExecFuture extends PhutilExecutableFuture {
    * Reads some bytes from a stream, discarding output once a certain amount
    * has been accumulated.
    *
-   * @param resource  Stream to read from.
+   * @param resource  $stream Stream to read from.
-   * @param int       Maximum number of bytes to return from $stream. If
+   * @param int       $limit Maximum number of bytes to return from $stream. If
    *                  additional bytes are available, they will be read and
    *                  discarded.
-   * @param string    Human-readable description of stream, for exception
+   * @param string    $description Human-readable description of stream, for
-   *                  message.
+   *                  exception message.
-   * @param int       Maximum number of bytes to read.
+   * @param int       $length Maximum number of bytes to read.
    * @return string   The data read from the stream.
    * @task internal
    */

src/future/exec/PhutilExecutableFuture.php

@@ -60,8 +60,9 @@ abstract class PhutilExecutableFuture extends Future {
    *   // Env will have ONLY "X".
    *   $exec->setEnv(array('X' => 'y'), $wipe_process_env = true);
    *
-   * @param map<string, string> Dictionary of environmental variables.
+   * @param map<string, string> $env Dictionary of environmental variables.
-   * @param bool Optionally, pass `true` to replace the existing environment.
+   * @param bool $wipe_process_env (optional) Pass `true` to replace the
+   *   existing environment.
    * @return this
    *
    * @task config
@@ -86,8 +87,8 @@ abstract class PhutilExecutableFuture extends Future {
   /**
    * Set the value of a specific environmental variable for this command.
    *
-   * @param string Environmental variable name.
+   * @param string $key Environmental variable name.
-   * @param string|null New value, or null to remove this variable.
+   * @param string|null $value New value, or null to remove this variable.
    * @return this
    * @task config
    */
@@ -159,7 +160,7 @@ abstract class PhutilExecutableFuture extends Future {
    * the subprocess will execute). If not set, the default value is the parent's
    * current working directory.
    *
-   * @param string Directory to execute the subprocess in.
+   * @param string $cwd Directory to execute the subprocess in.
    * @return this
    * @task config
    */

src/future/exec/execx.php

@@ -7,7 +7,7 @@
  *
  *   list ($stdout, $stderr) = execx('ls %s', $file);
  *
- * @param  string  sprintf()-style command pattern to execute.
+ * @param  string  $cmd sprintf()-style command pattern to execute.
  * @param  ...     Arguments to sprintf pattern.
  * @return array   List of stdout and stderr.
  */
@@ -27,7 +27,7 @@ function execx($cmd /* , ... */) {
  * Error flows can often be simplified by using @{function:execx} instead,
  * which throws an exception when it encounters an error.
  *
- * @param  string  sprintf()-style command pattern to execute.
+ * @param  string  $cmd sprintf()-style command pattern to execute.
  * @param  ...     Arguments to sprintf pattern.
  * @return array   List of return code, stdout, and stderr.
  */
@@ -41,7 +41,7 @@ function exec_manual($cmd /* , ... */) {
 /**
  * Wrapper for @{class:PhutilExecPassthru}.
  *
- * @param  string  sprintf()-style command pattern to execute.
+ * @param  string  $cmd sprintf()-style command pattern to execute.
  * @param  ...     Arguments to sprintf pattern.
  * @return int     Return code.
  */
@@ -55,7 +55,7 @@ function phutil_passthru($cmd /* , ... */) {
  * Return a human-readable signal name (like "SIGINT" or "SIGKILL") for a given
  * signal number.
  *
- * @param   int     Signal number.
+ * @param   int     $signo Signal number.
  * @return  string  Human-readable signal name.
  */
 function phutil_get_signal_name($signo) {

src/future/http/BaseHTTPFuture.php

@@ -37,10 +37,10 @@ abstract class BaseHTTPFuture extends Future {
    * instantiate it; instead, build a new @{class:HTTPFuture} or
    * @{class:HTTPSFuture}.
    *
-   * @param string Fully-qualified URI to send a request to.
+   * @param string $uri Fully-qualified URI to send a request to.
-   * @param mixed  String or array to include in the request. Strings will be
+   * @param mixed  $data (optional) String or array to include in the request.
-   *               transmitted raw; arrays will be encoded and sent as
+   *               Strings will be transmitted raw; arrays will be encoded and
-   *               'application/x-www-form-urlencoded'.
+   *               sent as 'application/x-www-form-urlencoded'.
    * @task create
    */
   final public function __construct($uri, $data = array()) {
@@ -58,7 +58,7 @@ abstract class BaseHTTPFuture extends Future {
    * out. You can determine if a status is a timeout status by calling
    * isTimeout() on the status object.
    *
-   * @param float Maximum timeout, in seconds.
+   * @param float $timeout Maximum timeout, in seconds.
    * @return this
    * @task config
    */
@@ -83,7 +83,7 @@ abstract class BaseHTTPFuture extends Future {
    * Select the HTTP method (e.g., "GET", "POST", "PUT") to use for the request.
    * By default, requests use "GET".
    *
-   * @param string HTTP method name.
+   * @param string $method HTTP method name.
    * @return this
    * @task config
    */
@@ -124,7 +124,7 @@ abstract class BaseHTTPFuture extends Future {
    * Set the URI to send the request to. Note that this is also a constructor
    * parameter.
    *
-   * @param string URI to send the request to.
+   * @param string $uri URI to send the request to.
    * @return this
    * @task config
    */
@@ -151,7 +151,7 @@ abstract class BaseHTTPFuture extends Future {
    * must be a string (in which case it will be sent raw) or an array (in which
    * case it will be encoded and sent as 'application/x-www-form-urlencoded').
    *
-   * @param mixed Data to send with the request.
+   * @param mixed $data Data to send with the request.
    * @return this
    * @task config
    */
@@ -179,8 +179,8 @@ abstract class BaseHTTPFuture extends Future {
    * Add an HTTP header to the request. The same header name can be specified
    * more than once, which will cause multiple headers to be sent.
    *
-   * @param string Header name, like "Accept-Language".
+   * @param string $name Header name, like "Accept-Language".
-   * @param string Header value, like "en-us".
+   * @param string $value Header value, like "en-us".
    * @return this
    * @task config
    */
@@ -200,8 +200,8 @@ abstract class BaseHTTPFuture extends Future {
    *
    * In either case, an array with all (or all matching) headers is returned.
    *
-   * @param string|null Optional filter, which selects only headers with that
+   * @param string|null $filter (optional) Filter, which selects only headers
-   *                    name if provided.
+   *                    with that name if provided.
    * @return array      List of all (or all matching) headers.
    * @task config
    */
@@ -228,7 +228,7 @@ abstract class BaseHTTPFuture extends Future {
    * HTTP status code outside the 2xx range (notwithstanding other errors such
    * as connection or transport issues).
    *
-   * @param array|null List of expected HTTP status codes.
+   * @param array|null $status_codes List of expected HTTP status codes.
    *
    * @return this
    * @task config
@@ -251,8 +251,8 @@ abstract class BaseHTTPFuture extends Future {
   /**
    * Add a HTTP basic authentication header to the request.
    *
-   * @param string                Username to authenticate with.
+   * @param string                $username Username to authenticate with.
-   * @param PhutilOpaqueEnvelope  Password to authenticate with.
+   * @param PhutilOpaqueEnvelope  $password Password to authenticate with.
    * @return this
    * @task config
    */
@@ -316,7 +316,7 @@ abstract class BaseHTTPFuture extends Future {
   /**
    * Parse a raw HTTP response into a <status, body, headers> tuple.
    *
-   * @param string Raw HTTP response.
+   * @param string $raw_response Raw HTTP response.
    * @return tuple Valid resolution tuple.
    * @task internal
    */
@@ -393,7 +393,7 @@ abstract class BaseHTTPFuture extends Future {
   /**
    * Parse an HTTP header block.
    *
-   * @param string Raw HTTP headers.
+   * @param string $head_raw Raw HTTP headers.
    * @return list List of HTTP header tuples.
    * @task internal
    */
@@ -423,8 +423,8 @@ abstract class BaseHTTPFuture extends Future {
   /**
    * Find value of the first header with given name.
    *
-   * @param list List of headers from `resolve()`.
+   * @param list $headers List of headers from `resolve()`.
-   * @param string Case insensitive header name.
+   * @param string $search Case insensitive header name.
    * @return string Value of the header or null if not found.
    * @task resolve
    */

src/future/http/HTTPSFuture.php

@@ -39,7 +39,8 @@ final class HTTPSFuture extends BaseHTTPFuture {
    * cURL needs this to be a file, it doesn't seem to be able to handle a string
    * which contains the cert. So we make a temporary file and store it there.
    *
-   * @param string The multi-line, possibly lengthy, SSL certificate to use.
+   * @param string $certificate The multi-line, possibly lengthy, SSL
+   *   certificate to use.
    * @return this
    */
   public function setCABundleFromString($certificate) {
@@ -52,7 +53,7 @@ final class HTTPSFuture extends BaseHTTPFuture {
   /**
    * Set the SSL certificate to use for this session, given a path.
    *
-   * @param string The path to a valid SSL certificate for this session
+   * @param string $path The path to a valid SSL certificate for this session
    * @return this
    */
   public function setCABundleFromPath($path) {
@@ -73,8 +74,8 @@ final class HTTPSFuture extends BaseHTTPFuture {
    * Set whether Location headers in the response will be respected.
    * The default is true.
    *
-   * @param boolean true to follow any Location header present in the response,
+   * @param boolean $follow true to follow any Location header present in the
-   *                false to return the request directly
+   *                response, false to return the request directly
    * @return this
    */
   public function setFollowLocation($follow) {
@@ -95,7 +96,7 @@ final class HTTPSFuture extends BaseHTTPFuture {
    * Set the fallback CA certificate if one is not specified
    * for the session, given a path.
    *
-   * @param string The path to a valid SSL certificate
+   * @param string $path The path to a valid SSL certificate
    * @return void
    */
   public static function setGlobalCABundleFromPath($path) {
@@ -105,7 +106,7 @@ final class HTTPSFuture extends BaseHTTPFuture {
    * Set the fallback CA certificate if one is not specified
    * for the session, given a string.
    *
-   * @param string The certificate
+   * @param string $certificate The certificate
    * @return void
    */
   public static function setGlobalCABundleFromString($certificate) {
@@ -127,8 +128,8 @@ final class HTTPSFuture extends BaseHTTPFuture {
    * Load contents of remote URI. Behaves pretty much like
    * `@file_get_contents($uri)` but doesn't require `allow_url_fopen`.
    *
-   * @param string
+   * @param string $uri
-   * @param float
+   * @param float $timeout (optional)
    * @return string|false
    */
   public static function loadContent($uri, $timeout = null) {
@@ -186,10 +187,10 @@ final class HTTPSFuture extends BaseHTTPFuture {
   /**
    * Attach a file to the request.
    *
-   * @param string  HTTP parameter name.
+   * @param string  $key HTTP parameter name.
-   * @param string  File content.
+   * @param string  $data File content.
-   * @param string  File name.
+   * @param string  $name File name.
-   * @param string  File mime type.
+   * @param string  $mime_type File mime type.
    * @return this
    */
   public function attachFileData($key, $data, $name, $mime_type) {
@@ -770,8 +771,9 @@ final class HTTPSFuture extends BaseHTTPFuture {
   /**
    * Detect strings which will cause cURL to do horrible, insecure things.
    *
-   * @param string  Possibly dangerous string.
+   * @param string  $string Possibly dangerous string.
-   * @param bool    True if this string is being used as part of a query string.
+   * @param bool    $is_query_string True if this string is being used as part
+   *   of a query string.
    * @return void
    */
   private function checkForDangerousCURLMagic($string, $is_query_string) {
@@ -828,7 +830,7 @@ final class HTTPSFuture extends BaseHTTPFuture {
    *
    * You must write the entire body before starting the request.
    *
-   * @param string Raw body.
+   * @param string $raw_body Raw body.
    * @return this
    */
   public function write($raw_body) {

src/future/postmark/PhutilPostmarkFuture.php

@@ -3,6 +3,7 @@
 final class PhutilPostmarkFuture extends FutureProxy {
 
   private $future;
+  private $clientID;
   private $accessToken;
   private $method;
   private $parameters;

src/hgdaemon/ArcanistHgClientChannel.php

@@ -50,7 +50,7 @@ final class ArcanistHgClientChannel extends PhutilProtocolChannel {
    * For a detailed description of the cmdserver protocol, see
    * @{class:ArcanistHgServerChannel}.
    *
-   * @param pair<string,string> The <channel, data> pair to encode.
+   * @param pair<string,string> $argv The <channel, data> pair to encode.
    * @return string Encoded string for transmission to the client.
    *
    * @task protocol
@@ -88,7 +88,7 @@ final class ArcanistHgClientChannel extends PhutilProtocolChannel {
    *     '5',
    *   );
    *
-   * @param string Bytes from the server.
+   * @param string $data Bytes from the server.
    * @return list<list<string>> Zero or more complete commands.
    *
    * @task protocol

src/hgdaemon/ArcanistHgProxyClient.php

@@ -41,7 +41,7 @@ final class ArcanistHgProxyClient extends Phobject {
    * Build a new client. This client is bound to a working copy. A server
    * must already be running on this working copy for the client to work.
    *
-   * @param string Path to a Mercurial working copy.
+   * @param string $working_copy Path to a Mercurial working copy.
    *
    * @task construct
    */
@@ -56,7 +56,7 @@ final class ArcanistHgProxyClient extends Phobject {
   /**
    * When connecting, do not expect the "capabilities" message.
    *
-   * @param bool True to skip the "capabilities" message.
+   * @param bool $skip True to skip the "capabilities" message.
    * @return this
    *
    * @task config
@@ -73,7 +73,8 @@ final class ArcanistHgProxyClient extends Phobject {
   /**
    * Execute a command (given as a list of arguments) via the command server.
    *
-   * @param list<string> A list of command arguments, like "log", "-l", "5".
+   * @param list<string> $argv A list of command arguments, like "log", "-l",
+   *   "5".
    * @return tuple<int, string, string> Return code, stdout and stderr.
    *
    * @task exec

src/hgdaemon/ArcanistHgProxyServer.php

@@ -52,7 +52,7 @@ final class ArcanistHgProxyServer extends Phobject {
    * Build a new server. This server is bound to a working copy. The server
    * is inactive until you @{method:start} it.
    *
-   * @param string Path to a Mercurial working copy.
+   * @param string $working_copy Path to a Mercurial working copy.
    *
    * @task construct
    */
@@ -67,7 +67,7 @@ final class ArcanistHgProxyServer extends Phobject {
   /**
    * Disable status messages to stdout. Controlled with `--quiet`.
    *
-   * @param bool  True to disable status messages.
+   * @param bool $quiet True to disable status messages.
    * @return this
    *
    * @task config
@@ -85,7 +85,7 @@ final class ArcanistHgProxyServer extends Phobject {
    * You can use `--client-limit 1` with `--xprofile` and `--do-not-daemonize`
    * to profile the server.
    *
-   * @param int Client limit, or 0 to disable limit.
+   * @param int $limit Client limit, or 0 to disable limit.
    * @return this
    *
    * @task config
@@ -100,7 +100,7 @@ final class ArcanistHgProxyServer extends Phobject {
    * Configure an idle time limit. After this many seconds idle, the server
    * will exit. Controlled with `--idle-limit`.
    *
-   * @param int Idle limit, or 0 to disable limit.
+   * @param int $limit Idle limit, or 0 to disable limit.
    * @return this
    *
    * @task config
@@ -117,7 +117,7 @@ final class ArcanistHgProxyServer extends Phobject {
    * if the clients are also configured not to expect the message, but slightly
    * improves performance. Controlled with --skip-hello.
    *
-   * @param bool True to skip the "capabilities" message.
+   * @param bool $skip True to skip the "capabilities" message.
    * @return this
    *
    * @task config
@@ -132,7 +132,7 @@ final class ArcanistHgProxyServer extends Phobject {
    * Configure whether the server runs in the foreground or daemonizes.
    * Controlled by --do-not-daemonize. Primarily useful for debugging.
    *
-   * @param bool True to run in the foreground.
+   * @param bool $do_not_daemonize True to run in the foreground.
    * @return this
    *
    * @task config
@@ -252,8 +252,8 @@ final class ArcanistHgProxyServer extends Phobject {
    * process all commands we've received here before returning to the main
    * server loop.
    *
-   * @param ArcanistHgClientChannel The client to update.
+   * @param ArcanistHgClientChannel $client The client to update.
-   * @param ArcanistHgServerChannel The Mercurial server.
+   * @param ArcanistHgServerChannel $hg The Mercurial server.
    *
    * @task server
    */

src/hgdaemon/ArcanistHgServerChannel.php

@@ -80,7 +80,7 @@ final class ArcanistHgServerChannel extends PhutilProtocolChannel {
    *   -l\0
    *   5
    *
-   * @param list<string> List of command arguments.
+   * @param list<string> $argv List of command arguments.
    * @return string Encoded string for transmission to the server.
    *
    * @task protocol
@@ -116,7 +116,7 @@ final class ArcanistHgServerChannel extends PhutilProtocolChannel {
    *
    *   array('o', '<data...>');
    *
-   * @param string Bytes from the server.
+   * @param string $data Bytes from the server.
    * @return list<pair<string,string>> Zero or more complete messages.
    *
    * @task protocol

src/init/lib/PhutilLibraryConflictException.php

@@ -30,10 +30,10 @@ final class PhutilLibraryConflictException extends Exception {
   /**
    * Create a new library conflict exception.
    *
-   * @param string The name of the library which conflicts with an existing
+   * @param string $library The name of the library which conflicts with an
-   *               library.
+   *               existing library.
-   * @param string The path of the already-loaded library.
+   * @param string $old_path The path of the already-loaded library.
-   * @param string The path of the attempting-to-load library.
+   * @param string $new_path The path of the attempting-to-load library.
    *
    * @task construct
    */

src/internationalization/PhutilLocale.php

@@ -30,11 +30,14 @@ abstract class PhutilLocale extends Phobject {
    * For locales like "English (Great Britain)", missing translations can be
    * sourced from "English (US)".
    *
+   * Languages with no other fallback use en_US because that's better
+   * than proto-English for untranslated strings.
+   *
    * @return string|null Locale code of fallback locale, or null if there is
    *                     no fallback locale.
    */
   public function getFallbackLocaleCode() {
-    return null;
+    return 'en_US';
   }
 
 
@@ -42,8 +45,8 @@ abstract class PhutilLocale extends Phobject {
    * Select a gender variant for this locale. By default, locales use a simple
    * rule with two gender variants, listed in "<male, female>" order.
    *
-   * @param const `PhutilPerson` gender constant.
+   * @param const $variant `PhutilPerson` gender constant.
-   * @param list<wild> List of variants.
+   * @param list<wild> $translations List of variants.
    * @return string Variant for use.
    */
   public function selectGenderVariant($variant, array $translations) {
@@ -59,8 +62,8 @@ abstract class PhutilLocale extends Phobject {
    * Select a plural variant for this locale. By default, locales use a simple
    * rule with two plural variants, listed in "<singular, plural>" order.
    *
-   * @param int Plurality of the value.
+   * @param int $variant Plurality of the value.
-   * @param list<wild> List of variants.
+   * @param list<wild> $translations List of variants.
    * @return string Variant for use.
    */
   public function selectPluralVariant($variant, array $translations) {
@@ -118,10 +121,10 @@ abstract class PhutilLocale extends Phobject {
    * from @{method:shouldPostProcessTranslations}. Activating this callback
    * incurs a performance penalty.
    *
-   * @param string The raw input pattern.
+   * @param string $raw_pattern The raw input pattern.
-   * @param string The selected translation pattern.
+   * @param string $translated_pattern The selected translation pattern.
-   * @param list<wild> The raw input arguments.
+   * @param list<wild> $args The raw input arguments.
-   * @param string The translated string.
+   * @param string $result_text The translated string.
    * @return string Post-processed translation string.
    */
   public function didTranslateString(
@@ -192,7 +195,7 @@ abstract class PhutilLocale extends Phobject {
   /**
    * Load a specific locale using a locale code.
    *
-   * @param string Locale code.
+   * @param string $locale_code Locale code.
    * @return PhutilLocale Locale object.
    */
   public static function loadLocale($locale_code) {
@@ -213,9 +216,9 @@ abstract class PhutilLocale extends Phobject {
   /**
    * Recursively check locale fallbacks for cycles.
    *
-   * @param map<string, PhutilLocale> Map of locales.
+   * @param map<string, PhutilLocale> $map Map of locales.
-   * @param PhutilLocale Current locale.
+   * @param PhutilLocale $locale Current locale.
-   * @param map<string, string> Map of visited locales.
+   * @param map<string, string> $seen Map of visited locales.
    * @return void
    */
   private static function checkLocaleFallback(

src/internationalization/PhutilTranslation.php

@@ -59,7 +59,7 @@ abstract class PhutilTranslation extends Phobject {
    * This will compile primary and fallback translations into a single
    * translation map.
    *
-   * @param string Locale code, like "en_US".
+   * @param string $locale_code Locale code, like "en_US".
    * @return map<string, wild> Map of all avialable translations.
    */
   public static function getTranslationMapForLocale($locale_code) {

src/internationalization/PhutilTranslator.php

@@ -64,7 +64,7 @@ final class PhutilTranslator extends Phobject {
    *     '%s owns %s.' => '%2$s is owned by %1$s.',
    *   );
    *
-   * @param array Identifier in key, translation in value.
+   * @param array $translations Identifier in key, translation in value.
    * @return PhutilTranslator Provides fluent interface.
    */
   public function setTranslations(array $translations) {
@@ -212,8 +212,8 @@ final class PhutilTranslator extends Phobject {
   /**
    * Translate date formatted by `$date->format()`.
    *
-   * @param string Format accepted by `DateTime::format()`.
+   * @param string $format Format accepted by `DateTime::format()`.
-   * @param DateTime
+   * @param DateTime $date
    * @return string Formatted and translated date.
    */
   public function translateDate($format, DateTime $date) {
@@ -243,8 +243,8 @@ final class PhutilTranslator extends Phobject {
    * translations of '.' (decimal point) and ',' (thousands separator). Both
    * these translations must be 1 byte long with PHP < 5.4.0.
    *
-   * @param float
+   * @param float $number
-   * @param int
+   * @param int $decimals (optional)
    * @return string
    */
   public function formatNumber($number, $decimals = 0) {

src/internationalization/__tests__/PhutilPhtTestCase.php

@@ -29,73 +29,4 @@ final class PhutilPhtTestCase extends PhutilTestCase {
 
     $this->assertEqual('5 piv', pht('%d beer(s)', 5));
   }
-
-  public function getDateTranslations() {
-    // The only purpose of this function is to provide a static list of
-    // translations which can come from PhutilTranslator::translateDate() to
-    // allow translation extractor getting them.
-    return array(
-      'D' => array(
-        pht('Sun'),
-        pht('Mon'),
-        pht('Tue'),
-        pht('Wed'),
-        pht('Thu'),
-        pht('Fri'),
-        pht('Sat'),
-      ),
-      'l' => array(
-        pht('Sunday'),
-        pht('Monday'),
-        pht('Tuesday'),
-        pht('Wednesday'),
-        pht('Thursday'),
-        pht('Friday'),
-        pht('Saturday'),
-      ),
-      'S' => array(
-        pht('st'),
-        pht('nd'),
-        pht('rd'),
-        pht('th'),
-      ),
-      'F' => array(
-        pht('January'),
-        pht('February'),
-        pht('March'),
-        pht('April'),
-        pht('May'),
-        pht('June'),
-        pht('July'),
-        pht('August'),
-        pht('September'),
-        pht('October'),
-        pht('November'),
-        pht('December'),
-      ),
-      'M' => array(
-        pht('Jan'),
-        pht('Feb'),
-        pht('Mar'),
-        pht('Apr'),
-        pht('May'),
-        pht('Jun'),
-        pht('Jul'),
-        pht('Aug'),
-        pht('Sep'),
-        pht('Oct'),
-        pht('Nov'),
-        pht('Dec'),
-      ),
-      'a' => array(
-        pht('am'),
-        pht('pm'),
-      ),
-      'A' => array(
-        pht('AM'),
-        pht('PM'),
-      ),
-    );
-  }
-
 }

src/internationalization/locales/PhutilPortugueseBrazilLocale.php

@@ -13,4 +13,13 @@ final class PhutilPortugueseBrazilLocale extends PhutilLocale {
     return pht('Portuguese (Brazil)');
   }
 
+  public function getFallbackLocaleCode() {
+    // Phabricator does not support bidirectional
+    // fallbacks (pt_BR -> pt and pt -> pt_BR simultaneously)
+    // since Translatewiki calls pt_PT "Portugese" without a country
+    // it makes slightly more sense to fall back in this direction
+    // than the other one
+    return 'pt_PT';
+  }
+
 }

src/internationalization/locales/PhutilPortuguesePortugalLocale.php

@@ -13,4 +13,14 @@ final class PhutilPortuguesePortugalLocale extends PhutilLocale {
     return pht('Portuguese (Portugal)');
   }
 
+  public function getFallbackLocaleCode() {
+    // Ideally this would be pt_BR but Phabricator does not support
+    // bidirectional fallbacks (pt_BR -> pt and pt -> pt_BR simultaneously)
+    // since Translatewiki calls pt_PT "Portugese" without a country
+    // it makes slightly more sense to fall back in the other direction
+    // In the mean time return `en_US` so users don't see Proto-English
+    // unncecessarily
+    return 'en_US';
+  }
+
 }

src/internationalization/locales/PhutilSimplifiedChineseLocale.php

@@ -13,4 +13,13 @@ final class PhutilSimplifiedChineseLocale extends PhutilLocale {
     return pht('Chinese (Simplified)');
   }
 
+  public function getFallbackLocaleCode() {
+    // Ideally this would be zh_Hant but Phabricator does not support
+    //  bidirectional fallbacks
+    // (zh_Hant -> zh_Hans and zh_Hans -> zh_Hant simultaneously)
+    // arbitrarily choose to fall back in the other direction instead
+    // In the mean time return `en_US` so users don't see Proto-English
+    return 'en_US';
+  }
+
 }

src/internationalization/locales/PhutilTraditionalChineseLocale.php

@@ -13,4 +13,8 @@ final class PhutilTraditionalChineseLocale extends PhutilLocale {
     return pht('Chinese (Traditional)');
   }
 
+  public function getFallbackLocaleCode() {
+    return 'zh_Hans';
+  }
+
 }

src/internationalization/locales/PhutilUSEnglishLocale.php

@@ -13,4 +13,10 @@ final class PhutilUSEnglishLocale extends PhutilLocale {
     return pht('English (US)');
   }
 
+  public function getFallbackLocaleCode() {
+    // The default fallback is en_US, explicitly return null here
+    // to avoid a fallback loop
+    return null;
+  }
+
 }

src/internationalization/pht.php

@@ -6,8 +6,9 @@
  * `PhutilTranslator::getInstance()->setTranslations()` and language rules set
  * by `PhutilTranslator::getInstance()->setLocale()`.
  *
- * @param string Translation identifier with `sprintf()` placeholders.
+ * @param string $text Translation identifier with `sprintf()` placeholders.
- * @param mixed Value to select the variant from (e.g. singular or plural).
+ * @param mixed $variant (optional) Value to select the variant from (e.g.
+ *    singular or plural). Defaults to null.
  * @param ... Next values referenced from $text.
  * @return string Translated string with substituted values.
  */
@@ -20,7 +21,7 @@ function pht($text, $variant = null /* , ... */) {
 /**
  * Count all elements in an array, or something in an object.
  *
- * @param  array|Countable  A countable object.
+ * @param  array|Countable  $countable A countable object.
  * @return PhutilNumber     Returns the number of elements in the input
  *                          parameter.
  */
@@ -38,7 +39,8 @@ function phutil_count($countable) {
  * This function does nothing and only serves as a marker for the static
  * extractor so it knows particular arguments may vary on gender.
  *
- * @param PhutilPerson Something implementing @{interface:PhutilPerson}.
+ * @param PhutilPerson $person Something implementing
+ *   @{interface:PhutilPerson}.
  * @return PhutilPerson The argument, unmodified.
  */
 function phutil_person(PhutilPerson $person) {

src/land/engine/ArcanistLandEngine.php

@@ -1420,7 +1420,8 @@ abstract class ArcanistLandEngine
    * and min is the earliest ancestor. This is done so that non-landing commits
    * that are descendants of the latest revision will only be rebased once.
    *
-   * @param ArcanistLandCommitSet  The current commit set to cascade.
+   * @param ArcanistLandCommitSet $set The current commit set to cascade.
+   * @param string $into_commit The commit hash that was landed into.
    */
   abstract protected function cascadeState(
     ArcanistLandCommitSet $set,
@@ -1434,7 +1435,7 @@ abstract class ArcanistLandEngine
    * Prunes the given sets of commits. This should be called after the sets
    * have been merged.
    *
-   * @param array  The list of ArcanistLandCommitSet to prune, in order of
+   * @param array $sets The list of ArcanistLandCommitSet to prune, in order of
    *   min to max commit set, where min is the earliest ancestor and max
    *   is the latest descendant.
    */
@@ -1445,9 +1446,10 @@ abstract class ArcanistLandEngine
    * should only be called after all changes have been merged, pruned, and
    * pushed.
    *
-   * @param string  The commit hash that was landed into.
+   * @param string $into_commit The commit hash that was landed into.
-   * @param ArcanistRepositoryLocalState  The local state that was captured
+   * @param ArcanistRepositoryLocalState $state The local state that was
-   *   at the beginning of the land process. This may include stashed changes.
+   *   captured at the beginning of the land process. This may include stashed
+   *   changes.
    */
   abstract protected function reconcileLocalState(
     $into_commit,
@@ -1457,7 +1459,7 @@ abstract class ArcanistLandEngine
    * Display information to the user about how to proceed since the land
    * process was not fully completed. The merged branch has not been pushed.
    *
-   * @param string  The commit hash that was landed into.
+   * @param string $into_commit The commit hash that was landed into.
    */
   abstract protected function didHoldChanges($into_commit);
 

src/lexer/PhutilLexer.php

@@ -233,8 +233,8 @@ abstract class PhutilLexer extends Phobject {
   /**
    * Lex an input string into tokens.
    *
-   * @param string Input string.
+   * @param string $input Input string.
-   * @param string Initial lexer state.
+   * @param string $initial_state (optional) Initial lexer state.
    * @return list List of lexer tokens.
    * @task tokens
    */

src/lexer/PhutilShellLexer.php

@@ -21,7 +21,7 @@ final class PhutilShellLexer extends PhutilLexer {
    *     "\"",
    *   );
    *
-   * @param   string  Shell command string.
+   * @param   string  $string Shell command string.
    * @return  array   Parsed argument vector.
    */
   public function splitArguments($string) {

src/lint/ArcanistLintMessage.php

@@ -184,7 +184,7 @@ final class ArcanistLintMessage extends Phobject {
   }
 
   /**
-   * @param dict Keys 'path', 'line', 'char', 'original'.
+   * @param dict $locations Keys 'path', 'line', 'char', 'original'.
    */
   public function setOtherLocations(array $locations) {
     assert_instances_of($locations, 'array');
@@ -272,7 +272,8 @@ final class ArcanistLintMessage extends Phobject {
    * less strict in linters themselves, since they often parse command line
    * output or XML and will end up with string representations of numbers.
    *
-   * @param mixed Integer or digit string.
+   * @param mixed $value Integer or digit string.
+   * @param mixed $caller
    * @return int Integer.
    */
   private function validateInteger($value, $caller) {

src/lint/engine/ArcanistLintEngine.php

@@ -291,6 +291,7 @@ abstract class ArcanistLintEngine extends Phobject {
 
   /**
    * @param dict<string path, dict<string version, list<dict message>>>
+   *   $results
    * @return this
    */
   final public function setCachedResults(array $results) {
@@ -419,9 +420,9 @@ abstract class ArcanistLintEngine extends Phobject {
    * construction of the result so it doesn't need to be built multiple
    * times.
    *
-   * @param string  Resource identifier.
+   * @param string  $key Resource identifier.
-   * @param wild    Optionally, default value to return if resource does not
+   * @param wild    $default (optional) Default value to return if resource
-   *                exist.
+   *                does not exist.
    * @return wild   Resource, or default value if not present.
    */
   public function getLinterResource($key, $default = null) {
@@ -434,8 +435,8 @@ abstract class ArcanistLintEngine extends Phobject {
    *
    * See @{method:getLinterResource} for a description of this mechanism.
    *
-   * @param string Resource identifier.
+   * @param string $key Resource identifier.
-   * @param wild   Resource.
+   * @param wild   $value Resource.
    * @return this
    */
   public function setLinterResource($key, $value) {

src/lint/linter/ArcanistBaseXHPASTLinter.php

@@ -101,7 +101,7 @@ abstract class ArcanistBaseXHPASTLinter extends ArcanistFutureLinter {
   /**
    * Build futures on this linter, for use and to share with other linters.
    *
-   * @param list<string> Paths to build futures for.
+   * @param list<string> $paths Paths to build futures for.
    * @return list<ExecFuture> Futures.
    * @task sharing
    */
@@ -122,7 +122,7 @@ abstract class ArcanistBaseXHPASTLinter extends ArcanistFutureLinter {
   /**
    * Release futures on this linter which are no longer in use elsewhere.
    *
-   * @param list<string> Paths to release futures for.
+   * @param list<string> $paths Paths to release futures for.
    * @return void
    * @task sharing
    */
@@ -152,7 +152,7 @@ abstract class ArcanistBaseXHPASTLinter extends ArcanistFutureLinter {
   /**
    * Get a path's tree from the responsible linter.
    *
-   * @param   string           Path to retrieve tree for.
+   * @param   string           $path Path to retrieve tree for.
    * @return  XHPASTTree|null  Tree, or null if unparseable.
    * @task sharing
    */
@@ -188,7 +188,7 @@ abstract class ArcanistBaseXHPASTLinter extends ArcanistFutureLinter {
   /**
    * Get a path's parse exception from the responsible linter.
    *
-   * @param   string          Path to retrieve exception for.
+   * @param   string          $path Path to retrieve exception for.
    * @return  Exception|null  Parse exception, if available.
    * @task sharing
    */
@@ -209,8 +209,8 @@ abstract class ArcanistBaseXHPASTLinter extends ArcanistFutureLinter {
    * Returns all descendant nodes which represent a function call to one of the
    * specified functions.
    *
-   * @param  XHPASTNode    Root node.
+   * @param  XHPASTNode    $root Root node.
-   * @param  list<string>  Function names.
+   * @param  list<string>  $function_names Function names.
    * @return AASTNodeList
    */
   protected function getFunctionCalls(XHPASTNode $root, array $function_names) {

src/lint/linter/ArcanistChmodLinter.php

@@ -117,7 +117,7 @@ final class ArcanistChmodLinter extends ArcanistLinter {
   /**
    * Returns the path's shebang.
    *
-   * @param  string
+   * @param  string $path
    * @return string|null
    */
   private function getShebang($path) {

src/lint/linter/ArcanistExternalLinter.php

@@ -104,7 +104,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter {
    * Override default flags with custom flags. If not overridden, flags provided
    * by @{method:getDefaultFlags} are used.
    *
-   * @param list<string> New flags.
+   * @param list<string> $flags New flags.
    * @return this
    * @task bin
    */
@@ -116,7 +116,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter {
   /**
    * Set the binary's version requirement.
    *
-   * @param string Version requirement.
+   * @param string $version Version requirement.
    * @return this
    * @task bin
    */
@@ -151,7 +151,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter {
   /**
    * Override the default binary with a new one.
    *
-   * @param string  New binary.
+   * @param string $bin New binary.
    * @return this
    * @task bin
    */
@@ -200,7 +200,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter {
   /**
    * Set the interpreter, overriding any default.
    *
-   * @param string New interpreter.
+   * @param string $interpreter New interpreter.
    * @return this
    * @task bin
    */
@@ -223,10 +223,10 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter {
    * you're able to detect a more specific condition.) Otherwise, return a list
    * of messages.
    *
-   * @param  string   Path to the file being linted.
+   * @param  string   $path Path to the file being linted.
-   * @param  int      Exit code of the linter.
+   * @param  int      $err Exit code of the linter.
-   * @param  string   Stdout of the linter.
+   * @param  string   $stdout Stdout of the linter.
-   * @param  string   Stderr of the linter.
+   * @param  string   $stderr Stderr of the linter.
    * @return list<ArcanistLintMessage>|false  List of lint messages, or false
    *                                          to indicate parser failure.
    * @task parse
@@ -298,7 +298,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter {
    * of the configured binary to the required version, and if the binary's
    * version is not supported, throw an exception.
    *
-   * @param  string   Version string to check.
+   * @param  string   $version Version string to check.
    * @return void
    */
   final protected function checkBinaryVersion($version) {
@@ -415,7 +415,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter {
    *
    * This method is expected to return an already escaped string.
    *
-   * @param string Path to the file being linted
+   * @param string $path Path to the file being linted
    * @return string The command-ready file argument
    */
   protected function getPathArgumentForLinterFuture($path) {
@@ -572,7 +572,7 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter {
    *
    * If the code is not recognized, you should throw an exception.
    *
-   * @param string  Code specified in configuration.
+   * @param string   $code Code specified in configuration.
    * @return string  Normalized code to use in severity map.
    */
   protected function getLintCodeFromLinterConfigurationKey($code) {

src/lint/linter/ArcanistFutureLinter.php

@@ -47,7 +47,7 @@ abstract class ArcanistFutureLinter extends ArcanistLinter {
    * This is invoked after a block of futures resolve, and allows linters to
    * discard or clean up any shared resources they no longer need.
    *
-   * @param map<string, Future> Map of paths to resolved futures.
+   * @param map<string, Future> $futures Map of paths to resolved futures.
    * @return void
    */
   protected function didResolveLinterFutures(array $futures) {

src/lint/linter/ArcanistLinter.php

@@ -131,7 +131,7 @@ abstract class ArcanistLinter extends Phobject {
    *
    * This ID is assigned automatically by the @{class:ArcanistLintEngine}.
    *
-   * @param string Unique linter ID.
+   * @param string $id Unique linter ID.
    * @return this
    * @task state
    */
@@ -168,7 +168,7 @@ abstract class ArcanistLinter extends Phobject {
    * Linters which are not parallelizable should normally ignore this callback
    * and implement @{method:lintPath} instead.
    *
-   * @param list<string> A list of paths to be linted
+   * @param list<string> $paths A list of paths to be linted
    * @return void
    * @task exec
    */
@@ -185,7 +185,7 @@ abstract class ArcanistLinter extends Phobject {
    * Linters which are parallelizable may want to ignore this callback and
    * implement @{method:willLintPaths} and @{method:didLintPaths} instead.
    *
-   * @param string Path to lint.
+   * @param string $path Path to lint.
    * @return void
    * @task exec
    */
@@ -202,7 +202,7 @@ abstract class ArcanistLinter extends Phobject {
    * Linters which are not paralleizable should normally ignore this callback
    * and implement @{method:lintPath} instead.
    *
-   * @param list<string> A list of paths which were linted.
+   * @param list<string> $paths A list of paths which were linted.
    * @return void
    * @task exec
    */
@@ -288,7 +288,7 @@ abstract class ArcanistLinter extends Phobject {
    * Filter out paths which this linter doesn't act on (for example, because
    * they are binaries and the linter doesn't apply to binaries).
    *
-   * @param  list<string>
+   * @param  list<string> $paths
    * @return list<string>
    */
   private function filterPaths(array $paths) {
@@ -617,7 +617,7 @@ abstract class ArcanistLinter extends Phobject {
    *
    * If the code is not recognized, you should throw an exception.
    *
-   * @param string  Code specified in configuration.
+   * @param string   $code Code specified in configuration.
    * @return string  Normalized code to use in severity map.
    */
   protected function getLintCodeFromLinterConfigurationKey($code) {

src/lint/linter/ArcanistScriptAndRegexLinter.php

@@ -324,7 +324,8 @@ final class ArcanistScriptAndRegexLinter extends ArcanistLinter {
   /**
    * Get the line and character of the message from the regex match.
    *
-   * @param dict Captured groups from regex.
+   * @param dict $match Captured groups from regex.
+   * @param string $path
    * @return pair<int|null,int|null> Line and character of the message.
    *
    * @task parse
@@ -362,7 +363,7 @@ final class ArcanistScriptAndRegexLinter extends ArcanistLinter {
    * a nonempty severity name group like 'error', or a group called 'severity'
    * with a valid name.
    *
-   * @param dict Captured groups from regex.
+   * @param dict $match Captured groups from regex.
    * @return const  @{class:ArcanistLintSeverity} constant.
    *
    * @task parse

src/lint/linter/ArcanistXHPASTLinter.php

@@ -29,7 +29,7 @@ final class ArcanistXHPASTLinter extends ArcanistBaseXHPASTLinter {
    * This is primarily useful for unit tests in which it is desirable to test
    * linter rules in isolation. By default, all linter rules will be enabled.
    *
-   * @param  list<ArcanistXHPASTLinterRule>
+   * @param  list<ArcanistXHPASTLinterRule> $rules
    * @return this
    */
   public function setRules(array $rules) {

src/lint/linter/__tests__/ArcanistLinterTestCase.php

@@ -305,8 +305,8 @@ abstract class ArcanistLinterTestCase extends PhutilTestCase {
   /**
    * Compare properties of @{class:ArcanistLintMessage} instances.
    *
-   * @param  wild
+   * @param  wild $x
-   * @param  wild
+   * @param  wild $y
    * @return bool
    */
   private static function compareLintMessageProperty($x, $y) {

src/lint/linter/standards/ArcanistLinterStandard.php

@@ -35,7 +35,7 @@ abstract class ArcanistLinterStandard extends Phobject {
   /**
    * Checks whether the linter standard supports a specified linter.
    *
-   * @param  ArcanistLinter  The linter which is being configured.
+   * @param  ArcanistLinter  $linter The linter which is being configured.
    * @return bool            True if the linter standard supports the specified
    *                         linter, otherwise false.
    */
@@ -68,8 +68,8 @@ abstract class ArcanistLinterStandard extends Phobject {
   /**
    * Load a linter standard by key.
    *
-   * @param  string
+   * @param  string $key
-   * @param  ArcanistLinter
+   * @param  ArcanistLinter $linter
    * @return ArcanistLinterStandard
    */
   final public static function getStandard($key, ArcanistLinter $linter) {
@@ -100,7 +100,7 @@ abstract class ArcanistLinterStandard extends Phobject {
   /**
    * Load all linter standards which support a specified linter.
    *
-   * @param  ArcanistLinter
+   * @param  ArcanistLinter $linter
    * @return list<ArcanistLinterStandard>
    */
   final public static function loadAllStandardsForLinter(

src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php

@@ -45,12 +45,13 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject {
    *   }
    *   return $default;
    *
-   * @param   string      The symbol type.
+   * @param   string      $type The symbol type.
-   * @param   string      The symbol name.
+   * @param   string      $name The symbol name.
-   * @param   string|null The default result from the main rule engine.
+   * @param   string|null $default The default result from the main rule
+   *                      engine.
    * @return  string|null Null to accept the name, or a message to reject it
-   *                      with. You should return the default value if you don't
+   *                      with. You should return the default value if you
-   *                      want to specifically provide an override.
+   *                      don't want to specifically provide an override.
    * @task override
    */
   abstract public function lintSymbolName($type, $name, $default);
@@ -61,7 +62,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject {
   /**
    * Returns true if a symbol name is UpperCamelCase.
    *
-   * @param string Symbol name.
+   * @param string $symbol Symbol name.
    * @return bool True if the symbol is UpperCamelCase.
    * @task util
    */
@@ -72,7 +73,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject {
   /**
    * Returns true if a symbol name is lowerCamelCase.
    *
-   * @param string Symbol name.
+   * @param string $symbol Symbol name.
    * @return bool True if the symbol is lowerCamelCase.
    * @task util
    */
@@ -83,7 +84,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject {
   /**
    * Returns true if a symbol name is UPPERCASE_WITH_UNDERSCORES.
    *
-   * @param string Symbol name.
+   * @param string $symbol Symbol name.
    * @return bool True if the symbol is UPPERCASE_WITH_UNDERSCORES.
    * @task util
    */
@@ -94,7 +95,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject {
   /**
    * Returns true if a symbol name is lowercase_with_underscores.
    *
-   * @param string Symbol name.
+   * @param string $symbol Symbol name.
    * @return bool True if the symbol is lowercase_with_underscores.
    * @task util
    */
@@ -107,7 +108,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject {
    * the "__" magic-method signifier, to make a symbol appropriate for testing
    * with methods like @{method:isLowerCamelCase}.
    *
-   * @param   string Symbol name.
+   * @param   string $symbol Symbol name.
    * @return  string Stripped symbol.
    * @task util
    */
@@ -142,7 +143,7 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject {
    * the "$", to make a symbol appropriate for testing with methods like
    * @{method:isLowercaseWithUnderscores}.
    *
-   * @param string Symbol name.
+   * @param string $symbol Symbol name.
    * @return string Stripped symbol.
    * @task util
    */

src/lint/linter/xhpast/ArcanistXHPASTLinterRule.php

@@ -144,7 +144,7 @@ abstract class ArcanistXHPASTLinterRule extends Phobject {
    *
    * TODO: Improve this and move it to XHPAST proper?
    *
-   * @param  string  The "semantic string" of a single value.
+   * @param  string  $string The "semantic string" of a single value.
    * @return mixed   `true` or `false` if the value could be evaluated
    *                 statically; `null` if static evaluation was not possible.
    */
@@ -168,7 +168,7 @@ abstract class ArcanistXHPASTLinterRule extends Phobject {
    * Returns all descendant nodes which represent an anonymous function
    * declaration.
    *
-   * @param  XHPASTNode    Root node.
+   * @param  XHPASTNode    $root Root node.
    * @return AASTNodeList
    */
   protected function getAnonymousClosures(XHPASTNode $root) {
@@ -187,7 +187,7 @@ abstract class ArcanistXHPASTLinterRule extends Phobject {
   /**
    * TODO
    *
-   * @param  XHPASTNode
+   * @param  XHPASTNode $variable
    * @return string
    */
   protected function getConcreteVariableString(XHPASTNode $variable) {
@@ -205,8 +205,8 @@ abstract class ArcanistXHPASTLinterRule extends Phobject {
    * Returns all descendant nodes which represent a function call to one of the
    * specified functions.
    *
-   * @param  XHPASTNode    Root node.
+   * @param  XHPASTNode    $root Root node.
-   * @param  list<string>  Function names.
+   * @param  list<string>  $function_names Function names.
    * @return AASTNodeList
    */
   protected function getFunctionCalls(XHPASTNode $root, array $function_names) {
@@ -228,7 +228,7 @@ abstract class ArcanistXHPASTLinterRule extends Phobject {
   /**
    * Get class/method modifiers.
    *
-   * @param  XHPASTNode         A node of type `n_CLASS_DECLARATION` or
+   * @param  XHPASTNode         $node A node of type `n_CLASS_DECLARATION` or
    *                            `n_METHOD_DECLARATION`.
    * @return map<string, bool>  Class/method modifiers.
    */

src/moduleutils/PhutilLibraryMapBuilder.php

@@ -29,7 +29,7 @@ final class PhutilLibraryMapBuilder extends Phobject {
   /**
    * Create a new map builder for a library.
    *
-   * @param string Path to the library root.
+   * @param string $root Path to the library root.
    *
    * @task map
    */
@@ -40,7 +40,7 @@ final class PhutilLibraryMapBuilder extends Phobject {
   /**
    * Control subprocess parallelism limit. Use `--limit` to set this.
    *
-   * @param  int   Maximum number of subprocesses to run in parallel.
+   * @param  int   $limit Maximum number of subprocesses to run in parallel.
    * @return this
    *
    * @task map
@@ -103,8 +103,8 @@ final class PhutilLibraryMapBuilder extends Phobject {
   /**
    * Get the path to some file in the library.
    *
-   * @param  string  A library-relative path. If omitted, returns the library
+   * @param  string  $path (optional) A library-relative path. If omitted,
-   *                 root path.
+   *                 returns the library root path.
    * @return string  An absolute path.
    *
    * @task path
@@ -188,8 +188,8 @@ final class PhutilLibraryMapBuilder extends Phobject {
   /**
    * Write a symbol map to disk cache.
    *
-   * @param  dict  Symbol map of relative paths to symbols.
+   * @param  dict  $symbol_map Symbol map of relative paths to symbols.
-   * @param  dict  Source map (like @{method:loadSourceFileMap}).
+   * @param  dict  $source_map Source map (like @{method:loadSourceFileMap}).
    * @return void
    *
    * @task symbol
@@ -212,7 +212,7 @@ final class PhutilLibraryMapBuilder extends Phobject {
   /**
    * Drop the symbol cache, forcing a clean rebuild.
    *
-   * @return this
+   * @return void
    *
    * @task symbol
    */
@@ -224,7 +224,7 @@ final class PhutilLibraryMapBuilder extends Phobject {
    * Build a future which returns a `extract-symbols.php` analysis of a source
    * file.
    *
-   * @param  string  Relative path to the source file to analyze.
+   * @param  string  $file Relative path to the source file to analyze.
    * @return Future  Analysis future.
    *
    * @task symbol
@@ -321,7 +321,7 @@ final class PhutilLibraryMapBuilder extends Phobject {
    * Convert the symbol analysis of all the source files in the library into
    * a library map.
    *
-   * @param   dict  Symbol analysis of all source files.
+   * @param   dict  $symbol_map Symbol analysis of all source files.
    * @return  dict  Library map.
    * @task source
    */
@@ -381,7 +381,7 @@ final class PhutilLibraryMapBuilder extends Phobject {
   /**
    * Write a finalized library map.
    *
-   * @param  dict Library map structure to write.
+   * @param  dict $library_map Library map structure to write.
    * @return void
    *
    * @task source

src/object/Phobject.php

@@ -73,8 +73,9 @@ abstract class Phobject implements Iterator {
    * useful message if the constant is not defined and allows the constant to
    * be limited to a maximum length.
    *
-   * @param string Name of the constant.
+   * @param string $key Name of the constant.
-   * @param int|null Maximum number of bytes permitted in the value.
+   * @param int|null $byte_limit (optional) Maximum number of bytes permitted
+   *   in the value.
    * @return string Value of the constant.
    */
   public function getPhobjectClassConstant($key, $byte_limit = null) {

src/parser/ArcanistDiffParser.php

@@ -1329,7 +1329,7 @@ final class ArcanistDiffParser extends Phobject {
    * return an incorrect value.  Such cases are expected to be
    * recovered by later rename detection codepaths.
    *
-   * @param string Text from a diff line after "diff --git ".
+   * @param string $paths Text from a diff line after "diff --git ".
    * @return string Filename being altered, or null for a rename.
    */
   public static function extractGitCommonFilename($paths) {

src/parser/PhutilEditorConfig.php

@@ -41,7 +41,7 @@ final class PhutilEditorConfig extends Phobject {
   /**
    * Constructor.
    *
-   * @param string  The root directory.
+   * @param string $root The root directory.
    */
   public function __construct($root) {
     $this->root = $root;
@@ -50,8 +50,8 @@ final class PhutilEditorConfig extends Phobject {
   /**
    * Get the specified EditorConfig property for the specified path.
    *
-   * @param  string
+   * @param  string $path
-   * @param  string
+   * @param  string $key
    * @return wild
    */
   public function getProperty($path, $key) {
@@ -100,7 +100,7 @@ final class PhutilEditorConfig extends Phobject {
    *   the future).
    * - Invalid glob patterns will be silently ignored.
    *
-   * @param  string
+   * @param  string $path
    * @return map<string, wild>
    */
   public function getProperties($path) {

src/parser/PhutilJSON.php

@@ -16,7 +16,7 @@ final class PhutilJSON extends Phobject {
    * Encode an object in JSON and pretty-print it. This generates a valid JSON
    * object with human-readable whitespace and indentation.
    *
-   * @param   dict    An object to encode in JSON.
+   * @param   dict    $object An object to encode in JSON.
    * @return  string  Pretty-printed object representation.
    */
   public function encodeFormatted($object) {
@@ -27,7 +27,7 @@ final class PhutilJSON extends Phobject {
   /**
    * Encode a list in JSON and pretty-print it, discarding keys.
    *
-   * @param list<wild> List to encode in JSON.
+   * @param list<wild> $list List to encode in JSON.
    * @return string Pretty-printed list representation.
    */
   public function encodeAsList(array $list) {
@@ -41,8 +41,8 @@ final class PhutilJSON extends Phobject {
   /**
    * Pretty-print a JSON object.
    *
-   * @param   dict    Object to format.
+   * @param   dict    $object Object to format.
-   * @param   int     Current depth, for indentation.
+   * @param   int     $depth Current depth, for indentation.
    * @return  string  Pretty-printed value.
    * @task internal
    */
@@ -84,8 +84,8 @@ final class PhutilJSON extends Phobject {
   /**
    * Pretty-print a JSON list.
    *
-   * @param   list    List to format.
+   * @param   list    $array List to format.
-   * @param   int     Current depth, for indentation.
+   * @param   int     $depth Current depth, for indentation.
    * @return  string  Pretty-printed value.
    * @task internal
    */
@@ -115,8 +115,8 @@ final class PhutilJSON extends Phobject {
   /**
    * Pretty-print a JSON value.
    *
-   * @param   dict    Value to format.
+   * @param   dict    $value Value to format.
-   * @param   int     Current depth, for indentation.
+   * @param   int     $depth Current depth, for indentation.
    * @return  string  Pretty-printed value.
    * @task internal
    */
@@ -146,7 +146,7 @@ final class PhutilJSON extends Phobject {
   /**
    * Render a string corresponding to the current indent depth.
    *
-   * @param   int     Current depth.
+   * @param   int     $depth Current depth.
    * @return  string  Indentation.
    * @task internal
    */

src/parser/PhutilLanguageGuesser.php

@@ -9,7 +9,7 @@ final class PhutilLanguageGuesser extends Phobject {
   /**
    * Guess which computer programming language a file is written in.
    *
-   * @param string Source text of the file.
+   * @param string $source Source text of the file.
    * @return mixed Language string, or null if unable to guess.
    */
   public static function guessLanguage($source) {

src/parser/PhutilQueryStringParser.php

@@ -33,7 +33,7 @@ final class PhutilQueryStringParser extends Phobject {
    *
    * For a more basic parse, see @{method:parseQueryStringToPairList}.
    *
-   * @param   string              Query string.
+   * @param   string              $query_string Query string.
    * @return  map<string, wild>   Parsed dictionary.
    */
   public function parseQueryString($query_string) {
@@ -68,7 +68,7 @@ final class PhutilQueryStringParser extends Phobject {
    * Use @{method:parseQueryString} to produce a more sophisticated parse which
    * applies array rules and returns a dictionary.
    *
-   * @param   string                      Query string.
+   * @param   string                      $query_string Query string.
    * @return  list<pair<string, string>>  List of parsed parameters.
    */
   public function parseQueryStringToPairList($query_string) {
@@ -110,7 +110,7 @@ final class PhutilQueryStringParser extends Phobject {
    *
    * @param string $key
    * @param string $val
-   * @param array  $input_arr
+   * @param array  &$input_arr
    */
   private function parseQueryKeyToArr($key, $val, array &$input_arr) {
     if (preg_match('/^[^\[\]]+(?:\[[^\[\]]*\])+$/', $key)) {

src/parser/PhutilSimpleOptions.php

@@ -31,7 +31,7 @@ final class PhutilSimpleOptions extends Phobject {
    *      'eyes' => '2',
    *    );
    *
-   * @param   string  Input option list.
+   * @param   string  $input Input option list.
    * @return  dict    Parsed dictionary.
    * @task parse
    */
@@ -130,8 +130,8 @@ final class PhutilSimpleOptions extends Phobject {
    *
    *    legs=4, eyes=2
    *
-   * @param   dict    Input dictionary.
+   * @param   dict    $options Input dictionary.
-   * @param   string  Additional characters to escape.
+   * @param   string  $escape (optional) Additional characters to escape.
    * @return  string  Unparsed option list.
    */
   public function unparse(array $options, $escape = '') {
@@ -161,8 +161,8 @@ final class PhutilSimpleOptions extends Phobject {
    * case insensitive, so "legs=4" has the same meaning as "LEGS=4". If you
    * set it to be case sensitive, the keys have different meanings.
    *
-   * @param bool  True to make the parser case sensitive, false (default) to
+   * @param bool  $case_sensitive True to make the parser case sensitive, false
-   *              make it case-insensitive.
+   *              to make it case-insensitive.
    * @return this
    * @task config
    */

src/parser/aast/api/AASTNode.php

@@ -363,7 +363,7 @@ abstract class AASTNode extends Phobject {
    * Determines whether the current node appears //after// a specified node in
    * the tree.
    *
-   * @param  AASTNode
+   * @param  AASTNode $node
    * @return bool
    */
   final public function isAfter(AASTNode $node) {
@@ -375,7 +375,7 @@ abstract class AASTNode extends Phobject {
    * Determines whether the current node appears //before// a specified node in
    * the tree.
    *
-   * @param  AASTNode
+   * @param  AASTNode $node
    * @return bool
    */
   final public function isBefore(AASTNode $node) {
@@ -386,7 +386,7 @@ abstract class AASTNode extends Phobject {
   /**
    * Determines whether a specified node is a descendant of the current node.
    *
-   * @param  AASTNode
+   * @param  AASTNode $node
    * @return bool
    */
   final public function containsDescendant(AASTNode $node) {

src/parser/argument/PhutilArgumentParser.php

@@ -95,7 +95,7 @@ final class PhutilArgumentParser extends Phobject {
    *
    *   $args = new PhutilArgumentParser($argv);
    *
-   * @param list  Argument vector to parse, generally the $argv global.
+   * @param list $argv Argument vector to parse, generally the $argv global.
    * @task parse
    */
   public function __construct(array $argv) {
@@ -111,9 +111,10 @@ final class PhutilArgumentParser extends Phobject {
    * @{method:getUnconsumedArgumentVector}. Doing a partial parse can make it
    * easier to share common flags across scripts or workflows.
    *
-   * @param   list  List of argument specs, see
+   * @param   list  $specs List of argument specs, see
    *                @{class:PhutilArgumentSpecification}.
-   * @param bool Require flags appear before any non-flag arguments.
+   * @param bool $initial_only (optional) Require flags appear before any
+   *             non-flag arguments.
    * @return  this
    * @task parse
    */
@@ -310,7 +311,7 @@ final class PhutilArgumentParser extends Phobject {
    * user-friendly error. You can also use @{method:printUsageException} to
    * render the exception in a user-friendly way.
    *
-   * @param   list  List of argument specs, see
+   * @param   list  $specs List of argument specs, see
    *                @{class:PhutilArgumentSpecification}.
    * @return  this
    * @task parse
@@ -346,7 +347,7 @@ final class PhutilArgumentParser extends Phobject {
    * Parse and consume a list of arguments, raising a user-friendly error if
    * anything remains. See also @{method:parseFull} and @{method:parsePartial}.
    *
-   * @param   list  List of argument specs, see
+   * @param   list  $specs List of argument specs, see
    *                @{class:PhutilArgumentSpecification}.
    * @return  this
    * @task parse
@@ -367,7 +368,7 @@ final class PhutilArgumentParser extends Phobject {
    *
    * See @{class:PhutilArgumentWorkflow} for details on using workflows.
    *
-   * @param   list  List of argument specs, see
+   * @param   list  $workflows List of argument specs, see
    *                @{class:PhutilArgumentSpecification}.
    * @return  this
    * @task parse
@@ -391,7 +392,7 @@ final class PhutilArgumentParser extends Phobject {
    *
    * See @{class:PhutilArgumentWorkflow} for details on using workflows.
    *
-   * @param list List of @{class:PhutilArgumentWorkflow}s.
+   * @param list $workflows List of @{class:PhutilArgumentWorkflow}s.
    * @return PhutilArgumentWorkflow|no  Returns the chosen workflow if it is
    *                                    not executable, or executes it and
    *                                    exits with a return code if it is.

src/parser/argument/PhutilArgumentSpecification.php

@@ -34,7 +34,7 @@ final class PhutilArgumentSpecification extends Phobject {
    *    wildcard    setWildcard()
    *    repeat      setRepeatable()
    *
-   * @param dict Dictionary of quick parameter definitions.
+   * @param dict $spec Dictionary of quick parameter definitions.
    * @return PhutilArgumentSpecification Constructed argument specification.
    */
   public static function newQuickSpec(array $spec) {

src/parser/xhpast/api/XHPASTNode.php

@@ -292,7 +292,6 @@ final class XHPASTNode extends AASTNode {
    * To prevent any possible ambiguity, the returned namespace will always be
    * prefixed with the namespace separator.
    *
-   * @param  XHPASTNode   The input node.
    * @return string|null  The namespace which contains the input node, or
    *                      `null` if no such node exists.
    */

src/parser/xhpast/api/__tests__/XHPASTNodeTestCase.php

@@ -73,7 +73,7 @@ final class XHPASTNodeTestCase extends PhutilTestCase {
    * }
    * ```
    *
-   * @param  string                 The path to the test file.
+   * @param  string                 $file The path to the test file.
    * @return pair<XHPASTTree, map>  The first element of the pair is the
    *                                `XHPASTTree` contained within the test file.
    *                                The second element of the pair is the

src/parser/xhpast/bin/PhutilXHPASTBinary.php

@@ -71,7 +71,7 @@ final class PhutilXHPASTBinary extends Phobject {
   /**
    * Constructs an @{class:ExecFuture} for XHPAST.
    *
-   * @param  wild        Data to pass to the future.
+   * @param  wild       $data Data to pass to the future.
    * @return ExecFuture
    */
   public static function getParserFuture($data) {

src/phage/bootloader/PhagePHPAgentBootloader.php

@@ -89,7 +89,7 @@ final class PhagePHPAgentBootloader extends PhageAgentBootloader {
       $boot_length = strlen($boot_sequence->toString());
       $boot_sequence->addText($main_sequence->toString());
 
-      if (strlen($boot_length) > 8192) {
+      if ($boot_length > 8192) {
         throw new Exception(pht('Stage 1 bootloader is too large!'));
       }
 

src/readableserializer/PhutilReadableSerializer.php

@@ -19,7 +19,7 @@ final class PhutilReadableSerializer extends Phobject {
    * representation of the value; use @{method:printShort} or
    * @{method:printShallow} to summarize values.
    *
-   * @param wild Any value.
+   * @param wild $value Any value.
    * @return string Human-readable representation of the value.
    * @task print
    */
@@ -43,7 +43,7 @@ final class PhutilReadableSerializer extends Phobject {
   /**
    * Print a concise, human readable representation of a value.
    *
-   * @param wild Any value.
+   * @param wild $value Any value.
    * @return string Human-readable short representation of the value.
    * @task print
    */
@@ -86,9 +86,11 @@ final class PhutilReadableSerializer extends Phobject {
    *
    * To print any number of member variables, pass null for `$max_members`.
    *
-   * @param wild Any value.
+   * @param wild $value Any value.
-   * @param int Maximum depth to print for nested arrays and objects.
+   * @param int $max_depth (optional) Maximum depth to print for nested arrays
-   * @param int Maximum number of values to print at each level.
+   *   and objects. Defaults to 2.
+   * @param int $max_members (optional) Maximum number of values to print at
+   *   each level. Defaults to 25.
    * @return string Human-readable shallow representation of the value.
    * @task print
    */
@@ -107,11 +109,12 @@ final class PhutilReadableSerializer extends Phobject {
   /**
    * Implementation for @{method:printShallow}.
    *
-   * @param wild Any value.
+   * @param wild $value Any value.
-   * @param int Maximum depth to print for nested arrays and objects.
+   * @param int $max_depth Maximum depth to print for nested arrays and
-   * @param int Maximum number of values to print at each level.
+   *   objects.
-   * @param int Current depth.
+   * @param int $max_members Maximum number of values to print at each level.
-   * @param string Indentation string.
+   * @param int $depth Current depth.
+   * @param string $indent Indentation string.
    * @return string Human-readable shallow representation of the value.
    * @task internal
    */
@@ -170,9 +173,9 @@ final class PhutilReadableSerializer extends Phobject {
    * Adds indentation to the beginning of every line starting from
    * `$first_line`.
    *
-   * @param string Printed value.
+   * @param string $value Printed value.
-   * @param string String to indent with.
+   * @param string $indent String to indent with.
-   * @param int Index of first line to indent.
+   * @param int $first_line Index of first line to indent.
    * @return string
    * @task internal
    */

src/repository/api/ArcanistGitAPI.php

@@ -82,8 +82,8 @@ final class ArcanistGitAPI extends ArcanistRepositoryAPI {
   /**
    * Tests if a child commit is descendant of a parent commit.
    * If child and parent are the same, it returns false.
-   * @param Child commit SHA.
+   * @param $child Child commit SHA.
-   * @param Parent commit SHA.
+   * @param $parent Parent commit SHA.
    * @return bool True if the child is a descendant of the parent.
    */
   private function isDescendant($child, $parent) {
@@ -404,7 +404,7 @@ final class ArcanistGitAPI extends ArcanistRepositoryAPI {
 
   /**
    * Translates a symbolic commit (like "HEAD^") to a commit identifier.
-   * @param string_symbol commit.
+   * @param string_symbol $symbolic_commit commit.
    * @return string the commit SHA.
    */
   private function resolveCommit($symbolic_commit) {
@@ -457,9 +457,9 @@ final class ArcanistGitAPI extends ArcanistRepositoryAPI {
   }
 
   /**
-   * @param the base revision
+   * @param $base the base revision
-   * @param head revision. If this is null, the generated diff will include the
+   * @param $head (optional) head revision. If this is null, the generated diff
-   * working copy
+   * will include the working copy
    */
   public function getFullGitDiff($base, $head = null) {
     $options = $this->getDiffFullOptions();
@@ -491,10 +491,10 @@ final class ArcanistGitAPI extends ArcanistRepositoryAPI {
   }
 
   /**
-   * @param string Path to generate a diff for.
+   * @param string $path Path to generate a diff for.
-   * @param bool   If true, detect moves and renames. Otherwise, ignore
+   * @param bool   $detect_moves_and_renames (optional) If true, detect moves
-   *               moves/renames; this is useful because it prompts git to
+   *               and renames. Otherwise, ignore moves/renames; this is useful
-   *               generate real diff text.
+   *               because it prompts git to generate real diff text.
    */
   public function getRawDiffText($path, $detect_moves_and_renames = true) {
     $options = $this->getDiffFullOptions($detect_moves_and_renames);
@@ -1452,7 +1452,7 @@ final class ArcanistGitAPI extends ArcanistRepositoryAPI {
    * Follow the chain of tracking branches upstream until we reach a remote
    * or cycle locally.
    *
-   * @param string Ref to start from.
+   * @param string $start Ref to start from.
    * @return ArcanistGitUpstreamPath Path to an upstream.
    */
   public function getPathToUpstream($start) {

src/repository/api/ArcanistMercurialAPI.php

@@ -732,8 +732,9 @@ final class ArcanistMercurialAPI extends ArcanistRepositoryAPI {
    *    cause a conflict but this is something the user has to address.
    * 3. Strip the original commit.
    *
-   * @param array     The list of child changesets off the original commit.
+   * @param array $child_nodes The list of child changesets off the original
-   * @param file      The file containing the new commit message.
+   *   commit.
+   * @param file  $tmp_file The file containing the new commit message.
    */
   private function amendNonHeadCommit($child_nodes, $tmp_file) {
     list($current) = $this->execxLocal(
@@ -1053,7 +1054,7 @@ final class ArcanistMercurialAPI extends ArcanistRepositoryAPI {
    * included with Arcanist. This will not enable other extensions, e.g.
    * "evolve".
    *
-   * @param string  The name of the extension to enable.
+   * @param string  $extension The name of the extension to enable.
    * @return string  A new command pattern that includes the necessary flags to
    *                 enable the specified extension.
    */
@@ -1086,10 +1087,10 @@ final class ArcanistMercurialAPI extends ArcanistRepositoryAPI {
    * Produces the arguments that should be passed to Mercurial command
    * execution that enables a desired extension.
    *
-   * @param string  The name of the extension to enable.
+   * @param string  $extension The name of the extension to enable.
-   * @param string  The command pattern that will be run with the extension
+   * @param string  $pattern The command pattern that will be run with the
-   *                enabled.
+   *                extension enabled.
-   * @param array   Parameters for the command pattern argument.
+   * @param array   ... Parameters for the command pattern argument.
    * @return array  An array where the first item is a Mercurial command
    *                pattern that includes the necessary flag for enabling the
    *                desired extension, and all remaining items are parameters

src/repository/api/ArcanistRepositoryAPI.php

@@ -429,7 +429,7 @@ abstract class ArcanistRepositoryAPI extends Phobject {
   /**
    * Try to read a scratch file, if it exists and is readable.
    *
-   * @param string Scratch file name.
+   * @param string $path Scratch file name.
    * @return mixed String for file contents, or false for failure.
    * @task scratch
    */
@@ -457,8 +457,8 @@ abstract class ArcanistRepositoryAPI extends Phobject {
    * Try to write a scratch file, if there's somewhere to put it and we can
    * write there.
    *
-   * @param  string Scratch file name to write.
+   * @param  string $path Scratch file name to write.
-   * @param  string Data to write.
+   * @param  string $data Data to write.
    * @return bool   True on success, false on failure.
    * @task scratch
    */
@@ -489,7 +489,7 @@ abstract class ArcanistRepositoryAPI extends Phobject {
   /**
    * Try to remove a scratch file.
    *
-   * @param   string  Scratch file name to remove.
+   * @param   string  $path Scratch file name to remove.
    * @return  bool    True if the file was removed successfully.
    * @task scratch
    */
@@ -512,7 +512,7 @@ abstract class ArcanistRepositoryAPI extends Phobject {
   /**
    * Get a human-readable description of the scratch file location.
    *
-   * @param string  Scratch file name.
+   * @param string  $path Scratch file name.
    * @return mixed  String, or false on failure.
    * @task scratch
    */
@@ -531,7 +531,7 @@ abstract class ArcanistRepositoryAPI extends Phobject {
   /**
    * Get the path to a scratch file, if possible.
    *
-   * @param string  Scratch file name.
+   * @param string  $path Scratch file name.
    * @return mixed  File path, or false on failure.
    * @task scratch
    */

src/repository/api/ArcanistSubversionAPI.php

@@ -40,6 +40,12 @@ final class ArcanistSubversionAPI extends ArcanistRepositoryAPI {
     $argv[0] = 'svn '.$argv[0];
 
     $future = newv('ExecFuture', $argv);
+
+    // For historical reasons we run Subversion commands keeping env.
+    // But, let's keep English, to have a reliable parser.
+    // https://we.phorge.it/T15872
+    $future->updateEnv('LC_ALL', 'C');
+
     $future->setCWD($this->getPath());
     return $future;
   }

src/repository/parser/ArcanistMercurialParser.php

@@ -17,7 +17,7 @@ final class ArcanistMercurialParser extends Phobject {
    * can get less detailed information with @{method:parseMercurialStatus}. In
    * particular, this will parse copy sources as per "hg status -C".
    *
-   * @param string The stdout from running an "hg status" command.
+   * @param string $stdout The stdout from running an "hg status" command.
    * @return dict Map of paths to status dictionaries.
    * @task parse
    */
@@ -96,7 +96,7 @@ final class ArcanistMercurialParser extends Phobject {
    * can get more detailed information by invoking
    * @{method:parseMercurialStatusDetails}.
    *
-   * @param string The stdout from running an "hg status" command.
+   * @param string $stdout The stdout from running an "hg status" command.
    * @return dict Map of paths to ArcanistRepositoryAPI status flags.
    * @task parse
    */
@@ -110,7 +110,7 @@ final class ArcanistMercurialParser extends Phobject {
    * Parse the output of "hg log". This also parses "hg outgoing", "hg parents",
    * and other similar commands. This assumes "--style default".
    *
-   * @param string The stdout from running an "hg log" command.
+   * @param string $stdout The stdout from running an "hg log" command.
    * @return list List of dictionaries with commit information.
    * @task parse
    */
@@ -194,7 +194,7 @@ final class ArcanistMercurialParser extends Phobject {
   /**
    * Parse the output of "hg branches".
    *
-   * @param string The stdout from running an "hg branches" command.
+   * @param string $stdout The stdout from running an "hg branches" command.
    * @return list A list of dictionaries with branch information.
    * @task parse
    */

src/repository/state/ArcanistRepositoryLocalState.php

@@ -211,7 +211,7 @@ abstract class ArcanistRepositoryLocalState
   /**
    * Restores changes that were previously stashed by {@method:saveStash()}.
    *
-   * @param wild  A reference object referring to which previously stashed
+   * @param wild  $ref A reference object referring to which previously stashed
    *              changes to restore, from invoking {@method:saveStash()}.
    */
   protected function restoreStash($ref) {

src/symbols/PhutilClassMapQuery.php

@@ -60,7 +60,7 @@ final class PhutilClassMapQuery extends Phobject {
    * Set the ancestor class or interface name to load the concrete descendants
    * of.
    *
-   * @param string Ancestor class or interface name.
+   * @param string $class Ancestor class or interface name.
    * @return this
    * @task config
    */
@@ -79,9 +79,9 @@ final class PhutilClassMapQuery extends Phobject {
    *
    * You must provide a method here to use @{method:setExpandMethod}.
    *
-   * @param string  Name of the unique key method.
+   * @param string  $unique_method Name of the unique key method.
-   * @param bool    If true, then classes which return `null` will be filtered
+   * @param bool    $filter_null (optional) If true, then classes which return
-   *                from the results.
+   *                `null` will be filtered from the results.
    * @return this
    * @task config
    */
@@ -125,7 +125,7 @@ final class PhutilClassMapQuery extends Phobject {
    * If a class map uses this pattern, it must also provide a unique key for
    * each instance with @{method:setUniqueMethod}.
    *
-   * @param string Name of the expansion method.
+   * @param string $expand_method Name of the expansion method.
    * @return this
    * @task config
    */
@@ -141,7 +141,7 @@ final class PhutilClassMapQuery extends Phobject {
    * The map will be sorted using @{function:msort} and passing this method
    * name.
    *
-   * @param string Name of the sorting method.
+   * @param string $sort_method Name of the sorting method.
    * @return this
    * @task config
    */
@@ -154,7 +154,7 @@ final class PhutilClassMapQuery extends Phobject {
   /**
    * Provide a method to filter the map.
    *
-   * @param string Name of the filtering method.
+   * @param string $filter_method Name of the filtering method.
    * @return this
    * @task config
    */

src/symbols/PhutilSymbolLoader.php

@@ -56,7 +56,7 @@ final class PhutilSymbolLoader {
    * Select the type of symbol to load, either `class`, `function` or
    * `interface`.
    *
-   * @param string  Type of symbol to load.
+   * @param string $type Type of symbol to load.
    * @return this
    *
    * @task config
@@ -71,7 +71,7 @@ final class PhutilSymbolLoader {
    * Restrict the symbol query to a specific library; only symbols from this
    * library will be loaded.
    *
-   * @param string Library name.
+   * @param string $library Library name.
    * @return this
    *
    * @task config
@@ -90,7 +90,7 @@ final class PhutilSymbolLoader {
    * Restrict the symbol query to a specific path prefix; only symbols defined
    * in files below that path will be selected.
    *
-   * @param string Path relative to library root, like "apps/cheese/".
+   * @param string $path Path relative to library root, like "apps/cheese/".
    * @return this
    *
    * @task config
@@ -105,7 +105,7 @@ final class PhutilSymbolLoader {
    * Restrict the symbol query to a single symbol name, e.g. a specific class
    * or function name.
    *
-   * @param string Symbol name.
+   * @param string $name Symbol name.
    * @return this
    *
    * @task config
@@ -121,7 +121,7 @@ final class PhutilSymbolLoader {
    * strictly select descendants, the base class will not be selected. This
    * implies loading only classes.
    *
-   * @param string Base class name.
+   * @param string $base Base class name.
    * @return this
    *
    * @task config
@@ -139,7 +139,7 @@ final class PhutilSymbolLoader {
    * NOTE: This currently causes class symbols to load, even if you run
    * @{method:selectSymbolsWithoutLoading}.
    *
-   * @param bool True if the query should load only concrete symbols.
+   * @param bool $concrete True if the query should load only concrete symbols.
    * @return this
    *
    * @task config
@@ -356,7 +356,7 @@ final class PhutilSymbolLoader {
    * This method implicitly restricts the query to match only concrete
    * classes.
    *
-   * @param  list<wild>           List of constructor arguments.
+   * @param  list<wild>           $argv List of constructor arguments.
    * @return map<string, object>  Map of class names to constructed objects.
    */
   public function loadObjects(array $argv = array()) {

src/toolset/ArcanistAliasEngine.php

@@ -67,7 +67,8 @@ final class ArcanistAliasEngine
       // This alias is not defined properly, so we're going to ignore it.
       unset($aliases[$key]);
 
-      $results[] = $this->newEffect(ArcanistAliasEffect::EFFECT_CONFIGURATION)
+      $results[] =
+        $this->newEffect(ArcanistAliasEffect::EFFECT_MISCONFIGURATION)
         ->setMessage(
           pht(
             'Configuration source ("%s") defines an invalid alias, which '.

src/unit/ArcanistUnitTestResult.php

@@ -80,7 +80,7 @@ final class ArcanistUnitTestResult extends Phobject {
    * Callers should pass an integer or a float. For example, pass `3` for
    * 3 seconds, or `0.125` for 125 milliseconds.
    *
-   * @param int|float Duration, in seconds.
+   * @param int|float $duration Duration, in seconds.
    * @return this
    */
   public function setDuration($duration) {
@@ -132,7 +132,7 @@ final class ArcanistUnitTestResult extends Phobject {
   /**
    * Merge several coverage reports into a comprehensive coverage report.
    *
-   * @param list List of coverage report strings.
+   * @param list $coverage List of coverage report strings.
    * @return string Cumulative coverage report.
    */
   public static function mergeCoverage(array $coverage) {

src/unit/engine/CSharpToolsTestEngine.php

@@ -81,7 +81,7 @@ final class CSharpToolsTestEngine extends XUnitTestEngine {
    * Overridden version of `buildTestFuture` so that the unit test can be run
    * via `cscover`, which instruments assemblies and reports on code coverage.
    *
-   * @param  string  Name of the test assembly.
+   * @param  string  $test_assembly Name of the test assembly.
    * @return array   The future, output filename and coverage filename
    *                 stored in an array.
    */
@@ -145,8 +145,8 @@ final class CSharpToolsTestEngine extends XUnitTestEngine {
   /**
    * Returns coverage results for the unit tests.
    *
-   * @param  string  The name of the coverage file if one was provided by
+   * @param  string  $cover_file The name of the coverage file if one was
-   *                 `buildTestFuture`.
+   *                 provided by `buildTestFuture`.
    * @return array   Code coverage results, or null.
    */
   protected function parseCoverageResult($cover_file) {
@@ -161,7 +161,7 @@ final class CSharpToolsTestEngine extends XUnitTestEngine {
    * result file is XML and can be large depending on what has been instrumented
    * so we cache it in case it's requested again.
    *
-   * @param  string  The name of the coverage file.
+   * @param  string  $cover_file The name of the coverage file.
    * @return array   Code coverage results, or null if not cached.
    */
   private function getCachedResultsIfPossible($cover_file) {
@@ -177,8 +177,8 @@ final class CSharpToolsTestEngine extends XUnitTestEngine {
   /**
    * Stores the code coverage results in the cache.
    *
-   * @param  string  The name of the coverage file.
+   * @param  string  $cover_file The name of the coverage file.
-   * @param  array   The results to cache.
+   * @param  array   $results The results to cache.
    */
   private function addCachedResults($cover_file, array $results) {
     if ($this->cachedResults == null) {
@@ -192,7 +192,7 @@ final class CSharpToolsTestEngine extends XUnitTestEngine {
    * the `instrumented` and `executed` tags with this method so that
    * we can access the data multiple times without a performance hit.
    *
-   * @param  array  The array of XML tags to parse.
+   * @param  array  $tags The array of XML tags to parse.
    * @return array  A PHP array containing the data.
    */
   private function processTags($tags) {
@@ -210,7 +210,7 @@ final class CSharpToolsTestEngine extends XUnitTestEngine {
   /**
    * Reads the code coverage results from the cscover results file.
    *
-   * @param  string  The path to the code coverage file.
+   * @param  string  $cover_file The path to the code coverage file.
    * @return array   The code coverage results.
    */
   public function readCoverage($cover_file) {

src/unit/engine/PhpunitTestEngine.php

@@ -118,7 +118,7 @@ final class PhpunitTestEngine extends ArcanistUnitTestEngine {
    * TODO: Add support for finding tests in testsuite folders from
    * phpunit.xml configuration.
    *
-   * @param   string      PHP file to locate test cases for.
+   * @param   string      $path PHP file to locate test cases for.
    * @return  string|null Path to test cases, or null.
    */
   private function findTestFile($path) {
@@ -192,7 +192,7 @@ final class PhpunitTestEngine extends ArcanistUnitTestEngine {
    * ...or similar. This list will be further pruned by the caller; it is
    * intentionally filesystem-agnostic to be unit testable.
    *
-   * @param   string        PHP file to locate test cases for.
+   * @param   string        $path PHP file to locate test cases for.
    * @return  list<string>  List of directories to search for tests in.
    */
   public static function getSearchLocationsForTests($path) {

src/unit/engine/XUnitTestEngine.php

@@ -115,7 +115,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine {
   /**
    * Applies the discovery rules to the set of paths specified.
    *
-   * @param  array   Array of paths.
+   * @param  array   $paths Array of paths.
    * @return array   Array of paths to test projects and assemblies.
    */
   public function mapPathsToResults(array $paths) {
@@ -161,7 +161,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine {
   /**
    * Builds and runs the specified test assemblies.
    *
-   * @param  array   Array of paths to test project files.
+   * @param  array   $test_projects Array of paths to test project files.
    * @return array   Array of test results.
    */
   public function runAllTests(array $test_projects) {
@@ -188,7 +188,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine {
    * This is needed since we build the assemblies as part of the unit tests, but
    * we can't run any of the unit tests if the build fails.
    *
-   * @param  array   Array of results to check.
+   * @param  array   $results Array of results to check.
    * @return bool    If there are any failures in the results.
    */
   private function resultsContainFailures(array $results) {
@@ -271,7 +271,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine {
    * build itself (since the unit tester is about to run each of the tests
    * individually).
    *
-   * @param  array   Array of test assemblies.
+   * @param  array   $test_assemblies Array of test assemblies.
    * @return array   Array of test results.
    */
   private function buildProjects(array $test_assemblies) {
@@ -315,7 +315,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine {
    * Build the future for running a unit test. This can be overridden to enable
    * support for code coverage via another tool.
    *
-   * @param  string  Name of the test assembly.
+   * @param  string  $test_assembly Name of the test assembly.
    * @return array   The future, output filename and coverage filename
    *                 stored in an array.
    */
@@ -345,7 +345,7 @@ class XUnitTestEngine extends ArcanistUnitTestEngine {
    * Run the xUnit test runner on each of the assemblies and parse the
    * resulting XML.
    *
-   * @param  array   Array of test assemblies.
+   * @param  array   $test_assemblies Array of test assemblies.
    * @return array   Array of test results.
    */
   private function testAssemblies(array $test_assemblies) {
@@ -395,8 +395,8 @@ class XUnitTestEngine extends ArcanistUnitTestEngine {
    * coverage directly. Override this method in another class to provide code
    * coverage information (also see @{class:CSharpToolsUnitEngine}).
    *
-   * @param  string  The name of the coverage file if one was provided by
+   * @param  string  $coverage The name of the coverage file if one was
-   *                 `buildTestFuture`.
+   *                 provided by `buildTestFuture`.
    * @return array   Code coverage results, or null.
    */
   protected function parseCoverageResult($coverage) {
@@ -406,9 +406,9 @@ class XUnitTestEngine extends ArcanistUnitTestEngine {
   /**
    * Parses the test results from xUnit.
    *
-   * @param  string  The name of the xUnit results file.
+   * @param  string  $xunit_tmp The name of the xUnit results file.
-   * @param  string  The name of the coverage file if one was provided by
+   * @param  string  $coverage The name of the coverage file if one was
-   *                 `buildTestFuture`. This is passed through to
+   *                 provided by `buildTestFuture`. This is passed through to
    *                 `parseCoverageResult`.
    * @return array   Test results.
    */

src/unit/engine/phutil/PhutilTestCase.php

@@ -28,10 +28,11 @@ abstract class PhutilTestCase extends Phobject {
   /**
    * Assert that a value is `false`, strictly. The test fails if it is not.
    *
-   * @param wild    The empirically derived value, generated by executing the
+   * @param wild    $result The empirically derived value, generated by
-   *                test.
+   *                executing the test.
-   * @param string  A human-readable description of what these values represent,
+   * @param string  $message (optional) A human-readable description of what
-   *                and particularly of what a discrepancy means.
+   *                these values represent, and particularly of what a
+   *                discrepancy means.
    *
    * @return void
    * @task assert
@@ -49,10 +50,11 @@ abstract class PhutilTestCase extends Phobject {
   /**
    * Assert that a value is `true`, strictly. The test fails if it is not.
    *
-   * @param wild    The empirically derived value, generated by executing the
+   * @param wild    $result The empirically derived value, generated by
-   *                test.
+   *                executing the test.
-   * @param string  A human-readable description of what these values represent,
+   * @param string  $message (optional) A human-readable description of what
-   *                and particularly of what a discrepancy means.
+   *                these values represent, and particularly of what a
+   *                discrepancy means.
    *
    * @return void
    * @task assert
@@ -74,12 +76,13 @@ abstract class PhutilTestCase extends Phobject {
    * compare values. This means values and types must be equal, key order must
    * be identical in arrays, and objects must be referentially identical.
    *
-   * @param wild    The theoretically expected value, generated by careful
+   * @param wild    $expect The theoretically expected value, generated by
-   *                reasoning about the properties of the system.
+   *                careful reasoning about the properties of the system.
-   * @param wild    The empirically derived value, generated by executing the
+   * @param wild    $result The empirically derived value, generated by
-   *                test.
+   *                executing the test.
-   * @param string  A human-readable description of what these values represent,
+   * @param string  $message (optional) A human-readable description of what
-   *                and particularly of what a discrepancy means.
+   *                these values represent, and particularly of what a
+   *                discrepancy means.
    *
    * @return void
    * @task assert
@@ -132,7 +135,8 @@ abstract class PhutilTestCase extends Phobject {
    * better indicates intent than using dummy values with assertEqual(). This
    * causes test failure.
    *
-   * @param   string  Human-readable description of the reason for test failure.
+   * @param   string  $message Human-readable description of the reason for
+   *   test failure.
    * @return  void
    * @task    assert
    */
@@ -145,7 +149,7 @@ abstract class PhutilTestCase extends Phobject {
    * End this test by asserting that the test should be skipped for some
    * reason.
    *
-   * @param   string  Reason for skipping this test.
+   * @param   string  $message Reason for skipping this test.
    * @return  void
    * @task    assert
    */
@@ -302,8 +306,8 @@ abstract class PhutilTestCase extends Phobject {
   /**
    * This simplest way to assert exceptions are thrown.
    *
-   * @param exception   The expected exception.
+   * @param exception   $expected_exception_class The expected exception.
-   * @param callable    The thing which throws the exception.
+   * @param callable    $callable The thing which throws the exception.
    *
    * @return void
    * @task exceptions
@@ -342,13 +346,13 @@ abstract class PhutilTestCase extends Phobject {
    *      is_a_fruit($input);
    *    }
    *
-   * @param map       Map of test case labels to test case inputs.
+   * @param map       $inputs Map of test case labels to test case inputs.
-   * @param list      List of expected results, true to indicate that the case
+   * @param list      $expect List of expected results, true to indicate that
-   *                  is expected to succeed and false to indicate that the case
+   *                  the case is expected to succeed and false to indicate
-   *                  is expected to throw.
+   *                  that the case is expected to throw.
-   * @param callable  Callback to invoke for each test case.
+   * @param callable  $callable Callback to invoke for each test case.
-   * @param string    Optional exception class to catch, defaults to
+   * @param string    $exception_class (optional) Exception class to catch,
-   *                  'Exception'.
+   *                  defaults to 'Exception'.
    * @return void
    * @task exceptions
    */
@@ -432,11 +436,11 @@ abstract class PhutilTestCase extends Phobject {
    *
    * For cases where your inputs are not scalar, use @{method:tryTestCases}.
    *
-   * @param map       Map of scalar test inputs to expected success (true
+   * @param map       $map Map of scalar test inputs to expected success (true
    *                  expects success, false expects an exception).
-   * @param callable  Callback to invoke for each test case.
+   * @param callable  $callable Callback to invoke for each test case.
-   * @param string    Optional exception class to catch, defaults to
+   * @param string    $exception_class (optional) Exception class to catch,
-   *                  'Exception'.
+   *                  defaults to 'Exception'.
    * @return void
    * @task exceptions
    */
@@ -445,7 +449,7 @@ abstract class PhutilTestCase extends Phobject {
     $callable,
     $exception_class = 'Exception') {
 
-    return $this->tryTestCases(
+    $this->tryTestCases(
       array_fuse(array_keys($map)),
       array_values($map),
       $callable,
@@ -483,7 +487,8 @@ abstract class PhutilTestCase extends Phobject {
   /**
    * This hook is invoked once per test, before the test method is invoked.
    *
-   * @param string Method name of the test which will be invoked.
+   * @param string $test_method_name Method name of the test which will be
+   *   invoked.
    * @return void
    * @task hook
    */
@@ -495,7 +500,7 @@ abstract class PhutilTestCase extends Phobject {
   /**
    * This hook is invoked once per test, after the test method is invoked.
    *
-   * @param string Method name of the test which was invoked.
+   * @param string $test_method_name Method name of the test which was invoked.
    * @return void
    * @task hook
    */
@@ -508,7 +513,7 @@ abstract class PhutilTestCase extends Phobject {
    * This hook is invoked once, before any test cases execute. It gives you
    * an opportunity to perform setup steps for the entire suite of test cases.
    *
-   * @param list<PhutilTestCase> List of test cases to be run.
+   * @param list<PhutilTestCase> $test_cases List of test cases to be run.
    * @return void
    * @task hook
    */
@@ -520,7 +525,7 @@ abstract class PhutilTestCase extends Phobject {
   /**
    * This hook is invoked once, after all test cases execute.
    *
-   * @param list<PhutilTestCase> List of test cases that ran.
+   * @param list<PhutilTestCase> $test_cases List of test cases that ran.
    * @return void
    * @task hook
    */
@@ -544,7 +549,7 @@ abstract class PhutilTestCase extends Phobject {
   /**
    * Mark the currently-running test as a failure.
    *
-   * @param string  Human-readable description of problems.
+   * @param string  $reason Human-readable description of problems.
    * @return void
    *
    * @task internal
@@ -557,7 +562,7 @@ abstract class PhutilTestCase extends Phobject {
   /**
    * This was a triumph. I'm making a note here: HUGE SUCCESS.
    *
-   * @param string  Human-readable overstatement of satisfaction.
+   * @param string  $reason Human-readable overstatement of satisfaction.
    * @return void
    *
    * @task internal
@@ -570,7 +575,7 @@ abstract class PhutilTestCase extends Phobject {
   /**
    * Mark the current running test as skipped.
    *
-   * @param string  Description for why this test was skipped.
+   * @param string  $reason Description for why this test was skipped.
    * @return void
    * @task internal
    */
@@ -852,9 +857,10 @@ abstract class PhutilTestCase extends Phobject {
    *
    * This method throws and does not return.
    *
-   * @param   string      Human readable description of the expected value.
+   * @param   string      $expect_description Human readable description of the
-   * @param   string      The actual value.
+   *                      expected value.
-   * @param   string|null Optional assertion message.
+   * @param   string      $actual_result The actual value.
+   * @param   string|null $message Optional assertion message.
    * @return  void
    * @task    internal
    */

src/unit/parser/ArcanistTestResultParser.php

@@ -40,8 +40,8 @@ abstract class ArcanistTestResultParser extends Phobject {
    * Parse test results from provided input and return an array of
    * @{class:ArcanistUnitTestResult}.
    *
-   * @param string Path to test.
+   * @param string $path Path to test.
-   * @param string String containing test results.
+   * @param string $test_results String containing test results.
    * @return array
    */
   abstract public function parseTestResults($path, $test_results);

src/upload/ArcanistFileDataRef.php

@@ -40,7 +40,7 @@ final class ArcanistFileDataRef extends Phobject {
    * This name does not correspond to a path on disk, and is purely for
    * human consumption.
    *
-   * @param string Filename.
+   * @param string $name Filename.
    * @return this
    * @task config
    */
@@ -65,7 +65,7 @@ final class ArcanistFileDataRef extends Phobject {
    * data, or by calling @{method:setPath} and providing a path to a file on
    * disk.
    *
-   * @param bytes Blob of file data.
+   * @param bytes $data Blob of file data.
    * @task config
    */
   public function setData($data) {
@@ -91,7 +91,7 @@ final class ArcanistFileDataRef extends Phobject {
    * The path itself only provides data. If you want to name the file, you
    * should also call @{method:setName}.
    *
-   * @param string Path on disk to a file containing data to upload.
+   * @param string $path Path on disk to a file containing data to upload.
    * @return this
    * @task config
    */
@@ -133,7 +133,7 @@ final class ArcanistFileDataRef extends Phobject {
    * you want to upload a temporary file instead, you can specify an epoch
    * timestamp. The file will be deleted after this time.
    *
-   * @param int Epoch timestamp to retain the file until.
+   * @param int $epoch Epoch timestamp to retain the file until.
    * @return this
    * @task config
    */

src/upload/ArcanistFileUploader.php

@@ -46,8 +46,8 @@ final class ArcanistFileUploader extends Phobject {
    * You can optionally provide an explicit key which will be used to identify
    * the file. After adding files, upload them with @{method:uploadFiles}.
    *
-   * @param ArcanistFileDataRef File data to upload.
+   * @param ArcanistFileDataRef $file File data to upload.
-   * @param null|string Optional key to use to identify this file.
+   * @param null|string $key (optional) Key to use to identify this file.
    * @return this
    * @task add
    */

src/utils/AbstractDirectedGraph.php

@@ -55,7 +55,7 @@ abstract class AbstractDirectedGraph extends Phobject {
    * acceptable for your application) or throw an exception if you can't satisfy
    * this requirement.
    *
-   * @param   list  A list of nodes.
+   * @param   list  $nodes A list of nodes.
    * @return  dict  A map of nodes to the nodes reachable along their edges.
    *                There must be an entry for each node you were provided.
    * @task build
@@ -68,7 +68,8 @@ abstract class AbstractDirectedGraph extends Phobject {
    * edges that a user is trying to create here, or the initial set of edges
    * you know about.
    *
-   * @param   dict  A map of nodes to the nodes reachable along their edges.
+   * @param   dict  $nodes A map of nodes to the nodes reachable along their
+   *   edges
    * @return  this
    * @task build
    */
@@ -282,7 +283,7 @@ abstract class AbstractDirectedGraph extends Phobject {
    * NOTE: This only detects cycles reachable from a node. It does not detect
    * cycles in the entire graph.
    *
-   * @param   scalar    The node to walk from, looking for graph cycles.
+   * @param   scalar    $node The node to walk from, looking for graph cycles.
    * @return  list|null Returns null if no cycles are reachable from the node,
    *                    or a list of nodes that form a cycle.
    * @task cycle
@@ -312,8 +313,8 @@ abstract class AbstractDirectedGraph extends Phobject {
    * Internal cycle detection implementation. Recursively walks the graph,
    * keeping track of where it's been, and returns the first cycle it finds.
    *
-   * @param   scalar      The node to walk from.
+   * @param   scalar      $node The node to walk from.
-   * @param   list        Previously visited nodes.
+   * @param   list        $visited Previously visited nodes.
    * @return  null|list   Null if no cycles are found, or a list of nodes
    *                      which cycle.
    * @task cycle

src/utils/CaseInsensitiveArray.php

@@ -50,7 +50,7 @@ final class CaseInsensitiveArray extends PhutilArray {
   /**
    * Construct a new array object.
    *
-   * @param array  The input array.
+   * @param array $data (optional) The input array.
    */
   public function __construct(array $data = array()) {
     foreach ($data as $key => $value) {
@@ -111,7 +111,7 @@ final class CaseInsensitiveArray extends PhutilArray {
    *   [[http://php.net/manual/en/book.strings.php | string transformation]]
    *   functions.
    *
-   * @param  string  The input key.
+   * @param  string  $key The input key.
    * @return string  The transformed key.
    */
   private function transformKey($key) {

src/utils/PhutilBufferedIterator.php

@@ -61,7 +61,7 @@ abstract class PhutilBufferedIterator extends Phobject implements Iterator {
   /**
    * Configure the page size. Note that implementations may ignore this.
    *
-   * @param int Page size.
+   * @param int $size Page size.
    * @return this
    * @task config
    */