Page Menu
Home
Phorge
Search
Configure Global Search
Log In
Files
F2680865
D25799.1734629936.diff
No One
Temporary
Actions
View File
Edit File
Delete File
View Transforms
Subscribe
Award Token
Flag For Later
Advanced/Developer...
View Handle
View Hovercard
Size
186 KB
Referenced Files
None
Subscribers
None
D25799.1734629936.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
Details
Attached
Mime Type
text/plain
Expires
Thu, Dec 19, 17:38 (20 h, 25 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1014985
Default Alt Text
D25799.1734629936.diff (186 KB)
Attached To
Mode
D25799: Add missing variable names to PHPDoc @param of methods
Attached
Detach File
Event Timeline
Log In to Comment