azjezz · azjezz · May 7, 2022 · Apr 10, 2022 · Apr 11, 2022 · Apr 11, 2022
diff --git a/docs/component/filesystem.md b/docs/component/filesystem.md
@@ -19,7 +19,7 @@
 - [canonicalize](./../../src/Psl/Filesystem/canonicalize.php#L15)
 - [change_group](./../../src/Psl/Filesystem/change_group.php#L21)
 - [change_owner](./../../src/Psl/Filesystem/change_owner.php#L21)
-- [change_permissions](./../../src/Psl/Filesystem/change_permissions.php#L20)
+- [change_permissions](./../../src/Psl/Filesystem/change_permissions.php#L21)
 - [copy](./../../src/Psl/Filesystem/copy.php#L22)
 - [create_directory](./../../src/Psl/Filesystem/create_directory.php#L19)
 - [create_file](./../../src/Psl/Filesystem/create_file.php#L24)
@@ -28,25 +28,25 @@
 - [create_temporary_file](./../../src/Psl/Filesystem/create_temporary_file.php#L26)
 - [delete_directory](./../../src/Psl/Filesystem/delete_directory.php#L23)
 - [delete_file](./../../src/Psl/Filesystem/delete_file.php#L21)
-- [exists](./../../src/Psl/Filesystem/exists.php#L21)
+- [exists](./../../src/Psl/Filesystem/exists.php#L16)
 - [file_size](./../../src/Psl/Filesystem/file_size.php#L22)
 - [get_access_time](./../../src/Psl/Filesystem/get_access_time.php#L20)
 - [get_basename](./../../src/Psl/Filesystem/get_basename.php#L23)
-- [get_change_time](./../../src/Psl/Filesystem/get_change_time.php#L21)
+- [get_change_time](./../../src/Psl/Filesystem/get_change_time.php#L23)
 - [get_directory](./../../src/Psl/Filesystem/get_directory.php#L24)
 - [get_extension](./../../src/Psl/Filesystem/get_extension.php#L18)
 - [get_filename](./../../src/Psl/Filesystem/get_filename.php#L20)
 - [get_group](./../../src/Psl/Filesystem/get_group.php#L20)
 - [get_inode](./../../src/Psl/Filesystem/get_inode.php#L20)
-- [get_modification_time](./../../src/Psl/Filesystem/get_modification_time.php#L20)
+- [get_modification_time](./../../src/Psl/Filesystem/get_modification_time.php#L22)
 - [get_owner](./../../src/Psl/Filesystem/get_owner.php#L20)
 - [get_permissions](./../../src/Psl/Filesystem/get_permissions.php#L20)
-- [is_directory](./../../src/Psl/Filesystem/is_directory.php#L21)
-- [is_executable](./../../src/Psl/Filesystem/is_executable.php#L19)
-- [is_file](./../../src/Psl/Filesystem/is_file.php#L21)
-- [is_readable](./../../src/Psl/Filesystem/is_readable.php#L19)
-- [is_symbolic_link](./../../src/Psl/Filesystem/is_symbolic_link.php#L19)
-- [is_writable](./../../src/Psl/Filesystem/is_writable.php#L19)
+- [is_directory](./../../src/Psl/Filesystem/is_directory.php#L15)
+- [is_executable](./../../src/Psl/Filesystem/is_executable.php#L15)
+- [is_file](./../../src/Psl/Filesystem/is_file.php#L15)
+- [is_readable](./../../src/Psl/Filesystem/is_readable.php#L14)
+- [is_symbolic_link](./../../src/Psl/Filesystem/is_symbolic_link.php#L14)
+- [is_writable](./../../src/Psl/Filesystem/is_writable.php#L14)
 - [read_directory](./../../src/Psl/Filesystem/read_directory.php#L21)
 - [read_symbolic_link](./../../src/Psl/Filesystem/read_symbolic_link.php#L23)
 

diff --git a/src/Psl/File/WriteMode.php b/src/Psl/File/WriteMode.php
@@ -11,7 +11,7 @@ enum WriteMode: string
      * the file.
      *
      * If the file exits, it is not truncated (as with `TRUNCATE`), and the call
-     * succeeds (unlike `EXCLUSIVE_CREATE`).
+     * succeeds (unlike `MUST_CREATE`).
      */
     case OPEN_OR_CREATE = 'cb';
 

diff --git a/src/Psl/Filesystem/canonicalize.php b/src/Psl/Filesystem/canonicalize.php
@@ -8,9 +8,9 @@
 
 /**
  * Returns canonicalized absolute pathname.
+ * The resulting path will have no symbolic links, '/./' or '/../' components.
  *
- * @return non-empty-string|null The canonicalized absolute pathname on success.
- *                               The resulting path will have no symbolic link, '/./' or '/../' components.
+ * @return non-empty-string|null
  */
 function canonicalize(string $path): ?string
 {

diff --git a/src/Psl/Filesystem/change_permissions.php b/src/Psl/Filesystem/change_permissions.php
@@ -10,9 +10,10 @@
 use function chmod;
 
 /**
- * Changes mode permission of $node.
+ * Change permission mode of $node.
  *
  * @param non-empty-string $node
+ * @param int $permissions Permissions as an octal number, e.g. `0755`.
  *
  * @throws Exception\RuntimeException If unable to change the mode for the given $node.
  * @throws Exception\NotFoundException If $node does not exist.

diff --git a/src/Psl/Filesystem/copy.php b/src/Psl/Filesystem/copy.php
@@ -10,12 +10,12 @@
 use Psl\Str;
 
 /**
- * Copy $source to $destination and preserve executable permission bits.
+ * Copy a file from $source to $destination and preserve executable permission bits.
  *
  * @param non-empty-string $source
  * @param non-empty-string $destination
  *
- * @throws Exception\RuntimeException If unable to change the group ownership for $filename.
+ * @throws Exception\RuntimeException If unable to copy $source to $destination.
  * @throws Exception\NotFoundException If $source is not found.
  * @throws Exception\NotReadableException If $source is not readable.
  */

diff --git a/src/Psl/Filesystem/create_file.php b/src/Psl/Filesystem/create_file.php
@@ -14,10 +14,10 @@
  * Create the file specified by $filename.
  *
  * @param non-empty-string $filename
- * @param int|null $time The touch time as a Unix timestamp,
- *                       If not supplied the current system time is used.
- * @param int|null $access_time The access time as a Unix timestamp,
- *                              If not supplied the current system time is used.
+ * @param int|null $time The touch time as a Unix timestamp.
+ *                       Defaults to the current system time.
+ * @param int|null $access_time The access time as a Unix timestamp.
+ *                              Defaults to the current system time.
  *
  * @throws Exception\RuntimeException If unable to create the file.
  */

diff --git a/src/Psl/Filesystem/create_hard_link.php b/src/Psl/Filesystem/create_hard_link.php
@@ -15,7 +15,7 @@
  * @param non-empty-string $source The file to create a hard link for.
  * @param non-empty-string $destination
  *
- * @throws Exception\RuntimeException If unable to create a hard file.
+ * @throws Exception\RuntimeException If unable to create the hard link.
  * @throws Exception\NotFoundException If $source does not exist.
  * @throws Exception\NotFileException If $source is not a file.
  * @throws Exception\NotReadableException If $destination is a non-empty directory, and is non-readable {@see delete_directory()}.

diff --git a/src/Psl/Filesystem/create_symbolic_link.php b/src/Psl/Filesystem/create_symbolic_link.php
@@ -12,7 +12,7 @@
 /**
  * Create a symbolic link for $source.
  *
- * @param non-empty-string $source The file to create a hard link for.
+ * @param non-empty-string $source The file to create a symbolic link for.
  * @param non-empty-string $destination
  *
  * @throws Exception\RuntimeException If unable to create the symbolic link.

diff --git a/src/Psl/Filesystem/create_temporary_file.php b/src/Psl/Filesystem/create_temporary_file.php
@@ -11,8 +11,8 @@
 /**
  * Create a temporary file.
  *
- * @param non-empty-string|null $directory The directory where the temporary filename will be created.
- *                                         If no specified, `Env\temp_dir()` will be used to retrieve
+ * @param non-empty-string|null $directory The directory where the temporary file will be created.
+ *                                         If none specified, `Env\temp_dir()` will be used to retrieve
  *                                         the system default temporary directory.
  * @param non-empty-string|null $prefix The prefix of the generated temporary filename.
  *

diff --git a/src/Psl/Filesystem/delete_file.php b/src/Psl/Filesystem/delete_file.php
@@ -16,7 +16,7 @@
  *
  * @throws Exception\RuntimeException If unable to delete the file.
  * @throws Exception\NotFileException If $file is not a file.
- * @throws Exception\NotFoundException If $file is not a found.
+ * @throws Exception\NotFoundException If $file is not found.
  */
 function delete_file(string $file): void
 {

diff --git a/src/Psl/Filesystem/exists.php b/src/Psl/Filesystem/exists.php
@@ -9,12 +9,7 @@
 /**
  * Check whether $node exists.
  *
- * @param string $node Path to the file.
- *
- * If $node is a relative filename, it will be checked relative to
- * the current working directory.
- *
- * @return bool true if $node exists, false otherwise.
+ * @param string $node Path, absolute or relative to the current working directory.
  *
  * @psalm-assert-if-true non-empty-string $node
  */

diff --git a/src/Psl/Filesystem/file_size.php b/src/Psl/Filesystem/file_size.php
@@ -8,7 +8,7 @@
 use Psl\Str;
 
 /**
- * Ge the size of $file.
+ * Get the size of $file.
  *
  * @param non-empty-string $file
  *

diff --git a/src/Psl/Filesystem/get_access_time.php b/src/Psl/Filesystem/get_access_time.php
@@ -10,7 +10,7 @@
 use function fileatime;
 
 /**
- * Gets last access time of $node.
+ * Get last access time of $node.
  *
  * @param non-empty-string $node
  *

diff --git a/src/Psl/Filesystem/get_basename.php b/src/Psl/Filesystem/get_basename.php
@@ -7,16 +7,16 @@
 use function basename as php_basename;
 
 /**
- * Returns trailing name component of path.
+ * Get the last component of $path.
  *
- * On Windows, both forward slash `/` and back slash `\` are used
- * as directory separator character.
+ * On Windows, both forward slash `/` and backslash `\` are used
+ * as a directory separator character.
  *
  * In other environments, it is the forward slash `/`.
  *
- * @param non-empty-string|null $suffix If the filename ends in a suffix, this will also be cut off.
+ * @param non-empty-string|null $suffix If the filename ends in a suffix, it will also be cut off.
  *
- * @return non-empty-string the base name of the given path.
+ * @return non-empty-string
  *
  * @pure
  */

diff --git a/src/Psl/Filesystem/get_change_time.php b/src/Psl/Filesystem/get_change_time.php
@@ -10,13 +10,15 @@
 use function filectime;
 
 /**
- * Get the last time the inode of $node
- * was changed ( e.g: permission change, ownership change .. etc ).
+ * Get the last time the inode of $node was changed
+ * (e.g. permission change or ownership change).
  *
  * @param non-empty-string $node
  *
  * @throws Exception\NotFoundException If $node is not found.
  * @throws Exception\RuntimeException In case of an error.
+ *
+ * @return int The last inode modification time as a Unix timestamp.
  */
 function get_change_time(string $node): int
 {

diff --git a/src/Psl/Filesystem/get_directory.php b/src/Psl/Filesystem/get_directory.php
@@ -7,17 +7,17 @@
 use function dirname;
 
 /**
- * Returns a parent directory's path.
+ * Get a parent directory path.
  *
- * On Windows, both forward slash `/` and back slash `\` are used
- * as directory separator character.
+ * On Windows, both forward slash `/` and backslash `\` are used
+ * as a directory separator character.
  *
  * In other environments, it is the forward slash `/`.
  *
  * @param non-empty-string $node
  * @param positive-int $levels The number of parent directories to go up.
  *
- * @return non-empty-string the base name of the given path.
+ * @return non-empty-string
  *
  * @pure
  */

diff --git a/src/Psl/Filesystem/get_extension.php b/src/Psl/Filesystem/get_extension.php
@@ -7,11 +7,11 @@
 use function pathinfo;
 
 /**
- * Returns the $node extension.
+ * Get the $node extension.
  *
  * @param non-empty-string $node
  *
- * @return non-empty-string|null the $node extensions, or null if none.
+ * @return non-empty-string|null The $node extensions, or null if none.
  *
  * @pure
  */

diff --git a/src/Psl/Filesystem/get_filename.php b/src/Psl/Filesystem/get_filename.php
@@ -9,11 +9,11 @@
 use const PATHINFO_FILENAME;
 
 /**
- * Returns trailing name component of path.
+ * Get the last component of $node, excluding extension.
  *
  * @param non-empty-string $node
  *
- * @return non-empty-string the base name of the given path.
+ * @return non-empty-string
  *
  * @pure
  */

diff --git a/src/Psl/Filesystem/get_inode.php b/src/Psl/Filesystem/get_inode.php
@@ -10,7 +10,7 @@
 use function fileinode;
 
 /**
- * Get the last time the content of $node was modified.
+ * Get inode number of $node.
  *
  * @param non-empty-string $node
  *

diff --git a/src/Psl/Filesystem/get_modification_time.php b/src/Psl/Filesystem/get_modification_time.php
@@ -16,6 +16,8 @@
  *
  * @throws Exception\NotFoundException If $node is not found.
  * @throws Exception\RuntimeException In case of an error.
+ *
+ * @return int The last content modification time as a Unix timestamp.
  */
 function get_modification_time(string $node): int
 {

diff --git a/src/Psl/Filesystem/is_directory.php b/src/Psl/Filesystem/is_directory.php
@@ -7,16 +7,10 @@
 use function is_dir;
 
 /**
- * Check whether $node is a directory.
+ * Check whether $node exists and is a directory.
  *
- * If $node is a relative filename, it will be checked relative to
- * the current working directory.
- *
- * If $node is a symbolic or hard link then the link will be resolved and checked.
- *
- * @param non-empty-string $node
- *
- * @return bool true if $node exists and is a directory, false otherwise.
+ * @param non-empty-string $node Path, absolute or relative to the current working directory.
+ *                               If it is a link, it will be resolved and checked.
  */
 function is_directory(string $node): bool
 {

diff --git a/src/Psl/Filesystem/is_executable.php b/src/Psl/Filesystem/is_executable.php
@@ -7,14 +7,10 @@
 use function is_executable as php_is_executable;
 
 /**
- * Check whether $node is executable.
+ * Check whether $node exists and is an executable file
+ * or a directory with `execute` permission.
  *
- * If $node is a relative filename, it will be checked relative to
- * the current working directory.
- *
- * @param non-empty-string $node
- *
- * @return bool true if the file or directory specified by $node exists and is executable, false otherwise.
+ * @param non-empty-string $node Path, absolute or relative to the current working directory.
  */
 function is_executable(string $node): bool
 {

diff --git a/src/Psl/Filesystem/is_file.php b/src/Psl/Filesystem/is_file.php
@@ -7,16 +7,10 @@
 use function is_file as php_is_file;
 
 /**
- * Check whether $node is a regular file.
+ * Check whether $node exists and is a regular file or a link to one.
  *
- * If $node is a relative filename, it will be checked relative to
- * the current working directory.
- *
- * If $node is a symbolic or hard link then the link will be resolved and checked.
- *
- * @param non-empty-string $node
- *
- * @return bool true if $node exists and is a regular file, false otherwise.
+ * @param non-empty-string $node Path, absolute or relative to the current working directory.
+ *                               If it is a link, it will be resolved and checked.
  */
 function is_file(string $node): bool
 {

diff --git a/src/Psl/Filesystem/is_readable.php b/src/Psl/Filesystem/is_readable.php
@@ -7,14 +7,9 @@
 use function is_readable as php_is_readable;
 
 /**
- * Check whether $node is readable.
+ * Check whether $node exists and is readable.
  *
- * If $node is a relative filename, it will be checked relative to
- * the current working directory.
- *
- * @param non-empty-string $node
- *
- * @return bool true if the file or directory specified by $node exists and is readable, false otherwise.
+ * @param non-empty-string $node Path, absolute or relative to the current working directory.
  */
 function is_readable(string $node): bool
 {

diff --git a/src/Psl/Filesystem/is_symbolic_link.php b/src/Psl/Filesystem/is_symbolic_link.php
@@ -7,14 +7,9 @@
 use function is_link as php_is_link;
 
 /**
- * Check whether $symbolic_link is a symbolic link.
+ * Check whether $symbolic_link exists and is a symbolic link.
  *
- * If $node is a relative filename, it will be checked relative to
- * the current working directory.
- *
- * @param non-empty-string $node
- *
- * @return bool true if the file or directory specified by $node exists and is a symbolic link, false otherwise.
+ * @param non-empty-string $node Path, absolute or relative to the current working directory.
  */
 function is_symbolic_link(string $node): bool
 {

diff --git a/src/Psl/Filesystem/is_writable.php b/src/Psl/Filesystem/is_writable.php
@@ -7,14 +7,9 @@
 use function is_writable as php_is_writable;
 
 /**
- * Check whether $node is writable.
+ * Check whether $node exists and is writable.
  *
- * If $node is a relative filename, it will be checked relative to
- * the current working directory.
- *
- * @param non-empty-string $node
- *
- * @return bool true if the file or directory specified by $node exists and is writable, false otherwise.
+ * @param non-empty-string $node Path, absolute or relative to the current working directory.
  */
 function is_writable(string $node): bool
 {