diff --git a/src/channel/PhutilChannel.php b/src/channel/PhutilChannel.php index 65ea544b..2827de10 100644 --- a/src/channel/PhutilChannel.php +++ b/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 A list of channels to wait for. - * @param dict Options, see above. + * @param list $channels A list of channels to wait for. + * @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 List of channels to wait for reads on. - * @param list List of channels to wait for writes on. + * @param list $reads List of channels to wait for reads on. + * @param list $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 */ diff --git a/src/channel/PhutilChannelChannel.php b/src/channel/PhutilChannelChannel.php index 1ab99e30..3b0cb437 100644 --- a/src/channel/PhutilChannelChannel.php +++ b/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() { diff --git a/src/channel/PhutilExecChannel.php b/src/channel/PhutilExecChannel.php index 0d4e722b..0f862103 100644 --- a/src/channel/PhutilExecChannel.php +++ b/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) { diff --git a/src/channel/PhutilProtocolChannel.php b/src/channel/PhutilProtocolChannel.php index 2e018fd8..1670857e 100644 --- a/src/channel/PhutilProtocolChannel.php +++ b/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 Zero or more parsed messages. * * @task protocol diff --git a/src/channel/PhutilSocketChannel.php b/src/channel/PhutilSocketChannel.php index 4bd2a47a..41cd2ddc 100644 --- a/src/channel/PhutilSocketChannel.php +++ b/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 - * socket is provided, it is used for reading and writing. - * @param socket? Optional write socket. + * @param socket $read_socket Socket (stream socket, not plain socket). If + * only one socket is provided, it is used for reading and + * writing. + * @param socket $write_socket (optional) Write socket. * * @task construct */ diff --git a/src/conduit/ConduitClient.php b/src/conduit/ConduitClient.php index 441fe25c..21db1427 100644 --- a/src/conduit/ConduitClient.php +++ b/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) { diff --git a/src/configuration/ArcanistConfigurationManager.php b/src/configuration/ArcanistConfigurationManager.php index 68ebde4e..36c05b20 100644 --- a/src/configuration/ArcanistConfigurationManager.php +++ b/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 wild Default value if key is not found. + * @param key $key Key to read. + * @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 value The value of the key. + * @param key $key Key to set. + * @param value $value The value of the key. * * @task config */ diff --git a/src/console/PhutilConsole.php b/src/console/PhutilConsole.php index 5d646f7c..f6eabe71 100644 --- a/src/console/PhutilConsole.php +++ b/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 */ diff --git a/src/console/PhutilInteractiveEditor.php b/src/console/PhutilInteractiveEditor.php index 3e12611c..eb3c4803 100644 --- a/src/console/PhutilInteractiveEditor.php +++ b/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 diff --git a/src/console/format.php b/src/console/format.php index a4fa98d5..7e621a92 100644 --- a/src/console/format.php +++ b/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 int Optional indent level. - * @param bool True to also indent the first line. + * @param string $text Text to wrap. + * @param int $indent (optional) Indent level. Defaults to 0. + * @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) { diff --git a/src/console/view/PhutilConsoleTable.php b/src/console/view/PhutilConsoleTable.php index 392ff813..86e9f4e3 100644 --- a/src/console/view/PhutilConsoleTable.php +++ b/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 + * @param list $columns * @return string */ protected function formatRow(array $columns) { diff --git a/src/console/view/PhutilConsoleView.php b/src/console/view/PhutilConsoleView.php index 85f5b8f9..39fe58c6 100644 --- a/src/console/view/PhutilConsoleView.php +++ b/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 List of unnested drawables. * @task draw */ @@ -84,7 +84,7 @@ abstract class PhutilConsoleView extends Phobject { /** - * @param list List of views, one per line. + * @param list $parts List of views, one per line. * @return wild Each view rendered on a separate line. */ final protected function drawLines(array $parts) { diff --git a/src/differential/ArcanistDifferentialCommitMessage.php b/src/differential/ArcanistDifferentialCommitMessage.php index cada4895..27053d91 100644 --- a/src/differential/ArcanistDifferentialCommitMessage.php +++ b/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) { diff --git a/src/error/PhutilErrorHandler.php b/src/error/PhutilErrorHandler.php index 2fc8fe7d..510fe9f8 100644 --- a/src/error/PhutilErrorHandler.php +++ b/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 string Error message. - * @param string File where the error occurred. - * @param int Line on which the error occurred. - * @param wild Error context information. + * @param int $num Error code. + * @param string $str Error message. + * @param string $file File where the error occurred. + * @param int $line Line on which the error occurred. + * @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 wild Event value. - * @param dict Event metadata. + * @param const $event Event type constant. + * @param wild $value Event value. + * @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 List of stack frames. */ public static function getExceptionTrace($ex) { diff --git a/src/error/phlog.php b/src/error/phlog.php index 52dc6af9..6dff4f06 100644 --- a/src/error/phlog.php +++ b/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 - * logs/consoles. + * @param wild $value Any value you want printed to the error log or other + * 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, - * which indicates the event type (e.g. error, exception, - * user message). - * @param wild The event value, like the Exception object for an exception - * event, an error string for an error event, or some user object - * for user messages. - * @param dict A dictionary of metadata about the event. The keys 'file', - * 'line' and 'trace' are always available. Other keys may be - * present, depending on the event type. + * @param const $event A PhutilErrorHandler constant, like + * PhutilErrorHandler::ERROR, which indicates the event type + * (e.g. error, exception, user message). + * @param wild $value The event value, like the Exception object for an + * exception event, an error string for an error event, or some + * user object for user messages. + * @param dict $metadata A dictionary of metadata about the event. The keys + * 'file', 'line' and 'trace' are always available. Other keys + * may be present, depending on the event type. * @return void */ function phutil_error_listener_example($event, $value, array $metadata) { diff --git a/src/filesystem/FileFinder.php b/src/filesystem/FileFinder.php index 6b1dbbb4..4eb2c3fd 100644 --- a/src/filesystem/FileFinder.php +++ b/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; diff --git a/src/filesystem/FileList.php b/src/filesystem/FileList.php index 656c92de..89eb6f7d 100644 --- a/src/filesystem/FileList.php +++ b/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 bool If true, consider the path to be contained in the list if - * the list contains a parent directory. If false, require - * that the path be part of the list explicitly. + * @param string $path Relative or absolute system file path. + * @param bool $allow_parent_directory (optional) If true, consider the + * path to be contained in the list if the list contains a + * 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 */ diff --git a/src/filesystem/Filesystem.php b/src/filesystem/Filesystem.php index dd6e984a..ca93f4cf 100644 --- a/src/filesystem/Filesystem.php +++ b/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, - * or an exception will be thrown. + * @param string $path File path to read. This file must exist and be + * 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 - * parent directory must exist. - * @param string Data to write. + * @param string $path File path to write. This file must be writable and + * its parent directory must exist. + * @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 data to write + * @param string $path file path 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 - * be used if it does not exist, or some similar name will - * be chosen if it does. - * @param string Data to write to the file. + * @param string $base Suggested filename, like "example.bak". This name + * will be used if it does not exist, or some similar name + * will be chosen if it does. + * @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 - * parent directory must exist and be writable. - * @param string Data to write. + * @param string $path File path to write. This file must be writable or + * its parent directory must exist and be writable. + * @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 New path. + * @param string $old Old 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 int Permission umask. Note that umask is in octal, so you - * should specify it as, e.g., `0777', not `777'. + * @param string $path Path to the file or directory. + * @param int $umask Permission umask. Note that umask is in octal, so + * 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 Maximum value, inclusive. + * @param int $min Minimum 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 Optional default mime type to return if the file's mime - * type can not be identified. + * @param string $path Path to the file to examine. + * @param string $default (optional) default mime type to return if the + * 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 - * be writable. - * @param int Permission umask. Note that umask is in octal, so you - * should specify it as, e.g., `0777', not `777'. - * @param boolean Recursively create directories. Default to false. + * @param string $path Path to directory. The parent directory must exist + * and be writable. + * @param int $umask Permission umask. Note that umask is in octal, so + * you should specify it as, e.g., `0777', not `777'. + * @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 int Permissions to create the directory with. By default, - * these permissions are very restrictive (0700). - * @param string Optional root directory. If not provided, the system - * temporary directory (often "/tmp") will be used. + * @param string $prefix (optional) directory prefix. + * @param int $umask (optional) Permissions to create the directory + * with. By default, these permissions are very restrictive + * (0700). + * @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 bool If false, exclude files beginning with a ".". + * @param string $path Path, absolute or relative to PWD. + * @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 The root directory. + * @param string $path Path, absolute or relative to PWD. + * @param string $root (optional) The root directory. * @return list 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. - * @return string Canonical, absolute path. + * @param string $path Path, absolute or relative to PWD. + * @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 Root path, absolute or relative to PWD. + * @param string $path Child 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 Optionally, working directory to make files readable + * @param string $path Path, absolute or relative to PWD. + * @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 Second path to test for equivalence. + * @param string $u First 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 diff --git a/src/filesystem/FilesystemException.php b/src/filesystem/FilesystemException.php index cc464ff7..d1ba12ab 100644 --- a/src/filesystem/FilesystemException.php +++ b/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 Description of the failure. + * @param string $path Path that caused the failure. + * @param string $message Description of the failure. */ public function __construct($path, $message) { $this->path = $path; diff --git a/src/filesystem/PhutilDeferredLog.php b/src/filesystem/PhutilDeferredLog.php index 2193eb3c..e2d1ac35 100644 --- a/src/filesystem/PhutilDeferredLog.php +++ b/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 - * create a log object which does not write anywhere. - * @param string The log entry format. + * @param string|null $file The file the entry should be written to, or null + * to create a log object which does not write anywhere. + * @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 wild Default to return if data does not exist. + * @param string $key Log data key. + * @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 - * prevent writes. + * @param string|null $file File where the entry should be written to, or + * null to prevent writes. * @return this * @task log */ diff --git a/src/filesystem/PhutilFileLock.php b/src/filesystem/PhutilFileLock.php index e8dd07f4..01e3ffc5 100644 --- a/src/filesystem/PhutilFileLock.php +++ b/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 diff --git a/src/filesystem/PhutilLock.php b/src/filesystem/PhutilLock.php index f69d7544..3be495e1 100644 --- a/src/filesystem/PhutilLock.php +++ b/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 - * block. + * @param float $wait (optional) Seconds to block waiting for the lock. By + * default, do not block. * @return this * * @task lock diff --git a/src/filesystem/TempFile.php b/src/filesystem/TempFile.php index 895b7a2b..ec493a7f 100644 --- a/src/filesystem/TempFile.php +++ b/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 - * file with an interactive editor, so the user's editor shows - * "commit-message" instead of "p3810hf-1z9b89bas". - * @param string? Root directory to hold the file. If omitted, the system - * temporary directory (often "/tmp") will be used by default. + * @param string $filename (optional) Filename hint. This is useful if you + * intend to edit the file with an interactive editor, so the + * user's editor shows "commit-message" instead of + * "p3810hf-1z9b89bas". + * @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 */ diff --git a/src/filesystem/linesofalarge/LinesOfALarge.php b/src/filesystem/linesofalarge/LinesOfALarge.php index 74a33b69..4b030bd9 100644 --- a/src/filesystem/linesofalarge/LinesOfALarge.php +++ b/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 */ diff --git a/src/filesystem/linesofalarge/LinesOfALargeExecFuture.php b/src/filesystem/linesofalarge/LinesOfALargeExecFuture.php index c54151f1..484eb502 100644 --- a/src/filesystem/linesofalarge/LinesOfALargeExecFuture.php +++ b/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 */ diff --git a/src/filesystem/linesofalarge/LinesOfALargeFile.php b/src/filesystem/linesofalarge/LinesOfALargeFile.php index e04c4074..9f85d19b 100644 --- a/src/filesystem/linesofalarge/LinesOfALargeFile.php +++ b/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 */ diff --git a/src/future/FutureIterator.php b/src/future/FutureIterator.php index bb464cd4..593d4942 100644 --- a/src/future/FutureIterator.php +++ b/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 - * yielding null. + * @param float $interval Maximum number of seconds to block waiting on + * 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 List of sockets expected to become writable. - * @param float Timeout, in seconds. + * @param list $read_list List of sockets expected to become readable. + * @param list $write_list List of sockets expected to become writable. + * @param float $timeout (optional) Timeout, in seconds. * @return void */ private function waitForSockets( diff --git a/src/future/exec/ExecFuture.php b/src/future/exec/ExecFuture.php index ddf9e515..5c25fc97 100644 --- a/src/future/exec/ExecFuture.php +++ b/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 bool If true, keep the pipe open for writing. By default, the pipe - * will be closed as soon as possible so that commands which - * listen for EOF will execute. If you want to keep the pipe open - * past the start of command execution, do an empty write with - * `$keep_pipe = true` first. + * @param string $data Data to write. + * @param bool $keep_pipe (optional) If true, keep the pipe open for writing. + * By default, the pipe will be closed as soon as possible so + * that commands which listen for EOF will execute. If you want + * to keep the pipe open past the start of command execution, do + * 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 - * it is signaled. + * @param int $seconds Maximum number of seconds this command may execute for + * 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 int Maximum number of bytes to return from $stream. If + * @param resource $stream Stream to read from. + * @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 - * message. - * @param int Maximum number of bytes to read. + * @param string $description Human-readable description of stream, for + * exception message. + * @param int $length Maximum number of bytes to read. * @return string The data read from the stream. * @task internal */ diff --git a/src/future/exec/PhutilExecutableFuture.php b/src/future/exec/PhutilExecutableFuture.php index 13e6977d..b4c490b9 100644 --- a/src/future/exec/PhutilExecutableFuture.php +++ b/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 Dictionary of environmental variables. - * @param bool Optionally, pass `true` to replace the existing environment. + * @param map $env Dictionary of environmental variables. + * @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|null New value, or null to remove this variable. + * @param string $key Environmental variable name. + * @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 */ diff --git a/src/future/exec/execx.php b/src/future/exec/execx.php index ee920aff..5c10f289 100644 --- a/src/future/exec/execx.php +++ b/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) { diff --git a/src/future/http/BaseHTTPFuture.php b/src/future/http/BaseHTTPFuture.php index 1def346b..a9c6bf93 100644 --- a/src/future/http/BaseHTTPFuture.php +++ b/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 mixed String or array to include in the request. Strings will be - * transmitted raw; arrays will be encoded and sent as - * 'application/x-www-form-urlencoded'. + * @param string $uri Fully-qualified URI to send a request to. + * @param mixed $data (optional) String or array to include in the request. + * Strings will be transmitted raw; arrays will be encoded and + * 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 Header value, like "en-us". + * @param string $name Header name, like "Accept-Language". + * @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 - * name if provided. + * @param string|null $filter (optional) Filter, which selects only headers + * 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 PhutilOpaqueEnvelope Password to authenticate with. + * @param string $username Username 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 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 string Case insensitive header name. + * @param list $headers List of headers from `resolve()`. + * @param string $search Case insensitive header name. * @return string Value of the header or null if not found. * @task resolve */ diff --git a/src/future/http/HTTPSFuture.php b/src/future/http/HTTPSFuture.php index 48824fb1..22f78ea5 100644 --- a/src/future/http/HTTPSFuture.php +++ b/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, - * false to return the request directly + * @param boolean $follow true to follow any Location header present in the + * 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 float + * @param string $uri + * @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 File content. - * @param string File name. - * @param string File mime type. + * @param string $key HTTP parameter name. + * @param string $data File content. + * @param string $name File name. + * @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 bool True if this string is being used as part of a query string. + * @param string $string Possibly dangerous 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) { diff --git a/src/future/postmark/PhutilPostmarkFuture.php b/src/future/postmark/PhutilPostmarkFuture.php index 23c21f47..fcf6e9d7 100644 --- a/src/future/postmark/PhutilPostmarkFuture.php +++ b/src/future/postmark/PhutilPostmarkFuture.php @@ -3,6 +3,7 @@ final class PhutilPostmarkFuture extends FutureProxy { private $future; + private $clientID; private $accessToken; private $method; private $parameters; diff --git a/src/hgdaemon/ArcanistHgClientChannel.php b/src/hgdaemon/ArcanistHgClientChannel.php index 82ce3002..f1559e17 100644 --- a/src/hgdaemon/ArcanistHgClientChannel.php +++ b/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 The pair to encode. + * @param pair $argv The 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> Zero or more complete commands. * * @task protocol diff --git a/src/hgdaemon/ArcanistHgProxyClient.php b/src/hgdaemon/ArcanistHgProxyClient.php index 6aa00e74..af9d8db9 100644 --- a/src/hgdaemon/ArcanistHgProxyClient.php +++ b/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 A list of command arguments, like "log", "-l", "5". + * @param list $argv A list of command arguments, like "log", "-l", + * "5". * @return tuple Return code, stdout and stderr. * * @task exec diff --git a/src/hgdaemon/ArcanistHgProxyServer.php b/src/hgdaemon/ArcanistHgProxyServer.php index d0d40a9b..b39a15bc 100644 --- a/src/hgdaemon/ArcanistHgProxyServer.php +++ b/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 ArcanistHgServerChannel The Mercurial server. + * @param ArcanistHgClientChannel $client The client to update. + * @param ArcanistHgServerChannel $hg The Mercurial server. * * @task server */ diff --git a/src/hgdaemon/ArcanistHgServerChannel.php b/src/hgdaemon/ArcanistHgServerChannel.php index 22f6b4ab..ccf68834 100644 --- a/src/hgdaemon/ArcanistHgServerChannel.php +++ b/src/hgdaemon/ArcanistHgServerChannel.php @@ -80,7 +80,7 @@ final class ArcanistHgServerChannel extends PhutilProtocolChannel { * -l\0 * 5 * - * @param list List of command arguments. + * @param list $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', ''); * - * @param string Bytes from the server. + * @param string $data Bytes from the server. * @return list> Zero or more complete messages. * * @task protocol diff --git a/src/init/lib/PhutilLibraryConflictException.php b/src/init/lib/PhutilLibraryConflictException.php index 4a9440ed..f7ca4bf6 100644 --- a/src/init/lib/PhutilLibraryConflictException.php +++ b/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 - * library. - * @param string The path of the already-loaded library. - * @param string The path of the attempting-to-load library. + * @param string $library The name of the library which conflicts with an + * existing library. + * @param string $old_path The path of the already-loaded library. + * @param string $new_path The path of the attempting-to-load library. * * @task construct */ diff --git a/src/internationalization/PhutilLocale.php b/src/internationalization/PhutilLocale.php index 3ef2524e..402d0970 100644 --- a/src/internationalization/PhutilLocale.php +++ b/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 "" order. * - * @param const `PhutilPerson` gender constant. - * @param list List of variants. + * @param const $variant `PhutilPerson` gender constant. + * @param list $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 "" order. * - * @param int Plurality of the value. - * @param list List of variants. + * @param int $variant Plurality of the value. + * @param list $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 The selected translation pattern. - * @param list The raw input arguments. - * @param string The translated string. + * @param string $raw_pattern The raw input pattern. + * @param string $translated_pattern The selected translation pattern. + * @param list $args The raw input arguments. + * @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 Map of locales. - * @param PhutilLocale Current locale. - * @param map Map of visited locales. + * @param map $map Map of locales. + * @param PhutilLocale $locale Current locale. + * @param map $seen Map of visited locales. * @return void */ private static function checkLocaleFallback( diff --git a/src/internationalization/PhutilTranslation.php b/src/internationalization/PhutilTranslation.php index 7acac136..7b44b497 100644 --- a/src/internationalization/PhutilTranslation.php +++ b/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 Map of all avialable translations. */ public static function getTranslationMapForLocale($locale_code) { diff --git a/src/internationalization/PhutilTranslator.php b/src/internationalization/PhutilTranslator.php index c2b0984a..46ba0dc9 100644 --- a/src/internationalization/PhutilTranslator.php +++ b/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 DateTime + * @param string $format Format accepted by `DateTime::format()`. + * @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 int + * @param float $number + * @param int $decimals (optional) * @return string */ public function formatNumber($number, $decimals = 0) { diff --git a/src/internationalization/__tests__/PhutilPhtTestCase.php b/src/internationalization/__tests__/PhutilPhtTestCase.php index fed12b1d..e10ed35a 100644 --- a/src/internationalization/__tests__/PhutilPhtTestCase.php +++ b/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'), - ), - ); - } - } diff --git a/src/internationalization/locales/PhutilPortugueseBrazilLocale.php b/src/internationalization/locales/PhutilPortugueseBrazilLocale.php index 2c1ffbea..259ed541 100644 --- a/src/internationalization/locales/PhutilPortugueseBrazilLocale.php +++ b/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'; + } + } diff --git a/src/internationalization/locales/PhutilPortuguesePortugalLocale.php b/src/internationalization/locales/PhutilPortuguesePortugalLocale.php index f893b77f..f5a9eb71 100644 --- a/src/internationalization/locales/PhutilPortuguesePortugalLocale.php +++ b/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'; + } + } diff --git a/src/internationalization/locales/PhutilSimplifiedChineseLocale.php b/src/internationalization/locales/PhutilSimplifiedChineseLocale.php index 6b0c709b..4f763323 100644 --- a/src/internationalization/locales/PhutilSimplifiedChineseLocale.php +++ b/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'; + } + } diff --git a/src/internationalization/locales/PhutilTraditionalChineseLocale.php b/src/internationalization/locales/PhutilTraditionalChineseLocale.php index f8879506..19ca3edb 100644 --- a/src/internationalization/locales/PhutilTraditionalChineseLocale.php +++ b/src/internationalization/locales/PhutilTraditionalChineseLocale.php @@ -13,4 +13,8 @@ final class PhutilTraditionalChineseLocale extends PhutilLocale { return pht('Chinese (Traditional)'); } + public function getFallbackLocaleCode() { + return 'zh_Hans'; + } + } diff --git a/src/internationalization/locales/PhutilUSEnglishLocale.php b/src/internationalization/locales/PhutilUSEnglishLocale.php index ef1633ed..1bd7430c 100644 --- a/src/internationalization/locales/PhutilUSEnglishLocale.php +++ b/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; + } + } diff --git a/src/internationalization/pht.php b/src/internationalization/pht.php index 1d9a2f7b..5062fafc 100644 --- a/src/internationalization/pht.php +++ b/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 mixed Value to select the variant from (e.g. singular or plural). + * @param string $text Translation identifier with `sprintf()` placeholders. + * @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) { diff --git a/src/land/engine/ArcanistLandEngine.php b/src/land/engine/ArcanistLandEngine.php index 692946eb..9c2573ba 100644 --- a/src/land/engine/ArcanistLandEngine.php +++ b/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 ArcanistRepositoryLocalState The local state that was captured - * at the beginning of the land process. This may include stashed changes. + * @param string $into_commit The commit hash that was landed into. + * @param ArcanistRepositoryLocalState $state The local state that was + * 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); diff --git a/src/lexer/PhutilLexer.php b/src/lexer/PhutilLexer.php index 36cc897c..ce461255 100644 --- a/src/lexer/PhutilLexer.php +++ b/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 Initial lexer state. + * @param string $input Input string. + * @param string $initial_state (optional) Initial lexer state. * @return list List of lexer tokens. * @task tokens */ diff --git a/src/lexer/PhutilShellLexer.php b/src/lexer/PhutilShellLexer.php index d4e8c523..ac17a60a 100644 --- a/src/lexer/PhutilShellLexer.php +++ b/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) { diff --git a/src/lint/ArcanistLintMessage.php b/src/lint/ArcanistLintMessage.php index cc9e58fb..749620e5 100644 --- a/src/lint/ArcanistLintMessage.php +++ b/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) { diff --git a/src/lint/engine/ArcanistLintEngine.php b/src/lint/engine/ArcanistLintEngine.php index add11d15..1ea5b84c 100644 --- a/src/lint/engine/ArcanistLintEngine.php +++ b/src/lint/engine/ArcanistLintEngine.php @@ -291,6 +291,7 @@ abstract class ArcanistLintEngine extends Phobject { /** * @param dict>> + * $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 wild Optionally, default value to return if resource does not - * exist. + * @param string $key Resource identifier. + * @param wild $default (optional) Default value to return if resource + * 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 wild Resource. + * @param string $key Resource identifier. + * @param wild $value Resource. * @return this */ public function setLinterResource($key, $value) { diff --git a/src/lint/linter/ArcanistBaseXHPASTLinter.php b/src/lint/linter/ArcanistBaseXHPASTLinter.php index f0f44827..83a175bd 100644 --- a/src/lint/linter/ArcanistBaseXHPASTLinter.php +++ b/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 Paths to build futures for. + * @param list $paths Paths to build futures for. * @return list 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 Paths to release futures for. + * @param list $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 list Function names. + * @param XHPASTNode $root Root node. + * @param list $function_names Function names. * @return AASTNodeList */ protected function getFunctionCalls(XHPASTNode $root, array $function_names) { diff --git a/src/lint/linter/ArcanistChmodLinter.php b/src/lint/linter/ArcanistChmodLinter.php index a8825e72..ceff264b 100644 --- a/src/lint/linter/ArcanistChmodLinter.php +++ b/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) { diff --git a/src/lint/linter/ArcanistExternalLinter.php b/src/lint/linter/ArcanistExternalLinter.php index 8c35e440..24e1c09f 100644 --- a/src/lint/linter/ArcanistExternalLinter.php +++ b/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 New flags. + * @param list $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 int Exit code of the linter. - * @param string Stdout of the linter. - * @param string Stderr of the linter. + * @param string $path Path to the file being linted. + * @param int $err Exit code of the linter. + * @param string $stdout Stdout of the linter. + * @param string $stderr Stderr of the linter. * @return list|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) { diff --git a/src/lint/linter/ArcanistFutureLinter.php b/src/lint/linter/ArcanistFutureLinter.php index 7fad5a55..d5daf196 100644 --- a/src/lint/linter/ArcanistFutureLinter.php +++ b/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 Map of paths to resolved futures. + * @param map $futures Map of paths to resolved futures. * @return void */ protected function didResolveLinterFutures(array $futures) { diff --git a/src/lint/linter/ArcanistLinter.php b/src/lint/linter/ArcanistLinter.php index 85a94453..4fc50861 100644 --- a/src/lint/linter/ArcanistLinter.php +++ b/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 A list of paths to be linted + * @param list $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 A list of paths which were linted. + * @param list $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 + * @param list $paths * @return list */ 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) { diff --git a/src/lint/linter/ArcanistScriptAndRegexLinter.php b/src/lint/linter/ArcanistScriptAndRegexLinter.php index 62000c31..7071fc4a 100644 --- a/src/lint/linter/ArcanistScriptAndRegexLinter.php +++ b/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 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 diff --git a/src/lint/linter/ArcanistXHPASTLinter.php b/src/lint/linter/ArcanistXHPASTLinter.php index 636d8569..d5194319 100644 --- a/src/lint/linter/ArcanistXHPASTLinter.php +++ b/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 + * @param list $rules * @return this */ public function setRules(array $rules) { diff --git a/src/lint/linter/__tests__/ArcanistLinterTestCase.php b/src/lint/linter/__tests__/ArcanistLinterTestCase.php index 19d9ce10..75760fbb 100644 --- a/src/lint/linter/__tests__/ArcanistLinterTestCase.php +++ b/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 + * @param wild $x + * @param wild $y * @return bool */ private static function compareLintMessageProperty($x, $y) { diff --git a/src/lint/linter/standards/ArcanistLinterStandard.php b/src/lint/linter/standards/ArcanistLinterStandard.php index 77b0ec79..bed4a1ec 100644 --- a/src/lint/linter/standards/ArcanistLinterStandard.php +++ b/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 ArcanistLinter + * @param string $key + * @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 */ final public static function loadAllStandardsForLinter( diff --git a/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php b/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php index a7d9ab18..24ccb577 100644 --- a/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php +++ b/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php @@ -45,12 +45,13 @@ abstract class ArcanistXHPASTLintNamingHook extends Phobject { * } * return $default; * - * @param string The symbol type. - * @param string The symbol name. - * @param string|null The default result from the main rule engine. + * @param string $type The symbol type. + * @param string $name The symbol name. + * @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 - * want to specifically provide an override. + * with. You should return the default value if you + * 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 */ diff --git a/src/lint/linter/xhpast/ArcanistXHPASTLinterRule.php b/src/lint/linter/xhpast/ArcanistXHPASTLinterRule.php index d6828e28..014f30cd 100644 --- a/src/lint/linter/xhpast/ArcanistXHPASTLinterRule.php +++ b/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 list Function names. + * @param XHPASTNode $root Root node. + * @param list $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 Class/method modifiers. */ diff --git a/src/moduleutils/PhutilLibraryMapBuilder.php b/src/moduleutils/PhutilLibraryMapBuilder.php index 5d359bbc..e0f7afab 100644 --- a/src/moduleutils/PhutilLibraryMapBuilder.php +++ b/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 - * root path. + * @param string $path (optional) A library-relative path. If omitted, + * 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 Source map (like @{method:loadSourceFileMap}). + * @param dict $symbol_map Symbol map of relative paths to symbols. + * @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 diff --git a/src/object/Phobject.php b/src/object/Phobject.php index 4d799306..2effc9de 100644 --- a/src/object/Phobject.php +++ b/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 int|null Maximum number of bytes permitted in the value. + * @param string $key Name of the constant. + * @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) { diff --git a/src/parser/ArcanistDiffParser.php b/src/parser/ArcanistDiffParser.php index f80917ed..1536b74c 100644 --- a/src/parser/ArcanistDiffParser.php +++ b/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) { diff --git a/src/parser/PhutilEditorConfig.php b/src/parser/PhutilEditorConfig.php index d2bf93a3..05d326ef 100644 --- a/src/parser/PhutilEditorConfig.php +++ b/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 + * @param string $path + * @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 */ public function getProperties($path) { diff --git a/src/parser/PhutilJSON.php b/src/parser/PhutilJSON.php index 5f43a625..dd6c2fb6 100644 --- a/src/parser/PhutilJSON.php +++ b/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 List to encode in JSON. + * @param list $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 int Current depth, for indentation. + * @param dict $object Object to format. + * @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 int Current depth, for indentation. + * @param list $array List to format. + * @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 int Current depth, for indentation. + * @param dict $value Value to format. + * @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 */ diff --git a/src/parser/PhutilLanguageGuesser.php b/src/parser/PhutilLanguageGuesser.php index 7b0dc6fc..98f1664b 100644 --- a/src/parser/PhutilLanguageGuesser.php +++ b/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) { diff --git a/src/parser/PhutilQueryStringParser.php b/src/parser/PhutilQueryStringParser.php index 90f67f64..4e082537 100644 --- a/src/parser/PhutilQueryStringParser.php +++ b/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 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> 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)) { diff --git a/src/parser/PhutilSimpleOptions.php b/src/parser/PhutilSimpleOptions.php index bcb25a4c..c763051b 100644 --- a/src/parser/PhutilSimpleOptions.php +++ b/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 string Additional characters to escape. + * @param dict $options Input dictionary. + * @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 - * make it case-insensitive. + * @param bool $case_sensitive True to make the parser case sensitive, false + * to make it case-insensitive. * @return this * @task config */ diff --git a/src/parser/aast/api/AASTNode.php b/src/parser/aast/api/AASTNode.php index 7b20224a..db25b029 100644 --- a/src/parser/aast/api/AASTNode.php +++ b/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) { diff --git a/src/parser/argument/PhutilArgumentParser.php b/src/parser/argument/PhutilArgumentParser.php index 6391fd83..fccb8e9d 100644 --- a/src/parser/argument/PhutilArgumentParser.php +++ b/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. diff --git a/src/parser/argument/PhutilArgumentSpecification.php b/src/parser/argument/PhutilArgumentSpecification.php index 71e583b1..fca3143f 100644 --- a/src/parser/argument/PhutilArgumentSpecification.php +++ b/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) { diff --git a/src/parser/xhpast/api/XHPASTNode.php b/src/parser/xhpast/api/XHPASTNode.php index 0f685c5e..94c095dd 100644 --- a/src/parser/xhpast/api/XHPASTNode.php +++ b/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. */ diff --git a/src/parser/xhpast/api/__tests__/XHPASTNodeTestCase.php b/src/parser/xhpast/api/__tests__/XHPASTNodeTestCase.php index 8e4ecbb1..7dfdc6b3 100644 --- a/src/parser/xhpast/api/__tests__/XHPASTNodeTestCase.php +++ b/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 The first element of the pair is the * `XHPASTTree` contained within the test file. * The second element of the pair is the diff --git a/src/parser/xhpast/bin/PhutilXHPASTBinary.php b/src/parser/xhpast/bin/PhutilXHPASTBinary.php index 5a1a4a13..058ff03c 100644 --- a/src/parser/xhpast/bin/PhutilXHPASTBinary.php +++ b/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) { diff --git a/src/phage/bootloader/PhagePHPAgentBootloader.php b/src/phage/bootloader/PhagePHPAgentBootloader.php index e4d522a4..18669b0a 100644 --- a/src/phage/bootloader/PhagePHPAgentBootloader.php +++ b/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!')); } diff --git a/src/readableserializer/PhutilReadableSerializer.php b/src/readableserializer/PhutilReadableSerializer.php index 7ef9d844..d4362149 100644 --- a/src/readableserializer/PhutilReadableSerializer.php +++ b/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 int Maximum depth to print for nested arrays and objects. - * @param int Maximum number of values to print at each level. + * @param wild $value Any value. + * @param int $max_depth (optional) Maximum depth to print for nested arrays + * 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 int Maximum depth to print for nested arrays and objects. - * @param int Maximum number of values to print at each level. - * @param int Current depth. - * @param string Indentation string. + * @param wild $value Any value. + * @param int $max_depth Maximum depth to print for nested arrays and + * objects. + * @param int $max_members Maximum number of values to print at each level. + * @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 String to indent with. - * @param int Index of first line to indent. + * @param string $value Printed value. + * @param string $indent String to indent with. + * @param int $first_line Index of first line to indent. * @return string * @task internal */ diff --git a/src/repository/api/ArcanistGitAPI.php b/src/repository/api/ArcanistGitAPI.php index 1ff299ec..aa5027ce 100644 --- a/src/repository/api/ArcanistGitAPI.php +++ b/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 Parent commit SHA. + * @param $child Child 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 head revision. If this is null, the generated diff will include the - * working copy + * @param $base the base revision + * @param $head (optional) head revision. If this is null, the generated diff + * 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 bool If true, detect moves and renames. Otherwise, ignore - * moves/renames; this is useful because it prompts git to - * generate real diff text. + * @param string $path Path to generate a diff for. + * @param bool $detect_moves_and_renames (optional) If true, detect moves + * and renames. Otherwise, ignore moves/renames; this is useful + * 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) { diff --git a/src/repository/api/ArcanistMercurialAPI.php b/src/repository/api/ArcanistMercurialAPI.php index 7e35a1e3..b27e87b2 100644 --- a/src/repository/api/ArcanistMercurialAPI.php +++ b/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 file The file containing the new commit message. + * @param array $child_nodes The list of child changesets off the original + * 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 The command pattern that will be run with the extension - * enabled. - * @param array Parameters for the command pattern argument. + * @param string $extension The name of the extension to enable. + * @param string $pattern The command pattern that will be run with the + * extension enabled. + * @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 diff --git a/src/repository/api/ArcanistRepositoryAPI.php b/src/repository/api/ArcanistRepositoryAPI.php index 48b44f66..dd35db2f 100644 --- a/src/repository/api/ArcanistRepositoryAPI.php +++ b/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 Data to write. + * @param string $path Scratch file name 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 */ diff --git a/src/repository/api/ArcanistSubversionAPI.php b/src/repository/api/ArcanistSubversionAPI.php index cfd4ab30..6fc17bf5 100644 --- a/src/repository/api/ArcanistSubversionAPI.php +++ b/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; } diff --git a/src/repository/parser/ArcanistMercurialParser.php b/src/repository/parser/ArcanistMercurialParser.php index 33e59c5c..96ad15e6 100644 --- a/src/repository/parser/ArcanistMercurialParser.php +++ b/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 */ diff --git a/src/repository/state/ArcanistRepositoryLocalState.php b/src/repository/state/ArcanistRepositoryLocalState.php index e2c50283..84521fc7 100644 --- a/src/repository/state/ArcanistRepositoryLocalState.php +++ b/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) { diff --git a/src/symbols/PhutilClassMapQuery.php b/src/symbols/PhutilClassMapQuery.php index 62d567d6..702ba441 100644 --- a/src/symbols/PhutilClassMapQuery.php +++ b/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 bool If true, then classes which return `null` will be filtered - * from the results. + * @param string $unique_method Name of the unique key method. + * @param bool $filter_null (optional) If true, then classes which return + * `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 */ diff --git a/src/symbols/PhutilSymbolLoader.php b/src/symbols/PhutilSymbolLoader.php index 7f733ee7..795b0803 100644 --- a/src/symbols/PhutilSymbolLoader.php +++ b/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 List of constructor arguments. + * @param list $argv List of constructor arguments. * @return map Map of class names to constructed objects. */ public function loadObjects(array $argv = array()) { diff --git a/src/toolset/ArcanistAliasEngine.php b/src/toolset/ArcanistAliasEngine.php index baa4ab56..250842c8 100644 --- a/src/toolset/ArcanistAliasEngine.php +++ b/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 '. diff --git a/src/unit/ArcanistUnitTestResult.php b/src/unit/ArcanistUnitTestResult.php index ec25c20f..e40df693 100644 --- a/src/unit/ArcanistUnitTestResult.php +++ b/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) { diff --git a/src/unit/engine/CSharpToolsTestEngine.php b/src/unit/engine/CSharpToolsTestEngine.php index 7fd23e0d..746c3739 100644 --- a/src/unit/engine/CSharpToolsTestEngine.php +++ b/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 - * `buildTestFuture`. + * @param string $cover_file The name of the coverage file if one was + * 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 array The results to cache. + * @param string $cover_file The name of the coverage file. + * @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) { diff --git a/src/unit/engine/PhpunitTestEngine.php b/src/unit/engine/PhpunitTestEngine.php index 4cb89006..30cc84c3 100644 --- a/src/unit/engine/PhpunitTestEngine.php +++ b/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 List of directories to search for tests in. */ public static function getSearchLocationsForTests($path) { diff --git a/src/unit/engine/XUnitTestEngine.php b/src/unit/engine/XUnitTestEngine.php index d6a20464..9e4eb447 100644 --- a/src/unit/engine/XUnitTestEngine.php +++ b/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 - * `buildTestFuture`. + * @param string $coverage The name of the coverage file if one was + * 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 The name of the coverage file if one was provided by - * `buildTestFuture`. This is passed through to + * @param string $xunit_tmp The name of the xUnit results file. + * @param string $coverage The name of the coverage file if one was + * provided by `buildTestFuture`. This is passed through to * `parseCoverageResult`. * @return array Test results. */ diff --git a/src/unit/engine/phutil/PhutilTestCase.php b/src/unit/engine/phutil/PhutilTestCase.php index e5f56164..e6a06ccd 100644 --- a/src/unit/engine/phutil/PhutilTestCase.php +++ b/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 - * test. - * @param string A human-readable description of what these values represent, - * and particularly of what a discrepancy means. + * @param wild $result The empirically derived value, generated by + * executing the test. + * @param string $message (optional) A human-readable description of what + * 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 - * test. - * @param string A human-readable description of what these values represent, - * and particularly of what a discrepancy means. + * @param wild $result The empirically derived value, generated by + * executing the test. + * @param string $message (optional) A human-readable description of what + * 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 - * reasoning about the properties of the system. - * @param wild The empirically derived value, generated by executing the - * test. - * @param string A human-readable description of what these values represent, - * and particularly of what a discrepancy means. + * @param wild $expect The theoretically expected value, generated by + * careful reasoning about the properties of the system. + * @param wild $result The empirically derived value, generated by + * executing the test. + * @param string $message (optional) A human-readable description of what + * 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 callable The thing which throws the exception. + * @param exception $expected_exception_class The expected 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 list List of expected results, true to indicate that the case - * is expected to succeed and false to indicate that the case - * is expected to throw. - * @param callable Callback to invoke for each test case. - * @param string Optional exception class to catch, defaults to - * 'Exception'. + * @param map $inputs Map of test case labels to test case inputs. + * @param list $expect List of expected results, true to indicate that + * the case is expected to succeed and false to indicate + * that the case is expected to throw. + * @param callable $callable Callback to invoke for each test case. + * @param string $exception_class (optional) Exception class to catch, + * 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 string Optional exception class to catch, defaults to - * 'Exception'. + * @param callable $callable Callback to invoke for each test case. + * @param string $exception_class (optional) Exception class to catch, + * 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 List of test cases to be run. + * @param list $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 List of test cases that ran. + * @param list $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 The actual value. - * @param string|null Optional assertion message. + * @param string $expect_description Human readable description of the + * expected value. + * @param string $actual_result The actual value. + * @param string|null $message Optional assertion message. * @return void * @task internal */ diff --git a/src/unit/parser/ArcanistTestResultParser.php b/src/unit/parser/ArcanistTestResultParser.php index 9a4c41fc..2b43fc3d 100644 --- a/src/unit/parser/ArcanistTestResultParser.php +++ b/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 String containing test results. + * @param string $path Path to test. + * @param string $test_results String containing test results. * @return array */ abstract public function parseTestResults($path, $test_results); diff --git a/src/upload/ArcanistFileDataRef.php b/src/upload/ArcanistFileDataRef.php index 99ed03d9..c1aa4d56 100644 --- a/src/upload/ArcanistFileDataRef.php +++ b/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 */ diff --git a/src/upload/ArcanistFileUploader.php b/src/upload/ArcanistFileUploader.php index 2af3ae25..cc4217be 100644 --- a/src/upload/ArcanistFileUploader.php +++ b/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 null|string Optional key to use to identify this file. + * @param ArcanistFileDataRef $file File data to upload. + * @param null|string $key (optional) Key to use to identify this file. * @return this * @task add */ diff --git a/src/utils/AbstractDirectedGraph.php b/src/utils/AbstractDirectedGraph.php index 24611c14..4e7db69a 100644 --- a/src/utils/AbstractDirectedGraph.php +++ b/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 list Previously visited nodes. + * @param scalar $node The node to walk from. + * @param list $visited Previously visited nodes. * @return null|list Null if no cycles are found, or a list of nodes * which cycle. * @task cycle diff --git a/src/utils/CaseInsensitiveArray.php b/src/utils/CaseInsensitiveArray.php index 5f8cae53..66e43c5f 100644 --- a/src/utils/CaseInsensitiveArray.php +++ b/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) { diff --git a/src/utils/PhutilBufferedIterator.php b/src/utils/PhutilBufferedIterator.php index 3f40b65d..598629f7 100644 --- a/src/utils/PhutilBufferedIterator.php +++ b/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 */ diff --git a/src/utils/PhutilCallbackFilterIterator.php b/src/utils/PhutilCallbackFilterIterator.php index c1a95a4d..1eb367ea 100644 --- a/src/utils/PhutilCallbackFilterIterator.php +++ b/src/utils/PhutilCallbackFilterIterator.php @@ -7,8 +7,8 @@ final class PhutilCallbackFilterIterator extends FilterIterator { private $callback; /** - * @param Iterator - * @param callable Signature: (mixed $current): bool. + * @param Iterator $iterator + * @param callable $callback Signature: (mixed $current): bool. */ public function __construct(Iterator $iterator, $callback) { parent::__construct($iterator); diff --git a/src/utils/PhutilChunkedIterator.php b/src/utils/PhutilChunkedIterator.php index a002c5fe..d4a66894 100644 --- a/src/utils/PhutilChunkedIterator.php +++ b/src/utils/PhutilChunkedIterator.php @@ -12,8 +12,8 @@ final class PhutilChunkedIterator extends Phobject implements Iterator { private $current; /** - * @param Iterator - * @param int + * @param Iterator $iterator + * @param int $size */ public function __construct(Iterator $iterator, $size) { $this->iterator = $iterator; diff --git a/src/utils/PhutilRope.php b/src/utils/PhutilRope.php index 31d7aa27..76a26b41 100644 --- a/src/utils/PhutilRope.php +++ b/src/utils/PhutilRope.php @@ -19,7 +19,7 @@ final class PhutilRope extends Phobject { /** * Append a string to the rope. * - * @param string String to append. + * @param string $string String to append. * @return this */ public function append($string) { @@ -70,7 +70,7 @@ final class PhutilRope extends Phobject { /** * Get prefix bytes of the rope, up to some maximum size. * - * @param int Maximum number of bytes to read. + * @param int $length Maximum number of bytes to read. * @return string Bytes. */ public function getPrefixBytes($length) { @@ -108,7 +108,7 @@ final class PhutilRope extends Phobject { /** * Remove a specified number of bytes from the head of the rope. * - * @param int Bytes to remove. + * @param int $remove Bytes to remove. * @return this */ public function removeBytesFromHead($remove) { diff --git a/src/utils/PhutilSystem.php b/src/utils/PhutilSystem.php index d2c053a5..4b1a98b9 100644 --- a/src/utils/PhutilSystem.php +++ b/src/utils/PhutilSystem.php @@ -106,7 +106,7 @@ final class PhutilSystem extends Phobject { * See @{method:getSystemMemoryInformation}. This method is used to get memory * information on Linux. * - * @param string Raw `/proc/meminfo`. + * @param string $data Raw `/proc/meminfo`. * @return map Parsed memory information. * @task memory */ @@ -159,7 +159,7 @@ final class PhutilSystem extends Phobject { * See @{method:getSystemMemoryInformation}. This method is used to get memory * information on Mac OS X. * - * @param string Raw `vm_stat` output. + * @param string $data Raw `vm_stat` output. * @return map Parsed memory information. * @task memory */ diff --git a/src/utils/utf8.php b/src/utils/utf8.php index 7ba7b11e..ef1b2551 100644 --- a/src/utils/utf8.php +++ b/src/utils/utf8.php @@ -8,7 +8,7 @@ * * This function treats overlong encodings as invalid. * - * @param string String to convert to valid UTF-8. + * @param string $string String to convert to valid UTF-8. * @return string String with invalid UTF-8 byte subsequences replaced with * U+FFFD. */ @@ -78,8 +78,8 @@ function phutil_utf8ize($string) { * types silently truncate strings which contain characters outside of this * set. * - * @param string String to test for being valid UTF-8 with only characters in - * the basic multilingual plane. + * @param string $string String to test for being valid UTF-8 with only + * characters in the basic multilingual plane. * @return bool True if the string is valid UTF-8 with only BMP characters. */ function phutil_is_utf8_with_only_bmp_characters($string) { @@ -90,7 +90,7 @@ function phutil_is_utf8_with_only_bmp_characters($string) { /** * Determine if a string is valid UTF-8. * - * @param string Some string which may or may not be valid UTF-8. + * @param string $string Some string which may or may not be valid UTF-8. * @return bool True if the string is valid UTF-8. */ function phutil_is_utf8($string) { @@ -116,9 +116,9 @@ function phutil_is_utf8($string) { * that function can use more performant mechanisms if they are available on * the system. * - * @param string Some string which may or may not be valid UTF-8. - * @param bool True to require all characters be part of the basic - * multilingual plane (no more than 3-bytes long). + * @param string $string Some string which may or may not be valid UTF-8. + * @param bool $only_bmp (optional) True to require all characters be part + * of the basic multilingual plane (no more than 3-bytes long). * @return bool True if the string is valid UTF-8. */ function phutil_is_utf8_slowly($string, $only_bmp = false) { @@ -284,7 +284,7 @@ function phutil_is_utf8_slowly($string, $only_bmp = false) { /** * Find the character length of a UTF-8 string. * - * @param string A valid utf-8 string. + * @param string $string A valid utf-8 string. * @return int The character length of the string. */ function phutil_utf8_strlen($string) { @@ -314,7 +314,7 @@ function phutil_utf8_strlen($string) { * * NOTE: This function is VERY slow. * - * @param string A valid UTF-8 string. + * @param string $string A valid UTF-8 string. * @return int The console display length of the string. */ function phutil_utf8_console_strlen($string) { @@ -370,7 +370,7 @@ function phutil_utf8_console_strlen($string) { * * Most languages use spaces to separate words, but these languages do not. * - * @param string String to examine, in UTF8. + * @param string $string String to examine, in UTF8. * @return bool True if the string contains Chinese, Japanese, or Korean * characters. */ @@ -427,8 +427,9 @@ function phutil_utf8_is_cjk($string) { * Split a UTF-8 string into an array of characters. Combining characters are * also split. * - * @param string A valid utf-8 string. - * @param int|null Stop processing after examining this many bytes. + * @param string $string A valid utf-8 string. + * @param int|null $byte_limit (optional) Stop processing after examining this + * many bytes. * @return list A list of characters in the string. */ function phutil_utf8v($string, $byte_limit = null) { @@ -492,7 +493,7 @@ function phutil_utf8v($string, $byte_limit = null) { /** * Split a UTF-8 string into an array of codepoints (as integers). * - * @param string A valid UTF-8 string. + * @param string $string A valid UTF-8 string. * @return list A list of codepoints, as integers. */ function phutil_utf8v_codepoints($string) { @@ -541,7 +542,7 @@ function phutil_utf8v_codepoints($string) { /** * Convert a Unicode codepoint into a UTF8-encoded string. * - * @param int Unicode codepoint. + * @param int $codepoint Unicode codepoint. * @return string UTF8 encoding. */ function phutil_utf8_encode_codepoint($codepoint) { @@ -573,7 +574,8 @@ function phutil_utf8_encode_codepoint($codepoint) { /** * Hard-wrap a block of UTF-8 text with embedded HTML tags and entities. * - * @param string An HTML string with tags and entities. + * @param string $string An HTML string with tags and entities. + * @param int $width Width of the hard-wrapped lines * @return list List of hard-wrapped lines. */ function phutil_utf8_hard_wrap_html($string, $width) { @@ -628,8 +630,8 @@ function phutil_utf8_hard_wrap_html($string, $width) { /** * Hard-wrap a block of UTF-8 text with no embedded HTML tags and entities. * - * @param string A non HTML string - * @param int Width of the hard-wrapped lines + * @param string $string A non HTML string + * @param int $width Width of the hard-wrapped lines * @return list List of hard-wrapped lines. */ function phutil_utf8_hard_wrap($string, $width) { @@ -677,9 +679,9 @@ function phutil_utf8_hard_wrap($string, $width) { * encoding name identifies a real encoding but the string is not actually * encoded with that encoding. * - * @param string String to re-encode. - * @param string Target encoding name, like "UTF-8". - * @param string Source encoding name, like "ISO-8859-1". + * @param string $string String to re-encode. + * @param string $to_encoding Target encoding name, like "UTF-8". + * @param string $from_encoding Source encoding name, like "ISO-8859-1". * @return string Input string, with converted character encoding. * * @phutil-external-symbol function mb_convert_encoding @@ -740,7 +742,7 @@ function phutil_utf8_convert($string, $to_encoding, $from_encoding) { * completely destroy inputs, so it just has to be better than that. Similar to * @{function:ucwords}. * - * @param string UTF-8 input string. + * @param string $str UTF-8 input string. * @return string Input, in some semblance of title case. */ function phutil_utf8_ucwords($str) { @@ -780,7 +782,7 @@ function phutil_utf8_ucwords($str) { * Convert a string to lower case in a UTF8-aware way. Similar to * @{function:strtolower}. * - * @param string UTF-8 input string. + * @param string $str UTF-8 input string. * @return string Input, in some semblance of lower case. * * @phutil-external-symbol function mb_convert_case @@ -808,7 +810,7 @@ function phutil_utf8_strtolower($str) { * Convert a string to upper case in a UTF8-aware way. Similar to * @{function:strtoupper}. * - * @param string UTF-8 input string. + * @param string $str UTF-8 input string. * @return string Input, in some semblance of upper case. * * @phutil-external-symbol function mb_convert_case @@ -833,8 +835,8 @@ function phutil_utf8_strtoupper($str) { * Replace characters in a string in a UTF-aware way. Similar to * @{function:strtr}. * - * @param string UTF-8 input string. - * @param map Map of characters to replace. + * @param string $str UTF-8 input string. + * @param map $map Map of characters to replace. * @return string Input with translated characters. */ function phutil_utf8_strtr($str, array $map) { @@ -854,7 +856,7 @@ function phutil_utf8_strtr($str, array $map) { /** * Determine if a given unicode character is a combining character or not. * - * @param string A single unicode character. + * @param string $character A single unicode character. * @return boolean True or false. */ function phutil_utf8_is_combining_character($character) { @@ -882,7 +884,7 @@ function phutil_utf8_is_combining_character($character) { * Split a UTF-8 string into an array of characters. Combining characters * are not split. * - * @param string A valid utf-8 string. + * @param string $string A valid utf-8 string. * @return list A list of characters in the string. */ function phutil_utf8v_combined($string) { @@ -897,7 +899,7 @@ function phutil_utf8v_combined($string) { * This is a low-level method which can allow other operations to do less work. * If you have a string, call @{method:phutil_utf8v_combined} instead. * - * @param list List of UTF-8 characters. + * @param list $characters List of UTF-8 characters. * @return list List of UTF-8 strings with combining characters merged. */ function phutil_utf8v_combine_characters(array $characters) { @@ -961,7 +963,7 @@ function phutil_get_system_locale() { /** * Test if a system locale (LC_ALL) is available on the system. * - * @param string Locale name like "en_US.UTF-8". + * @param string $locale Locale name like "en_US.UTF-8". * @return bool True if the locale is available. */ function phutil_is_system_locale_available($locale) { @@ -976,7 +978,7 @@ function phutil_is_system_locale_available($locale) { /** * Set the system locale (LC_ALL) to a particular value. * - * @param string New locale setting. + * @param string $locale New locale setting. * @return void */ function phutil_set_system_locale($locale) { diff --git a/src/utils/utils.php b/src/utils/utils.php index 7043d9b8..58aa9c7a 100644 --- a/src/utils/utils.php +++ b/src/utils/utils.php @@ -27,10 +27,10 @@ function id($x) { * a default if it does not. This function allows you to concisely access an * index which may or may not exist without raising a warning. * - * @param array Array to access. - * @param scalar Index to access in the array. - * @param wild Default value to return if the key is not present in the - * array. + * @param array $array Array to access. + * @param scalar $key Index to access in the array. + * @param wild $default (optional) Default value to return if the key is + * not present in the array. * @return wild If `$array[$key]` exists, that value is returned. If not, * $default is returned without raising a warning. */ @@ -57,9 +57,9 @@ function idx(array $array, $key, $default = null) { * `$dict['a']['b']['c']`, if it exists. If it does not, or any intermediate * value is not itself an array, it returns the defualt value. * - * @param array Array to access. - * @param list List of keys to access, in sequence. - * @param wild Default value to return. + * @param array $map Array to access. + * @param list $path List of keys to access, in sequence. + * @param wild $default (optional) Default value to return. * @return wild Accessed value, or default if the value is not accessible. */ function idxv(array $map, array $path, $default = null) { @@ -126,13 +126,14 @@ function idxv(array $map, array $path, $default = null) { * See also @{function:ipull}, which works similarly but accesses array indexes * instead of calling methods. * - * @param list Some list of objects. - * @param string|null Determines which **values** will appear in the result - * array. Use a string like 'getName' to store the - * value of calling the named method in each value, or - * ##null## to preserve the original objects. - * @param string|null Determines how **keys** will be assigned in the result - * array. Use a string like 'getID' to use the result + * @param list $list Some list of objects. + * @param string|null $method Determines which **values** will appear in + * the result array. Use a string like 'getName' to + * store the value of calling the named method in each + * value, or ##null## to preserve the original objects. + * @param string|null $key_method (optional) Determines how **keys** will + * be assigned in the result array. + * Use a string like 'getID' to use the result * of calling the named method as each object's key, or * `null` to preserve the original keys. * @return dict A dictionary with keys and values derived according @@ -199,15 +200,16 @@ function mpull(array $list, $method, $key_method = null) { * See also @{function:mpull}, which works similarly but calls object methods * instead of accessing object properties. * - * @param list Some list of objects. - * @param string|null Determines which **values** will appear in the result - * array. Use a string like 'name' to store the value of - * accessing the named property in each value, or - * `null` to preserve the original objects. - * @param string|null Determines how **keys** will be assigned in the result - * array. Use a string like 'id' to use the result of - * accessing the named property as each object's key, or - * `null` to preserve the original keys. + * @param list $list Some list of objects. + * @param string|null $property Determines which **values** will appear in + * the result array. Use a string like 'name' to store + * the value of accessing the named property in each + * value, or `null` to preserve the original objects. + * @param string|null $key_property (optional) Determines how **keys** will + * be assigned in the result array. Use a string like + * 'id' to use the result of accessing the named property + * as each object's key, or `null` to preserve the + * original keys. * @return dict A dictionary with keys and values derived according * to whatever you passed as `$property` and * `$key_property`. @@ -249,14 +251,15 @@ function ppull(array $list, $property, $key_property = null) { * * See @{function:mpull} for more usage examples. * - * @param list Some list of arrays. - * @param scalar|null Determines which **values** will appear in the result - * array. Use a scalar to select that index from each - * array, or null to preserve the arrays unmodified as - * values. - * @param scalar|null Determines which **keys** will appear in the result - * array. Use a scalar to select that index from each - * array, or null to preserve the array keys. + * @param list $list Some list of arrays. + * @param scalar|null $index Determines which **values** will appear in the + * result array. Use a scalar to select that index from + * each array, or null to preserve the arrays unmodified + * as values. + * @param scalar|null $key_index (optional) Determines which **keys** will + * appear in the result array. Use a scalar to select + * that index from each array, or null to preserve the + * array keys. * @return dict A dictionary with keys and values derived according * to whatever you passed for `$index` and `$key_index`. */ @@ -300,11 +303,12 @@ function ipull(array $list, $index, $key_index = null) { * See also @{function:igroup}, which works the same way but operates on * array indexes. * - * @param list List of objects to group by some property. - * @param string Name of a method, like 'getType', to call on each object - * in order to determine which group it should be placed into. - * @param ... Zero or more additional method names, to subgroup the - * groups. + * @param list $list List of objects to group by some property. + * @param string $by Name of a method, like 'getType', to call on each + * object in order to determine which group it should be + * placed into. + * @param ... (optional) Zero or more additional method names, to + * subgroup the groups. * @return dict Dictionary mapping distinct method returns to lists of * all objects which returned that value. */ @@ -340,11 +344,11 @@ function mgroup(array $list, $by /* , ... */) { * as @{function:mgroup}, except it operates on the values of array indexes * rather than the return values of method calls. * - * @param list List of arrays to group by some index value. - * @param string Name of an index to select from each array in order to + * @param list $list List of arrays to group by some index value. + * @param string $by Name of an index to select from each array in order to * determine which group it should be placed into. - * @param ... Zero or more additional indexes names, to subgroup the - * groups. + * @param ... (optional) Zero or more additional indexes names, to + * subgroup the groups. * @return dict Dictionary mapping distinct index values to lists of * all objects which had that value at the index. */ @@ -387,9 +391,9 @@ function igroup(array $list, $by /* , ... */) { * * NOTE: This method does not take the list by reference; it returns a new list. * - * @param list List of objects to sort by some property. - * @param string Name of a method to call on each object; the return values - * will be used to sort the list. + * @param list $list List of objects to sort by some property. + * @param string $method Name of a method to call on each object; the return + * values will be used to sort the list. * @return list Objects ordered by the return values of the method calls. */ function msort(array $list, $method) { @@ -428,9 +432,9 @@ function msort(array $list, $method) { * * This sort is stable, well-behaved, and more efficient than `usort()`. * - * @param list List of objects to sort. - * @param string Name of a method to call on each object. The method must - * return a @{class:PhutilSortVector}. + * @param list $list List of objects to sort. + * @param string $method Name of a method to call on each object. The method + * must return a @{class:PhutilSortVector}. * @return list Objects ordered by the vectors. */ function msortv(array $list, $method) { @@ -480,8 +484,8 @@ function msortv_internal(array $list, $method, $flags) { * @{function:msort}, but operates on a list of arrays instead of a list of * objects. * - * @param list List of arrays to sort by some index value. - * @param string Index to access on each object; the return values + * @param list $list List of arrays to sort by some index value. + * @param string $index Index to access on each object; the return values * will be used to sort the list. * @return list Arrays ordered by the index values. */ @@ -515,10 +519,10 @@ function isort(array $list, $index) { * * mfilter($list, 'hasChildren', true); * - * @param array List of objects to filter. - * @param string A method name. - * @param bool Optionally, pass true to drop objects which pass the - * filter instead of keeping them. + * @param array $list List of objects to filter. + * @param string $method A method name. + * @param bool $negate (optional) Pass true to drop objects which pass + * the filter instead of keeping them. * @return array List of objects which pass the filter. */ function mfilter(array $list, $method, $negate = false) { @@ -560,10 +564,10 @@ function mfilter(array $list, $method, $negate = false) { * * ifilter($list, 'username', true); * - * @param array List of arrays to filter. - * @param scalar The index. - * @param bool Optionally, pass true to drop arrays which pass the - * filter instead of keeping them. + * @param array $list List of arrays to filter. + * @param scalar $index The index. + * @param bool $negate (optional) Pass true to drop arrays which pass + * the filter instead of keeping them. * @return array List of arrays which pass the filter. */ function ifilter(array $list, $index, $negate = false) { @@ -599,8 +603,8 @@ function ifilter(array $list, $index, $negate = false) { * uses: either reducing a large dictionary to a smaller one, or changing the * key order on an existing dictionary. * - * @param dict Dictionary of key-value pairs to select from. - * @param list List of keys to select. + * @param dict $dict Dictionary of key-value pairs to select from. + * @param list $keys List of keys to select. * @return dict Dictionary of only those key-value pairs where the key was * present in the list of keys to select. Ordering is * determined by the list order. @@ -620,8 +624,8 @@ function array_select_keys(array $dict, array $keys) { * Checks if all values of array are instances of the passed class. Throws * `InvalidArgumentException` if it isn't true for any value. * - * @param array - * @param string Name of the class or 'array' to check arrays. + * @param array $arr + * @param string $class Name of the class or 'array' to check arrays. * @return array Returns passed array. */ function assert_instances_of(array $arr, $class) { @@ -658,8 +662,8 @@ function assert_instances_of(array $arr, $class) { /** * Assert that two arrays have the exact same keys, in any order. * - * @param map Array with expected keys. - * @param map Array with actual keys. + * @param map $expect Array with expected keys. + * @param map $actual Array with actual keys. * @return void */ function assert_same_keys(array $expect, array $actual) { @@ -690,7 +694,7 @@ function assert_same_keys(array $expect, array $actual) { /** * Assert that passed data can be converted to string. * - * @param string Assert that this data is valid. + * @param string $parameter Assert that this data is valid. * @return void * * @task assert @@ -793,8 +797,8 @@ function nonempty(/* ... */) { * constructors can be invoked with `call_user_func_array()`, and may give your * class a cleaner and more descriptive API. * - * @param string The name of a class. - * @param list Array of arguments to pass to its constructor. + * @param string $class_name The name of a class. + * @param list $argv Array of arguments to pass to its constructor. * @return obj A new object of the specified class, constructed by passing * the argument vector to its constructor. */ @@ -813,7 +817,7 @@ function newv($class_name, array $argv) { * choke if you pass it some non-referenceable value like the return value of * a function. * - * @param array Array to retrieve the first element from. + * @param array $arr Array to retrieve the first element from. * @return wild The first value of the array. */ function head(array $arr) { @@ -825,7 +829,7 @@ function head(array $arr) { * that it won't warn you if you pass some non-referencable array to * it -- e.g., the result of some other array operation. * - * @param array Array to retrieve the last element from. + * @param array $arr Array to retrieve the last element from. * @return wild The last value of the array. */ function last(array $arr) { @@ -835,7 +839,7 @@ function last(array $arr) { /** * Returns the first key of an array. * - * @param array Array to retrieve the first key from. + * @param array $arr Array to retrieve the first key from. * @return int|string The first key of the array. */ function head_key(array $arr) { @@ -846,7 +850,7 @@ function head_key(array $arr) { /** * Returns the last key of an array. * - * @param array Array to retrieve the last key from. + * @param array $arr Array to retrieve the last key from. * @return int|string The last key of the array. */ function last_key(array $arr) { @@ -865,7 +869,7 @@ function last_key(array $arr) { * merge them with this function than by calling array_merge() in a loop, * because using a loop generates an intermediary array on each iteration. * - * @param list Vector of arrays to merge. + * @param list $arrayv Vector of arrays to merge. * @return list Arrays, merged with array_merge() semantics. */ function array_mergev(array $arrayv) { @@ -902,7 +906,8 @@ function array_mergev(array $arrayv) { * of SVN, Git or Mercurial do on any OS. * * @param string|PhutilSafeHTML $corpus Block of text to be split into lines. - * @param bool If true, retain line endings in result strings. + * @param bool $retain_endings (optional) If true, retain line endings in + * result strings. * @return list List of lines. * * @phutil-external-symbol class PhutilSafeHTML @@ -952,7 +957,7 @@ function phutil_split_lines($corpus, $retain_endings = true) { * * $result = array_fuse($list); * - * @param list List of scalars. + * @param list $list (optional) List of scalars. * @return dict Dictionary with inputs mapped to themselves. */ function array_fuse(array $list = null) { @@ -977,8 +982,8 @@ function array_fuse(array $list = null) { * * This function does not preserve keys. * - * @param wild Element to interleave. - * @param list List of elements to be interleaved. + * @param wild $interleave Element to interleave. + * @param list $array List of elements to be interleaved. * @return list Original list with the new element interleaved. */ function array_interleave($interleave, array $array) { @@ -1005,7 +1010,7 @@ function phutil_is_hiphop_runtime() { /** * Converts a string to a loggable one, with unprintables and newlines escaped. * - * @param string Any string. + * @param string $string Any string. * @return string String with control and newline characters escaped, suitable * for printing on a single log line. */ @@ -1056,8 +1061,8 @@ function phutil_loggable_string($string) { * when a zero-length write is caused by EAGAIN and return `0` only if the * write really should be retried. * - * @param resource Socket or pipe stream. - * @param string Bytes to write. + * @param resource $stream Socket or pipe stream. + * @param string $bytes Bytes to write. * @return bool|int Number of bytes written, or `false` on any error (including * errors which `fwrite()` can not detect, like a broken pipe). */ @@ -1136,7 +1141,7 @@ function phutil_fwrite_nonblocking_stream($stream, $bytes) { * * ...which is self-documenting and difficult to make a mistake with. * - * @param string Human readable description of a unit quantity. + * @param string $description Human readable description of a unit quantity. * @return int Quantity of specified unit. */ function phutil_units($description) { @@ -1279,7 +1284,8 @@ function phutil_units($description) { * Compute the number of microseconds that have elapsed since an earlier * timestamp (from `microtime(true)`). * - * @param double Microsecond-precision timestamp, from `microtime(true)`. + * @param double $timestamp Microsecond-precision timestamp, from + * `microtime(true)`. * @return int Elapsed microseconds. */ function phutil_microseconds_since($timestamp) { @@ -1301,8 +1307,8 @@ function phutil_microseconds_since($timestamp) { /** * Decode a JSON dictionary. * - * @param string A string which ostensibly contains a JSON-encoded list or - * dictionary. + * @param string $string A string which ostensibly contains a JSON-encoded + * list or dictionary. * @return mixed Decoded list/dictionary. */ function phutil_json_decode($string) { @@ -1322,7 +1328,7 @@ function phutil_json_decode($string) { /** * Encode a value in JSON, raising an exception if it can not be encoded. * - * @param wild A value to encode. + * @param wild $value A value to encode. * @return string JSON representation of the value. */ function phutil_json_encode($value) { @@ -1362,8 +1368,8 @@ function phutil_json_encode($value) { /** * Produce a human-readable explanation why a value can not be JSON-encoded. * - * @param wild Value to validate. - * @param string Path within the object to provide context. + * @param wild $value Value to validate. + * @param string $path (optional) Path within the object to provide context. * @return string|null Explanation of why it can't be encoded, or null. */ function phutil_validate_json($value, $path = '') { @@ -1435,7 +1441,7 @@ function phutil_validate_json($value, $path = '') { /** * Decode an INI string. * - * @param string + * @param string $string * @return mixed */ function phutil_ini_decode($string) { @@ -1508,7 +1514,7 @@ function phutil_ini_decode($string) { * output. For example, when `git fetch` fails, the output includes credentials * for authenticated HTTP remotes. * - * @param string Some block of text. + * @param string $string Some block of text. * @return string A similar block of text, but with credentials that could * be identified censored. */ @@ -1523,7 +1529,7 @@ function phutil_censor_credentials($string) { * This function is intended to behave similarly to PHP's `var_export` function, * but the output is intended to follow our style conventions. * - * @param wild The variable you want to export. + * @param wild $var The variable you want to export. * @return string */ function phutil_var_export($var) { @@ -1570,8 +1576,8 @@ function phutil_var_export($var) { /** * An improved version of `fnmatch`. * - * @param string A glob pattern. - * @param string A path. + * @param string $glob A glob pattern. + * @param string $path A path. * @return bool */ function phutil_fnmatch($glob, $path) { @@ -1655,8 +1661,8 @@ function phutil_fnmatch($glob, $path) { * It is questionable how practical these attacks are, but they are possible * in theory and defusing them is straightforward. * - * @param string First hash. - * @param string Second hash. + * @param string $u First hash. + * @param string $v Second hash. * @return bool True if hashes are identical. */ function phutil_hashes_are_identical($u, $v) { @@ -1686,7 +1692,7 @@ function phutil_hashes_are_identical($u, $v) { /** * Build a query string from a dictionary. * - * @param map Dictionary of parameters. + * @param map $parameters Dictionary of parameters. * @return string HTTP query string. */ function phutil_build_http_querystring(array $parameters) { @@ -1701,7 +1707,7 @@ function phutil_build_http_querystring(array $parameters) { /** * Build a query string from a list of parameter pairs. * - * @param list> List of pairs. + * @param list> $pairs List of pairs. * @return string HTTP query string. */ function phutil_build_http_querystring_from_pairs(array $pairs) { @@ -1733,8 +1739,8 @@ function phutil_build_http_querystring_from_pairs(array $pairs) { * * Scalar values are converted to strings. Nonscalar values raise exceptions. * - * @param scalar HTTP parameter key. - * @param scalar HTTP parameter value. + * @param scalar $key HTTP parameter key. + * @param scalar $value HTTP parameter value. * @return pair Key and value as strings. */ function phutil_http_parameter_pair($key, $value) { @@ -1800,7 +1806,7 @@ function phutil_decode_mime_header($header) { * We also reject arrays. PHP casts them to the string "Array". This behavior * is, charitably, evil. * - * @param wild Any value which aspires to be represented as a string. + * @param wild $value Any value which aspires to be represented as a string. * @return string String representation of the provided value. */ function phutil_string_cast($value) { @@ -1837,7 +1843,7 @@ function phutil_string_cast($value) { * This is similar to "get_type()", but describes objects and arrays in more * detail. * - * @param wild Anything. + * @param wild $value Anything. * @return string Human-readable description of the value's type. */ function phutil_describe_type($value) { @@ -1885,7 +1891,7 @@ function phutil_is_natural_list(array $list) { * you have more information, like you know the format of the suffix). For infix * URI components, use @{function:phutil_escape_uri_path_component} instead. * - * @param string Some string. + * @param string $string Some string. * @return string URI encoded string, except for '/'. */ function phutil_escape_uri($string) { @@ -1909,7 +1915,7 @@ function phutil_escape_uri($string) { * @{function:phutil_unescape_uri_path_component} before it can be used in the * application. * - * @param string Some string. + * @param string $string Some string. * @return string URI encoded string that is safe for infix composition. */ function phutil_escape_uri_path_component($string) { @@ -1927,7 +1933,7 @@ function phutil_escape_uri_path_component($string) { * which is added to survive the implied unescaping performed by the webserver * when interpreting the request. * - * @param string Some string emitted + * @param string $string Some string emitted * from @{function:phutil_escape_uri_path_component} and * then accessed via a web server. * @return string Original string. @@ -2109,7 +2115,7 @@ function phutil_raise_preg_exception($function, array $argv) { * This method raises an exception if passed a value which is neither null * nor a string. * - * @param Value to test. + * @param $value Value to test. * @return bool True if the parameter is a nonempty string. */ function phutil_nonempty_string($value) { @@ -2143,7 +2149,7 @@ function phutil_nonempty_string($value) { * * This method raises an exception if passed any other value. * - * @param Value to test. + * @param $value Value to test. * @return bool True if the parameter is a nonempty, stringlike value. */ function phutil_nonempty_stringlike($value) { @@ -2193,7 +2199,7 @@ function phutil_nonempty_stringlike($value) { * * This method raises an exception if passed any other value. * - * @param Value to test. + * @param $value Value to test. * @return bool True if the parameter is a nonempty, scalar value. */ function phutil_nonempty_scalar($value) { diff --git a/src/utils/viewutils.php b/src/utils/viewutils.php index b660de42..4a056757 100644 --- a/src/utils/viewutils.php +++ b/src/utils/viewutils.php @@ -24,9 +24,9 @@ function phutil_format_relative_time($duration) { * seconds, but unlike phabricator_format_relative_time, does so for more than * just the largest unit. * - * @param int Duration in seconds. - * @param int Levels to render - will render the three highest levels, ie: - * 5 h, 37 m, 1 s + * @param int $duration Duration in seconds. + * @param int $levels (optional) Levels to render. By default, renders the + * three highest levels, ie: 5 h, 37 m, 1 s * @return string Human-readable description. */ function phutil_format_relative_time_detailed($duration, $levels = 2) { @@ -73,7 +73,7 @@ function phutil_format_relative_time_detailed($duration, $levels = 2) { * Format a byte count for human consumption, e.g. "10MB" instead of * "10485760". * - * @param int Number of bytes. + * @param int $bytes Number of bytes. * @return string Human-readable description. */ function phutil_format_bytes($bytes) { @@ -88,7 +88,7 @@ function phutil_format_bytes($bytes) { /** * Parse a human-readable byte description (like "6MB") into an integer. * - * @param string Human-readable description. + * @param string $input Human-readable description. * @return int Number of represented bytes. */ function phutil_parse_bytes($input) { diff --git a/src/workflow/ArcanistDiffWorkflow.php b/src/workflow/ArcanistDiffWorkflow.php index f8a627d7..3c0afa84 100644 --- a/src/workflow/ArcanistDiffWorkflow.php +++ b/src/workflow/ArcanistDiffWorkflow.php @@ -1803,7 +1803,7 @@ EOTEXT * errors (e.g., if the user typed a reviewer name incorrectly) and a * summary of the commits themselves. * - * @param dict Local commit information. + * @param dict $local Local commit information. * @return list Complex output, see summary. * @task message */ @@ -1938,6 +1938,10 @@ EOTEXT continue; } + if ($value === null) { + continue; + } + if (is_array($value)) { // For array values, merge the arrays, appending the new values. // Examples are "Reviewers" and "Cc", where this produces a list of @@ -2394,8 +2398,8 @@ EOTEXT /** * Update an arbitrary diff property. * - * @param string Diff property name. - * @param string Diff property value. + * @param string $name Diff property name. + * @param string $data Diff property value. * @return void * * @task diffprop diff --git a/src/workflow/ArcanistDownloadWorkflow.php b/src/workflow/ArcanistDownloadWorkflow.php index 3b1264b2..acbd01de 100644 --- a/src/workflow/ArcanistDownloadWorkflow.php +++ b/src/workflow/ArcanistDownloadWorkflow.php @@ -3,6 +3,10 @@ final class ArcanistDownloadWorkflow extends ArcanistArcWorkflow { + private $id; + private $saveAs; + private $show; + public function getWorkflowName() { return 'download'; } @@ -156,7 +160,7 @@ EOTEXT try { list($data) = $future->resolvex(); } catch (Exception $ex) { - Filesystem::removePath($path); + Filesystem::remove($path); throw $ex; } diff --git a/src/workflow/ArcanistUnitWorkflow.php b/src/workflow/ArcanistUnitWorkflow.php index db01d000..d7b6b53f 100644 --- a/src/workflow/ArcanistUnitWorkflow.php +++ b/src/workflow/ArcanistUnitWorkflow.php @@ -352,8 +352,8 @@ EOTEXT * Raise a tailored error when a unit test engine returns results in an * invalid format. * - * @param ArcanistUnitTestEngine The engine. - * @param wild Results from the engine. + * @param ArcanistUnitTestEngine $engine The engine. + * @param wild $results Results from the engine. */ private function validateUnitEngineResults( ArcanistUnitTestEngine $engine, diff --git a/src/workflow/ArcanistWorkflow.php b/src/workflow/ArcanistWorkflow.php index 3b8242cb..9522812b 100644 --- a/src/workflow/ArcanistWorkflow.php +++ b/src/workflow/ArcanistWorkflow.php @@ -315,8 +315,8 @@ abstract class ArcanistWorkflow extends Phobject { * * NOTE: You can not call this after a conduit has been established. * - * @param string The URI to open a conduit to when @{method:establishConduit} - * is called. + * @param string $conduit_uri The URI to open a conduit to when + * @{method:establishConduit} is called. * @return this * @task conduit */ @@ -407,7 +407,8 @@ abstract class ArcanistWorkflow extends Phobject { * NOTE: You can not call this method after calling * @{method:authenticateConduit}. * - * @param dict A credential dictionary, see @{method:authenticateConduit}. + * @param dict $credentials A credential dictionary, see + * @{method:authenticateConduit}. * @return this * @task conduit */ @@ -1415,8 +1416,8 @@ abstract class ArcanistWorkflow extends Phobject { * change list is meaningless (for example, because the path is a directory * or binary file). * - * @param string Path within the repository. - * @param string Change selection mode (see ArcanistDiffHunk). + * @param string $path Path within the repository. + * @param string $mode Change selection mode (see ArcanistDiffHunk). * @return list|null List of changed line numbers, or null to indicate that * the path is not a line-oriented text file. */ @@ -1568,7 +1569,7 @@ abstract class ArcanistWorkflow extends Phobject { * Write a message to stderr so that '--json' flags or stdout which is meant * to be piped somewhere aren't disrupted. * - * @param string Message to write to stderr. + * @param string $msg Message to write to stderr. * @return void */ final protected function writeStatusMessage($msg) { @@ -1620,9 +1621,10 @@ abstract class ArcanistWorkflow extends Phobject { * This method takes the user's selections and returns the paths that the * workflow should act upon. * - * @param list List of explicitly provided paths. - * @param string|null Revision name, if provided. - * @param mask Mask of ArcanistRepositoryAPI flags to exclude. + * @param list $paths List of explicitly provided paths. + * @param string|null $rev Revision name, if provided. + * @param mask $omit_mask (optional) Mask of ArcanistRepositoryAPI + * flags to exclude. * Defaults to ArcanistRepositoryAPI::FLAG_UNTRACKED. * @return list List of paths the workflow should act on. */ @@ -1684,7 +1686,7 @@ abstract class ArcanistWorkflow 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 */ @@ -1699,7 +1701,7 @@ abstract class ArcanistWorkflow extends Phobject { /** * Try to read a scratch JSON file, if it exists and is readable. * - * @param string Scratch file name. + * @param string $path Scratch file name. * @return array Empty array for failure. * @task scratch */ @@ -1716,8 +1718,8 @@ abstract class ArcanistWorkflow 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 Data to write. + * @param string $path Scratch file name to write. + * @param string $data Data to write. * @return bool True on success, false on failure. * @task scratch */ @@ -1733,8 +1735,8 @@ abstract class ArcanistWorkflow extends Phobject { * Try to write a scratch JSON file, if there's somewhere to put it and we can * write there. * - * @param string Scratch file name to write. - * @param array Data to write. + * @param string $path Scratch file name to write. + * @param array $data Data to write. * @return bool True on success, false on failure. * @task scratch */ @@ -1746,7 +1748,7 @@ abstract class ArcanistWorkflow 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 */ @@ -1761,7 +1763,7 @@ abstract class ArcanistWorkflow 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 */ @@ -1776,7 +1778,7 @@ abstract class ArcanistWorkflow 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 */ @@ -2057,7 +2059,7 @@ abstract class ArcanistWorkflow extends Phobject { * of a particular class. Normally this is used to implement an `--engine` * flag from the CLI. * - * @param string Optional explicit engine class name. + * @param string $engine_class (optional) Explicit engine class name. * @return ArcanistLintEngine Constructed engine. */ protected function newLintEngine($engine_class = null) { @@ -2108,7 +2110,7 @@ abstract class ArcanistWorkflow extends Phobject { * of a particular class. Normally this is used to implement an `--engine` * flag from the CLI. * - * @param string Optional explicit engine class name. + * @param string $engine_class (optional) Explicit engine class name. * @return ArcanistUnitTestEngine Constructed engine. */ protected function newUnitTestEngine($engine_class = null) { diff --git a/src/workingcopy/ArcanistWorkingCopyPath.php b/src/workingcopy/ArcanistWorkingCopyPath.php index 5fcd1498..80b03bce 100644 --- a/src/workingcopy/ArcanistWorkingCopyPath.php +++ b/src/workingcopy/ArcanistWorkingCopyPath.php @@ -7,6 +7,7 @@ final class ArcanistWorkingCopyPath private $mode; private $data; private $binary; + private $mimeType; private $dataAsLines; private $charMap; private $lineMap; @@ -30,7 +31,7 @@ final class ArcanistWorkingCopyPath throw new Exception( pht( 'No data provided for path "%s".', - $this->getDescription())); + $this->getPath())); } return $this->data; @@ -55,7 +56,7 @@ final class ArcanistWorkingCopyPath throw new Exception( pht( 'No mode provided for path "%s".', - $this->getDescription())); + $this->getPath())); } return $this->mode; diff --git a/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php b/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php index 82a98cbb..d7858681 100644 --- a/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php +++ b/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php @@ -51,10 +51,11 @@ final class ArcanistWorkingCopyIdentity extends Phobject { * This method attempts to be robust against all sorts of possible * misconfiguration. * - * @param string Path to load information for, usually the current working - * directory (unless running unit tests). - * @param map|null Pass `null` to locate and load a `.arcconfig` file if one - * exists. Pass a map to use it to set configuration. + * @param string $path Path to load information for, usually the current + * working directory (unless running unit tests). + * @param map|null $config Pass `null` to locate and load a `.arcconfig` + * file if one exists. Pass a map to use it to set + * configuration. * @return ArcanistWorkingCopyIdentity Constructed working copy identity. */ private static function newFromPathWithConfig($path, $config) { @@ -245,8 +246,8 @@ final class ArcanistWorkingCopyIdentity extends Phobject { * configuration sources. See @{method:getConfigFromAnySource} to read from * user configuration. * - * @param key Key to read. - * @param wild Default value if key is not found. + * @param key $key Key to read. + * @param wild $default (Optional) Default value if key is not found. * @return wild Value, or default value if not found. * * @task config diff --git a/src/xsprintf/csprintf.php b/src/xsprintf/csprintf.php index ead744a8..0818d34c 100644 --- a/src/xsprintf/csprintf.php +++ b/src/xsprintf/csprintf.php @@ -27,7 +27,7 @@ * Generally, you should invoke shell commands via @{function:execx} rather * than by calling @{function:csprintf} directly. * - * @param string sprintf()-style format string. + * @param string $pattern sprintf()-style format string. * @param ... Zero or more arguments. * @return PhutilCommandString Formatted string, escaped appropriately for * shell contexts. @@ -40,8 +40,8 @@ function csprintf($pattern /* , ... */) { /** * Version of @{function:csprintf} that takes a vector of arguments. * - * @param string sprintf()-style format string. - * @param list List of zero or more arguments to csprintf(). + * @param string $pattern sprintf()-style format string. + * @param list $argv List of zero or more arguments to csprintf(). * @return PhutilCommandString Formatted string, escaped appropriately for * shell contexts. */ diff --git a/src/xsprintf/pregsprintf.php b/src/xsprintf/pregsprintf.php index 05ac86f4..f227b6e4 100644 --- a/src/xsprintf/pregsprintf.php +++ b/src/xsprintf/pregsprintf.php @@ -9,9 +9,9 @@ * %R Raw * Inserts a raw regular expression. * - * @param string sprintf()-style format string. - * @param string Flags to use with the regular expression. - * @param ... Zero or more arguments. + * @param string $pattern sprintf()-style format string. + * @param string (optional) Flags to use with the regular expression. + * @param ... (optional) Zero or more arguments. * @return string Formatted string. */ function pregsprintf($pattern /* , ... */) { diff --git a/src/xsprintf/xsprintf.php b/src/xsprintf/xsprintf.php index cdc0c9ed..ec2a6a08 100644 --- a/src/xsprintf/xsprintf.php +++ b/src/xsprintf/xsprintf.php @@ -26,10 +26,10 @@ * ...the callback will be invoked twice, at string positions 5 ("M") and 19 * ("C"), with values "moon" and "cheese" respectively. * - * @param string The name of a callback to pass conversions to. - * @param wild Optional userdata to pass to the callback. For + * @param string $callback The name of a callback to pass conversions to. + * @param wild $userdata Optional userdata to pass to the callback. For * @{function:qsprintf}, this is the database connection. - * @param list List of arguments, with the `sprintf()` pattern in + * @param list $argv List of arguments, with the `sprintf()` pattern in * position 0. * @return string Formatted string. */ @@ -118,12 +118,12 @@ function xsprintf($callback, $userdata, array $argv) { * For example implementations, see @{function:xsprintf_command}, * @{function:xsprintf_javascript} and @{function:xsprintf_query}. * - * @param wild Arbitrary, optional userdata. This is whatever userdata - * was passed to @{function:xsprintf}. - * @param string The pattern string being parsed. - * @param int The current character position in the string. - * @param wild The value to convert. - * @param int The string length. + * @param wild $userdata Arbitrary, optional userdata. This is whatever + * userdata was passed to @{function:xsprintf}. + * @param string &$pattern The pattern string being parsed. + * @param int &$pos The current character position in the string. + * @param wild &$value The value to convert. + * @param int &$length The string length. */ function xsprintf_callback_example( $userdata, diff --git a/support/unit/lock.php b/support/unit/lock.php index b4e13a60..1670cd12 100755 --- a/support/unit/lock.php +++ b/support/unit/lock.php @@ -51,7 +51,7 @@ $lock = PhutilFileLock::newForPath($file); try { $lock->lock($args->getArg('wait')); -} catch (PhutilFileLockException $ex) { +} catch (PhutilLockException $ex) { $console->writeOut( "**%s** %s\n", pht('UNABLE TO ACQUIRE LOCK:'),