Page MenuHomePhorge
Files F2680581

D25799.1734572443.diff
No OneTemporary
Actions

D25799.1734572443.diff
View Options

diff --git a/src/channel/PhutilChannel.php b/src/channel/PhutilChannel.php
--- a/src/channel/PhutilChannel.php
+++ b/src/channel/PhutilChannel.php
@@ -65,7 +65,7 @@
*
* 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 @@
* Wait for any activity on a list of channels. Convenience wrapper around
* @{method:waitForActivity}.
*
- * @param list<PhutilChannel> A list of channels to wait for.
- * @param dict Options, see above.
+ * @param list<PhutilChannel> $channels A list of channels to wait for.
+ * @param dict $options (optional) Options, see above.
* @return void
*
* @task wait
@@ -119,8 +119,9 @@
* NOTE: Extra streams must be //streams//, not //sockets//, because this
* method uses `stream_select()`, not `socket_select()`.
*
- * @param list<PhutilChannel> List of channels to wait for reads on.
- * @param list<PhutilChannel> List of channels to wait for writes on.
+ * @param list<PhutilChannel> $reads List of channels to wait for reads on.
+ * @param list<PhutilChannel> $writes List of channels to wait for writes on.
+ * @param dict $options (optional) Options, see above.
* @return void
*
* @task wait
@@ -245,7 +246,7 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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/PhutilExecChannel.php b/src/channel/PhutilExecChannel.php
--- a/src/channel/PhutilExecChannel.php
+++ b/src/channel/PhutilExecChannel.php
@@ -57,7 +57,7 @@
* 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 @@
* 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
--- a/src/channel/PhutilProtocolChannel.php
+++ b/src/channel/PhutilProtocolChannel.php
@@ -46,7 +46,7 @@
/**
* Write a message to the channel.
*
- * @param wild Some message.
+ * @param wild $message Some message.
* @return this
*
* @task io
@@ -61,7 +61,7 @@
* 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 @@
/**
* 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 @@
* a parser in this method, and store parser state on the object to be able
* to process incoming data in small chunks.
*
- * @param string One or more bytes from the underlying channel.
+ * @param string $data One or more bytes from the underlying channel.
* @return list<wild> Zero or more parsed messages.
*
* @task protocol
diff --git a/src/channel/PhutilSocketChannel.php b/src/channel/PhutilSocketChannel.php
--- a/src/channel/PhutilSocketChannel.php
+++ b/src/channel/PhutilSocketChannel.php
@@ -33,9 +33,10 @@
* `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
--- a/src/conduit/ConduitClient.php
+++ b/src/conduit/ConduitClient.php
@@ -206,7 +206,7 @@
* 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
--- a/src/configuration/ArcanistConfigurationManager.php
+++ b/src/configuration/ArcanistConfigurationManager.php
@@ -50,8 +50,8 @@
* 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 @@
* 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 @@
* 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
--- a/src/console/PhutilConsole.php
+++ b/src/console/PhutilConsole.php
@@ -56,7 +56,7 @@
/**
* 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
--- a/src/console/PhutilInteractiveEditor.php
+++ b/src/console/PhutilInteractiveEditor.php
@@ -31,7 +31,7 @@
/**
* 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 @@
* 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 @@
* 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 @@
/**
* Set the text content to be edited.
*
- * @param string New content.
+ * @param string $content New content.
* @return $this
*
* @task config
@@ -255,7 +255,7 @@
* 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 @@
* 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 @@
* 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
--- a/src/console/format.php
+++ b/src/console/format.php
@@ -94,9 +94,9 @@
* 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
--- a/src/console/view/PhutilConsoleTable.php
+++ b/src/console/view/PhutilConsoleTable.php
@@ -219,7 +219,7 @@
/**
* Get the width of a specific column, including padding.
*
- * @param string
+ * @param string $key
* @return int
*/
protected function getWidth($key) {
@@ -265,7 +265,7 @@
/**
* Format cells into an entire row.
*
- * @param list<string>
+ * @param list<string> $columns
* @return string
*/
protected function formatRow(array $columns) {
diff --git a/src/console/view/PhutilConsoleView.php b/src/console/view/PhutilConsoleView.php
--- a/src/console/view/PhutilConsoleView.php
+++ b/src/console/view/PhutilConsoleView.php
@@ -57,7 +57,7 @@
/**
* Reduce a view to a list of simple, unnested parts.
*
- * @param wild Any drawable view.
+ * @param wild $view Any drawable view.
* @return list<wild> List of unnested drawables.
* @task draw
*/
@@ -84,7 +84,7 @@
/**
- * @param list<wild> List of views, one per line.
+ * @param list<wild> $parts List of views, one per line.
* @return wild Each view rendered on a separate line.
*/
final protected function drawLines(array $parts) {
diff --git a/src/differential/ArcanistDifferentialCommitMessage.php b/src/differential/ArcanistDifferentialCommitMessage.php
--- a/src/differential/ArcanistDifferentialCommitMessage.php
+++ b/src/differential/ArcanistDifferentialCommitMessage.php
@@ -111,7 +111,7 @@
/**
* 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
--- a/src/error/PhutilErrorHandler.php
+++ b/src/error/PhutilErrorHandler.php
@@ -88,7 +88,7 @@
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* ##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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
* all of the places an exception came from, even if it came from multiple
* origins and has been aggregated or proxied.
*
- * @param Exception|Throwable Exception to retrieve a trace for.
+ * @param Exception|Throwable $ex Exception to retrieve a trace for.
* @return list<wild> List of stack frames.
*/
public static function getExceptionTrace($ex) {
diff --git a/src/error/phlog.php b/src/error/phlog.php
--- 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 @@
* 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
--- a/src/filesystem/FileFinder.php
+++ b/src/filesystem/FileFinder.php
@@ -31,7 +31,7 @@
/**
* 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 @@
/**
* @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
--- a/src/filesystem/FileList.php
+++ b/src/filesystem/FileList.php
@@ -26,7 +26,7 @@
/**
* 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 @@
* 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
--- a/src/filesystem/Filesystem.php
+++ b/src/filesystem/Filesystem.php
@@ -25,8 +25,8 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
*
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
* 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<string> List of parent paths, including the provided path.
* @task directory
*/
@@ -924,7 +928,7 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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
--- a/src/filesystem/FilesystemException.php
+++ b/src/filesystem/FilesystemException.php
@@ -11,8 +11,8 @@
/**
* 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
--- a/src/filesystem/PhutilDeferredLog.php
+++ b/src/filesystem/PhutilDeferredLog.php
@@ -55,9 +55,9 @@
*
* $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 @@
* 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 @@
/**
* 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 @@
*
* 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
--- a/src/filesystem/PhutilFileLock.php
+++ b/src/filesystem/PhutilFileLock.php
@@ -29,7 +29,7 @@
/**
* 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 @@
* 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
--- a/src/filesystem/PhutilLock.php
+++ b/src/filesystem/PhutilLock.php
@@ -41,7 +41,7 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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
--- a/src/filesystem/TempFile.php
+++ b/src/filesystem/TempFile.php
@@ -27,13 +27,13 @@
/**
* Create a new temporary file.
*
- * @param string (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
+ * @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 (optional) Root directory to hold the file. If omitted, the
- * system temporary directory (often "/tmp") will be used by
- * default.
+ * @param string $root_directory (optional) Root directory to hold the file.
+ * If omitted, the system temporary directory (often "/tmp")
+ * will be used by default.
* @task create
*/
public function __construct($filename = null, $root_directory = null) {
@@ -62,7 +62,7 @@
* 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
--- a/src/filesystem/linesofalarge/LinesOfALarge.php
+++ b/src/filesystem/linesofalarge/LinesOfALarge.php
@@ -56,7 +56,7 @@
* 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
--- a/src/filesystem/linesofalarge/LinesOfALargeExecFuture.php
+++ b/src/filesystem/linesofalarge/LinesOfALargeExecFuture.php
@@ -34,7 +34,7 @@
/**
* 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
--- a/src/filesystem/linesofalarge/LinesOfALargeFile.php
+++ b/src/filesystem/linesofalarge/LinesOfALargeFile.php
@@ -29,7 +29,7 @@
/**
* 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
--- a/src/future/FutureIterator.php
+++ b/src/future/FutureIterator.php
@@ -52,7 +52,7 @@
/**
* 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 @@
* 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 @@
* 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 @@
* // 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 @@
/**
* 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
--- a/src/future/exec/ExecFuture.php
+++ b/src/future/exec/ExecFuture.php
@@ -119,7 +119,7 @@
*
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
* 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 @@
* 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
--- a/src/future/exec/PhutilExecutableFuture.php
+++ b/src/future/exec/PhutilExecutableFuture.php
@@ -60,8 +60,9 @@
* // Env will have ONLY "X".
* $exec->setEnv(array('X' => 'y'), $wipe_process_env = true);
*
- * @param map<string, string> Dictionary of environmental variables.
- * @param bool Optionally, pass `true` to replace the existing environment.
+ * @param map<string, string> $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 @@
/**
* 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 @@
* 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
--- 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 @@
* 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 @@
/**
* 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 @@
* 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
--- a/src/future/http/BaseHTTPFuture.php
+++ b/src/future/http/BaseHTTPFuture.php
@@ -37,10 +37,10 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
*
* 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 @@
* 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 @@
/**
* 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 @@
/**
* Parse a raw HTTP response into a <status, body, headers> tuple.
*
- * @param string Raw HTTP response.
+ * @param string $raw_response Raw HTTP response.
* @return tuple Valid resolution tuple.
* @task internal
*/
@@ -393,7 +393,7 @@
/**
* 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 @@
/**
* 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
--- a/src/future/http/HTTPSFuture.php
+++ b/src/future/http/HTTPSFuture.php
@@ -39,7 +39,8 @@
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
*
* 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/hgdaemon/ArcanistHgClientChannel.php b/src/hgdaemon/ArcanistHgClientChannel.php
--- a/src/hgdaemon/ArcanistHgClientChannel.php
+++ b/src/hgdaemon/ArcanistHgClientChannel.php
@@ -50,7 +50,7 @@
* For a detailed description of the cmdserver protocol, see
* @{class:ArcanistHgServerChannel}.
*
- * @param pair<string,string> The <channel, data> pair to encode.
+ * @param pair<string,string> $argv The <channel, data> pair to encode.
* @return string Encoded string for transmission to the client.
*
* @task protocol
@@ -88,7 +88,7 @@
* '5',
* );
*
- * @param string Bytes from the server.
+ * @param string $data Bytes from the server.
* @return list<list<string>> Zero or more complete commands.
*
* @task protocol
diff --git a/src/hgdaemon/ArcanistHgProxyClient.php b/src/hgdaemon/ArcanistHgProxyClient.php
--- a/src/hgdaemon/ArcanistHgProxyClient.php
+++ b/src/hgdaemon/ArcanistHgProxyClient.php
@@ -41,7 +41,7 @@
* 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 @@
/**
* 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 @@
/**
* Execute a command (given as a list of arguments) via the command server.
*
- * @param list<string> A list of command arguments, like "log", "-l", "5".
+ * @param list<string> $argv A list of command arguments, like "log", "-l",
+ * "5".
* @return tuple<int, string, string> Return code, stdout and stderr.
*
* @task exec
diff --git a/src/hgdaemon/ArcanistHgProxyServer.php b/src/hgdaemon/ArcanistHgProxyServer.php
--- a/src/hgdaemon/ArcanistHgProxyServer.php
+++ b/src/hgdaemon/ArcanistHgProxyServer.php
@@ -52,7 +52,7 @@
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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
--- a/src/hgdaemon/ArcanistHgServerChannel.php
+++ b/src/hgdaemon/ArcanistHgServerChannel.php
@@ -80,7 +80,7 @@
* -l\0
* 5
*
- * @param list<string> List of command arguments.
+ * @param list<string> $argv List of command arguments.
* @return string Encoded string for transmission to the server.
*
* @task protocol
@@ -116,7 +116,7 @@
*
* array('o', '<data...>');
*
- * @param string Bytes from the server.
+ * @param string $data Bytes from the server.
* @return list<pair<string,string>> Zero or more complete messages.
*
* @task protocol
diff --git a/src/init/lib/PhutilLibraryConflictException.php b/src/init/lib/PhutilLibraryConflictException.php
--- a/src/init/lib/PhutilLibraryConflictException.php
+++ b/src/init/lib/PhutilLibraryConflictException.php
@@ -30,10 +30,10 @@
/**
* 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
--- a/src/internationalization/PhutilLocale.php
+++ b/src/internationalization/PhutilLocale.php
@@ -45,8 +45,8 @@
* Select a gender variant for this locale. By default, locales use a simple
* rule with two gender variants, listed in "<male, female>" order.
*
- * @param const `PhutilPerson` gender constant.
- * @param list<wild> List of variants.
+ * @param const $variant `PhutilPerson` gender constant.
+ * @param list<wild> $translations List of variants.
* @return string Variant for use.
*/
public function selectGenderVariant($variant, array $translations) {
@@ -62,8 +62,8 @@
* Select a plural variant for this locale. By default, locales use a simple
* rule with two plural variants, listed in "<singular, plural>" order.
*
- * @param int Plurality of the value.
- * @param list<wild> List of variants.
+ * @param int $variant Plurality of the value.
+ * @param list<wild> $translations List of variants.
* @return string Variant for use.
*/
public function selectPluralVariant($variant, array $translations) {
@@ -121,10 +121,10 @@
* from @{method:shouldPostProcessTranslations}. Activating this callback
* incurs a performance penalty.
*
- * @param string The raw input pattern.
- * @param string The selected translation pattern.
- * @param list<wild> 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<wild> $args The raw input arguments.
+ * @param string $result_text The translated string.
* @return string Post-processed translation string.
*/
public function didTranslateString(
@@ -195,7 +195,7 @@
/**
* 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) {
@@ -216,9 +216,9 @@
/**
* Recursively check locale fallbacks for cycles.
*
- * @param map<string, PhutilLocale> Map of locales.
- * @param PhutilLocale Current locale.
- * @param map<string, string> Map of visited locales.
+ * @param map<string, PhutilLocale> $map Map of locales.
+ * @param PhutilLocale $locale Current locale.
+ * @param map<string, string> $seen Map of visited locales.
* @return void
*/
private static function checkLocaleFallback(
diff --git a/src/internationalization/PhutilTranslation.php b/src/internationalization/PhutilTranslation.php
--- a/src/internationalization/PhutilTranslation.php
+++ b/src/internationalization/PhutilTranslation.php
@@ -59,7 +59,7 @@
* This will compile primary and fallback translations into a single
* translation map.
*
- * @param string Locale code, like "en_US".
+ * @param string $locale_code Locale code, like "en_US".
* @return map<string, wild> Map of all avialable translations.
*/
public static function getTranslationMapForLocale($locale_code) {
diff --git a/src/internationalization/PhutilTranslator.php b/src/internationalization/PhutilTranslator.php
--- a/src/internationalization/PhutilTranslator.php
+++ b/src/internationalization/PhutilTranslator.php
@@ -64,7 +64,7 @@
* '%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 @@
/**
* 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 @@
* 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/pht.php b/src/internationalization/pht.php
--- 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 @@
/**
* 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 @@
* 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
--- a/src/land/engine/ArcanistLandEngine.php
+++ b/src/land/engine/ArcanistLandEngine.php
@@ -1420,7 +1420,8 @@
* 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 @@
* 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 @@
* 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 @@
* 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
--- a/src/lexer/PhutilLexer.php
+++ b/src/lexer/PhutilLexer.php
@@ -233,8 +233,8 @@
/**
* 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
--- a/src/lexer/PhutilShellLexer.php
+++ b/src/lexer/PhutilShellLexer.php
@@ -21,7 +21,7 @@
* "\"",
* );
*
- * @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
--- a/src/lint/ArcanistLintMessage.php
+++ b/src/lint/ArcanistLintMessage.php
@@ -184,7 +184,7 @@
}
/**
- * @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 @@
* 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
--- a/src/lint/engine/ArcanistLintEngine.php
+++ b/src/lint/engine/ArcanistLintEngine.php
@@ -291,6 +291,7 @@
/**
* @param dict<string path, dict<string version, list<dict message>>>
+ * $results
* @return this
*/
final public function setCachedResults(array $results) {
@@ -419,9 +420,9 @@
* 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 @@
*
* 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
--- a/src/lint/linter/ArcanistBaseXHPASTLinter.php
+++ b/src/lint/linter/ArcanistBaseXHPASTLinter.php
@@ -101,7 +101,7 @@
/**
* Build futures on this linter, for use and to share with other linters.
*
- * @param list<string> Paths to build futures for.
+ * @param list<string> $paths Paths to build futures for.
* @return list<ExecFuture> Futures.
* @task sharing
*/
@@ -122,7 +122,7 @@
/**
* Release futures on this linter which are no longer in use elsewhere.
*
- * @param list<string> Paths to release futures for.
+ * @param list<string> $paths Paths to release futures for.
* @return void
* @task sharing
*/
@@ -152,7 +152,7 @@
/**
* 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 @@
/**
* 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 @@
* Returns all descendant nodes which represent a function call to one of the
* specified functions.
*
- * @param XHPASTNode Root node.
- * @param list<string> Function names.
+ * @param XHPASTNode $root Root node.
+ * @param list<string> $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
--- a/src/lint/linter/ArcanistChmodLinter.php
+++ b/src/lint/linter/ArcanistChmodLinter.php
@@ -117,7 +117,7 @@
/**
* 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
--- a/src/lint/linter/ArcanistExternalLinter.php
+++ b/src/lint/linter/ArcanistExternalLinter.php
@@ -104,7 +104,7 @@
* Override default flags with custom flags. If not overridden, flags provided
* by @{method:getDefaultFlags} are used.
*
- * @param list<string> New flags.
+ * @param list<string> $flags New flags.
* @return this
* @task bin
*/
@@ -116,7 +116,7 @@
/**
* Set the binary's version requirement.
*
- * @param string Version requirement.
+ * @param string $version Version requirement.
* @return this
* @task bin
*/
@@ -151,7 +151,7 @@
/**
* 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 @@
/**
* Set the interpreter, overriding any default.
*
- * @param string New interpreter.
+ * @param string $interpreter New interpreter.
* @return this
* @task bin
*/
@@ -223,10 +223,10 @@
* 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<ArcanistLintMessage>|false List of lint messages, or false
* to indicate parser failure.
* @task parse
@@ -298,7 +298,7 @@
* 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 @@
*
* 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 @@
*
* 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
--- a/src/lint/linter/ArcanistFutureLinter.php
+++ b/src/lint/linter/ArcanistFutureLinter.php
@@ -47,7 +47,7 @@
* This is invoked after a block of futures resolve, and allows linters to
* discard or clean up any shared resources they no longer need.
*
- * @param map<string, Future> Map of paths to resolved futures.
+ * @param map<string, Future> $futures Map of paths to resolved futures.
* @return void
*/
protected function didResolveLinterFutures(array $futures) {
diff --git a/src/lint/linter/ArcanistLinter.php b/src/lint/linter/ArcanistLinter.php
--- a/src/lint/linter/ArcanistLinter.php
+++ b/src/lint/linter/ArcanistLinter.php
@@ -131,7 +131,7 @@
*
* 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 @@
* Linters which are not parallelizable should normally ignore this callback
* and implement @{method:lintPath} instead.
*
- * @param list<string> A list of paths to be linted
+ * @param list<string> $paths A list of paths to be linted
* @return void
* @task exec
*/
@@ -185,7 +185,7 @@
* 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 @@
* Linters which are not paralleizable should normally ignore this callback
* and implement @{method:lintPath} instead.
*
- * @param list<string> A list of paths which were linted.
+ * @param list<string> $paths A list of paths which were linted.
* @return void
* @task exec
*/
@@ -288,7 +288,7 @@
* Filter out paths which this linter doesn't act on (for example, because
* they are binaries and the linter doesn't apply to binaries).
*
- * @param list<string>
+ * @param list<string> $paths
* @return list<string>
*/
private function filterPaths(array $paths) {
@@ -617,7 +617,7 @@
*
* 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
--- a/src/lint/linter/ArcanistScriptAndRegexLinter.php
+++ b/src/lint/linter/ArcanistScriptAndRegexLinter.php
@@ -324,7 +324,8 @@
/**
* Get the line and character of the message from the regex match.
*
- * @param dict Captured groups from regex.
+ * @param dict $match Captured groups from regex.
+ * @param string $path
* @return pair<int|null,int|null> Line and character of the message.
*
* @task parse
@@ -362,7 +363,7 @@
* 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
--- a/src/lint/linter/ArcanistXHPASTLinter.php
+++ b/src/lint/linter/ArcanistXHPASTLinter.php
@@ -29,7 +29,7 @@
* This is primarily useful for unit tests in which it is desirable to test
* linter rules in isolation. By default, all linter rules will be enabled.
*
- * @param list<ArcanistXHPASTLinterRule>
+ * @param list<ArcanistXHPASTLinterRule> $rules
* @return this
*/
public function setRules(array $rules) {
diff --git a/src/lint/linter/__tests__/ArcanistLinterTestCase.php b/src/lint/linter/__tests__/ArcanistLinterTestCase.php
--- a/src/lint/linter/__tests__/ArcanistLinterTestCase.php
+++ b/src/lint/linter/__tests__/ArcanistLinterTestCase.php
@@ -305,8 +305,8 @@
/**
* 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
--- a/src/lint/linter/standards/ArcanistLinterStandard.php
+++ b/src/lint/linter/standards/ArcanistLinterStandard.php
@@ -35,7 +35,7 @@
/**
* 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 @@
/**
* 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 @@
/**
* Load all linter standards which support a specified linter.
*
- * @param ArcanistLinter
+ * @param ArcanistLinter $linter
* @return list<ArcanistLinterStandard>
*/
final public static function loadAllStandardsForLinter(
diff --git a/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php b/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php
--- a/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php
+++ b/src/lint/linter/xhpast/ArcanistXHPASTLintNamingHook.php
@@ -45,12 +45,13 @@
* }
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
* 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
--- a/src/lint/linter/xhpast/ArcanistXHPASTLinterRule.php
+++ b/src/lint/linter/xhpast/ArcanistXHPASTLinterRule.php
@@ -144,7 +144,7 @@
*
* 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 @@
* 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 @@
/**
* TODO
*
- * @param XHPASTNode
+ * @param XHPASTNode $variable
* @return string
*/
protected function getConcreteVariableString(XHPASTNode $variable) {
@@ -205,8 +205,8 @@
* Returns all descendant nodes which represent a function call to one of the
* specified functions.
*
- * @param XHPASTNode Root node.
- * @param list<string> Function names.
+ * @param XHPASTNode $root Root node.
+ * @param list<string> $function_names Function names.
* @return AASTNodeList
*/
protected function getFunctionCalls(XHPASTNode $root, array $function_names) {
@@ -228,7 +228,7 @@
/**
* Get class/method modifiers.
*
- * @param XHPASTNode A node of type `n_CLASS_DECLARATION` or
+ * @param XHPASTNode $node A node of type `n_CLASS_DECLARATION` or
* `n_METHOD_DECLARATION`.
* @return map<string, bool> Class/method modifiers.
*/
diff --git a/src/moduleutils/PhutilLibraryMapBuilder.php b/src/moduleutils/PhutilLibraryMapBuilder.php
--- a/src/moduleutils/PhutilLibraryMapBuilder.php
+++ b/src/moduleutils/PhutilLibraryMapBuilder.php
@@ -29,7 +29,7 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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
@@ -224,7 +224,7 @@
* 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 @@
* 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 @@
/**
* 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
--- a/src/object/Phobject.php
+++ b/src/object/Phobject.php
@@ -73,8 +73,9 @@
* 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
--- a/src/parser/ArcanistDiffParser.php
+++ b/src/parser/ArcanistDiffParser.php
@@ -1329,7 +1329,7 @@
* 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
--- a/src/parser/PhutilEditorConfig.php
+++ b/src/parser/PhutilEditorConfig.php
@@ -41,7 +41,7 @@
/**
* Constructor.
*
- * @param string The root directory.
+ * @param string $root The root directory.
*/
public function __construct($root) {
$this->root = $root;
@@ -50,8 +50,8 @@
/**
* 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 @@
* the future).
* - Invalid glob patterns will be silently ignored.
*
- * @param string
+ * @param string $path
* @return map<string, wild>
*/
public function getProperties($path) {
diff --git a/src/parser/PhutilJSON.php b/src/parser/PhutilJSON.php
--- a/src/parser/PhutilJSON.php
+++ b/src/parser/PhutilJSON.php
@@ -16,7 +16,7 @@
* 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 @@
/**
* Encode a list in JSON and pretty-print it, discarding keys.
*
- * @param list<wild> List to encode in JSON.
+ * @param list<wild> $list List to encode in JSON.
* @return string Pretty-printed list representation.
*/
public function encodeAsList(array $list) {
@@ -41,8 +41,8 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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
--- a/src/parser/PhutilLanguageGuesser.php
+++ b/src/parser/PhutilLanguageGuesser.php
@@ -9,7 +9,7 @@
/**
* 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
--- a/src/parser/PhutilQueryStringParser.php
+++ b/src/parser/PhutilQueryStringParser.php
@@ -33,7 +33,7 @@
*
* For a more basic parse, see @{method:parseQueryStringToPairList}.
*
- * @param string Query string.
+ * @param string $query_string Query string.
* @return map<string, wild> Parsed dictionary.
*/
public function parseQueryString($query_string) {
@@ -68,7 +68,7 @@
* Use @{method:parseQueryString} to produce a more sophisticated parse which
* applies array rules and returns a dictionary.
*
- * @param string Query string.
+ * @param string $query_string Query string.
* @return list<pair<string, string>> List of parsed parameters.
*/
public function parseQueryStringToPairList($query_string) {
@@ -110,7 +110,7 @@
*
* @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
--- a/src/parser/PhutilSimpleOptions.php
+++ b/src/parser/PhutilSimpleOptions.php
@@ -31,7 +31,7 @@
* 'eyes' => '2',
* );
*
- * @param string Input option list.
+ * @param string $input Input option list.
* @return dict Parsed dictionary.
* @task parse
*/
@@ -130,8 +130,8 @@
*
* 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 @@
* 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
--- a/src/parser/aast/api/AASTNode.php
+++ b/src/parser/aast/api/AASTNode.php
@@ -363,7 +363,7 @@
* 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 @@
* 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 @@
/**
* 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
--- a/src/parser/argument/PhutilArgumentParser.php
+++ b/src/parser/argument/PhutilArgumentParser.php
@@ -95,7 +95,7 @@
*
* $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 @@
* @{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 @@
* 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 @@
* 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 @@
*
* 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 @@
*
* 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
--- a/src/parser/argument/PhutilArgumentSpecification.php
+++ b/src/parser/argument/PhutilArgumentSpecification.php
@@ -34,7 +34,7 @@
* 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
--- a/src/parser/xhpast/api/XHPASTNode.php
+++ b/src/parser/xhpast/api/XHPASTNode.php
@@ -292,7 +292,6 @@
* 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
--- a/src/parser/xhpast/api/__tests__/XHPASTNodeTestCase.php
+++ b/src/parser/xhpast/api/__tests__/XHPASTNodeTestCase.php
@@ -73,7 +73,7 @@
* }
* ```
*
- * @param string The path to the test file.
+ * @param string $file The path to the test file.
* @return pair<XHPASTTree, map> The first element of the pair is the
* `XHPASTTree` contained within the test file.
* The second element of the pair is the
diff --git a/src/parser/xhpast/bin/PhutilXHPASTBinary.php b/src/parser/xhpast/bin/PhutilXHPASTBinary.php
--- a/src/parser/xhpast/bin/PhutilXHPASTBinary.php
+++ b/src/parser/xhpast/bin/PhutilXHPASTBinary.php
@@ -71,7 +71,7 @@
/**
* 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/readableserializer/PhutilReadableSerializer.php b/src/readableserializer/PhutilReadableSerializer.php
--- a/src/readableserializer/PhutilReadableSerializer.php
+++ b/src/readableserializer/PhutilReadableSerializer.php
@@ -19,7 +19,7 @@
* 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 @@
/**
* 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 @@
*
* 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 @@
/**
* 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 @@
* 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
--- a/src/repository/api/ArcanistGitAPI.php
+++ b/src/repository/api/ArcanistGitAPI.php
@@ -82,8 +82,8 @@
/**
* 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 @@
/**
* 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 @@
}
/**
- * @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 @@
}
/**
- * @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 @@
* 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
--- a/src/repository/api/ArcanistMercurialAPI.php
+++ b/src/repository/api/ArcanistMercurialAPI.php
@@ -732,8 +732,9 @@
* 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 @@
* 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 @@
* 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
--- a/src/repository/api/ArcanistRepositoryAPI.php
+++ b/src/repository/api/ArcanistRepositoryAPI.php
@@ -429,7 +429,7 @@
/**
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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/parser/ArcanistMercurialParser.php b/src/repository/parser/ArcanistMercurialParser.php
--- a/src/repository/parser/ArcanistMercurialParser.php
+++ b/src/repository/parser/ArcanistMercurialParser.php
@@ -17,7 +17,7 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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
--- a/src/repository/state/ArcanistRepositoryLocalState.php
+++ b/src/repository/state/ArcanistRepositoryLocalState.php
@@ -211,7 +211,7 @@
/**
* 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
--- a/src/symbols/PhutilClassMapQuery.php
+++ b/src/symbols/PhutilClassMapQuery.php
@@ -60,7 +60,7 @@
* 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 @@
*
* 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 @@
* 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 @@
* 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 @@
/**
* 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
--- a/src/symbols/PhutilSymbolLoader.php
+++ b/src/symbols/PhutilSymbolLoader.php
@@ -56,7 +56,7 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* This method implicitly restricts the query to match only concrete
* classes.
*
- * @param list<wild> List of constructor arguments.
+ * @param list<wild> $argv List of constructor arguments.
* @return map<string, object> Map of class names to constructed objects.
*/
public function loadObjects(array $argv = array()) {
diff --git a/src/unit/ArcanistUnitTestResult.php b/src/unit/ArcanistUnitTestResult.php
--- a/src/unit/ArcanistUnitTestResult.php
+++ b/src/unit/ArcanistUnitTestResult.php
@@ -80,7 +80,7 @@
* 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 @@
/**
* 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
--- a/src/unit/engine/CSharpToolsTestEngine.php
+++ b/src/unit/engine/CSharpToolsTestEngine.php
@@ -81,7 +81,7 @@
* 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 @@
/**
* 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 @@
* 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 @@
/**
* 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 @@
* 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 @@
/**
* 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
--- a/src/unit/engine/PhpunitTestEngine.php
+++ b/src/unit/engine/PhpunitTestEngine.php
@@ -118,7 +118,7 @@
* 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 @@
* ...or similar. This list will be further pruned by the caller; it is
* intentionally filesystem-agnostic to be unit testable.
*
- * @param string PHP file to locate test cases for.
+ * @param string $path PHP file to locate test cases for.
* @return list<string> List of directories to search for tests in.
*/
public static function getSearchLocationsForTests($path) {
diff --git a/src/unit/engine/XUnitTestEngine.php b/src/unit/engine/XUnitTestEngine.php
--- a/src/unit/engine/XUnitTestEngine.php
+++ b/src/unit/engine/XUnitTestEngine.php
@@ -115,7 +115,7 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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
--- a/src/unit/engine/phutil/PhutilTestCase.php
+++ b/src/unit/engine/phutil/PhutilTestCase.php
@@ -28,10 +28,11 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
* 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 @@
*
* 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
*/
@@ -483,7 +487,8 @@
/**
* 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 @@
/**
* 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 @@
* This hook is invoked once, before any test cases execute. It gives you
* an opportunity to perform setup steps for the entire suite of test cases.
*
- * @param list<PhutilTestCase> List of test cases to be run.
+ * @param list<PhutilTestCase> $test_cases List of test cases to be run.
* @return void
* @task hook
*/
@@ -520,7 +525,7 @@
/**
* This hook is invoked once, after all test cases execute.
*
- * @param list<PhutilTestCase> List of test cases that ran.
+ * @param list<PhutilTestCase> $test_cases List of test cases that ran.
* @return void
* @task hook
*/
@@ -544,7 +549,7 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
*
* 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
--- a/src/unit/parser/ArcanistTestResultParser.php
+++ b/src/unit/parser/ArcanistTestResultParser.php
@@ -40,8 +40,8 @@
* 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
--- a/src/upload/ArcanistFileDataRef.php
+++ b/src/upload/ArcanistFileDataRef.php
@@ -40,7 +40,7 @@
* 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 @@
* 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 @@
* 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 @@
* 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
--- a/src/upload/ArcanistFileUploader.php
+++ b/src/upload/ArcanistFileUploader.php
@@ -46,8 +46,8 @@
* 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
--- a/src/utils/AbstractDirectedGraph.php
+++ b/src/utils/AbstractDirectedGraph.php
@@ -55,7 +55,7 @@
* 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 @@
* 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 @@
* 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 @@
* 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
--- a/src/utils/CaseInsensitiveArray.php
+++ b/src/utils/CaseInsensitiveArray.php
@@ -50,7 +50,7 @@
/**
* 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 @@
* [[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
--- a/src/utils/PhutilBufferedIterator.php
+++ b/src/utils/PhutilBufferedIterator.php
@@ -61,7 +61,7 @@
/**
* 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
--- a/src/utils/PhutilCallbackFilterIterator.php
+++ b/src/utils/PhutilCallbackFilterIterator.php
@@ -7,8 +7,8 @@
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
--- a/src/utils/PhutilChunkedIterator.php
+++ b/src/utils/PhutilChunkedIterator.php
@@ -12,8 +12,8 @@
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
--- a/src/utils/PhutilRope.php
+++ b/src/utils/PhutilRope.php
@@ -19,7 +19,7 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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
--- a/src/utils/PhutilSystem.php
+++ b/src/utils/PhutilSystem.php
@@ -106,7 +106,7 @@
* 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<string, wild> Parsed memory information.
* @task memory
*/
@@ -159,7 +159,7 @@
* 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<string, wild> Parsed memory information.
* @task memory
*/
diff --git a/src/utils/utf8.php b/src/utils/utf8.php
--- 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 @@
* 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 @@
/**
* 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 @@
* 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 @@
/**
* 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 @@
*
* 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 @@
*
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* Replace characters in a string in a UTF-aware way. Similar to
* @{function:strtr}.
*
- * @param string UTF-8 input string.
- * @param map<string, string> Map of characters to replace.
+ * @param string $str UTF-8 input string.
+ * @param map<string, string> $map Map of characters to replace.
* @return string Input with translated characters.
*/
function phutil_utf8_strtr($str, array $map) {
@@ -854,7 +856,7 @@
/**
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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
--- a/src/utils/utils.php
+++ b/src/utils/utils.php
@@ -27,10 +27,10 @@
* 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 @@
* `$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<string> List of keys to access, in sequence.
- * @param wild Default value to return.
+ * @param array $map Array to access.
+ * @param list<string> $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 @@
* 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 @@
* 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 @@
*
* 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 @@
* 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 @@
* 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 @@
*
* 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 @@
*
* 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: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 @@
*
* 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 @@
*
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
*
* $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 @@
*
* 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 @@
/**
* 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 @@
* 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 @@
*
* ...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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* Decode an INI string.
*
- * @param string
+ * @param string $string
* @return mixed
*/
function phutil_ini_decode($string) {
@@ -1508,7 +1514,7 @@
* 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 @@
* 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 @@
/**
* 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 @@
* 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 @@
/**
* Build a query string from a dictionary.
*
- * @param map<string, string> Dictionary of parameters.
+ * @param map<string, string> $parameters Dictionary of parameters.
* @return string HTTP query string.
*/
function phutil_build_http_querystring(array $parameters) {
@@ -1701,7 +1707,7 @@
/**
* Build a query string from a list of parameter pairs.
*
- * @param list<pair<string, string>> List of pairs.
+ * @param list<pair<string, string>> $pairs List of pairs.
* @return string HTTP query string.
*/
function phutil_build_http_querystring_from_pairs(array $pairs) {
@@ -1733,8 +1739,8 @@
*
* 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<string, string> Key and value as strings.
*/
function phutil_http_parameter_pair($key, $value) {
@@ -1800,7 +1806,7 @@
* 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 @@
* 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 @@
* 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_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 @@
* 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 @@
* 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 @@
*
* 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 @@
*
* 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
--- a/src/utils/viewutils.php
+++ b/src/utils/viewutils.php
@@ -24,9 +24,9 @@
* 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 @@
* 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 @@
/**
* 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
--- a/src/workflow/ArcanistDiffWorkflow.php
+++ b/src/workflow/ArcanistDiffWorkflow.php
@@ -1803,7 +1803,7 @@
* 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
*/
@@ -2398,8 +2398,8 @@
/**
* 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/ArcanistUnitWorkflow.php b/src/workflow/ArcanistUnitWorkflow.php
--- a/src/workflow/ArcanistUnitWorkflow.php
+++ b/src/workflow/ArcanistUnitWorkflow.php
@@ -352,8 +352,8 @@
* 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
--- a/src/workflow/ArcanistWorkflow.php
+++ b/src/workflow/ArcanistWorkflow.php
@@ -315,8 +315,8 @@
*
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
* 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/workingcopyidentity/ArcanistWorkingCopyIdentity.php b/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php
--- a/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php
+++ b/src/workingcopyidentity/ArcanistWorkingCopyIdentity.php
@@ -51,10 +51,11 @@
* 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 @@
* 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
--- 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 @@
/**
* 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
--- 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
--- 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 @@
* 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,

File Metadata

Mime Type
text/plain
Expires
Thu, Dec 19, 01:40 (12 h, 52 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1014985
Default Alt Text
D25799.1734572443.diff (186 KB)

Event Timeline

Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0