Add docs to README

Author: kelunik

README.md

@@ -1,6 +1,10 @@
-# file ![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)
+# amphp/file
 
-`amphp/file` allows non-blocking access to the filesystem for [Amp](https://github.com/amphp/amp).
+AMPHP is a collection of event-driven libraries for PHP designed with fibers and concurrency in mind.
+`amphp/file` provides non-blocking file system access.
+
+[![Latest Release](https://img.shields.io/github/release/amphp/file.svg?style=flat-square)](https://github.com/amphp/file/releases)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/amphp/file/blob/master/LICENSE)
 
 ## Installation
 
@@ -10,15 +14,191 @@ This package can be installed as a [Composer](https://getcomposer.org/) dependen
 composer require amphp/file
 ```
 
-## Optional Extension Backends
+`amphp/file` works out of the box without any PHP extensions.
+It uses multiple processes by default, but also comes with a blocking driver that just uses PHP's blocking functions in the current process.
+
+Extensions allow using threading in the background instead of using multiple processes:
+
+- [`ext-eio`](https://pecl.php.net/package/eio)
+- [`ext-uv`](https://github.com/amphp/ext-uv)
+- [`ext-parallel`](https://github.com/krakjoe/parallel)
+
+## Usage
+
+### read
+
+Read the specified file's contents:
+
+```php
+$contents = Amp\File\read('/path/to/file.txt');
+```
+
+### write
+
+Write the contents string to the specified path:
+
+```php
+Amp\File\write('/path/to/file.txt', 'contents');
+```
+
+### openFile
+
+Open a [`File` handle](#file) for the specified path, e.g. to stream data:
+
+```php
+$file = Amp\File\openFile('/path/to/file.txt', 'r');
+Amp\ByteStream\pipe($file, getStdout());
+```
+
+### getStatus
+
+Execute a file stat operation.
+
+If the requested path does not exist the function will return `null`.
+
+### getLinkStatus
+
+Same as [`getStatus()`](#getstatus) except if the path is a link then the link's data is returned.
+
+If the requested path does not exist the function will return `null`.
+
+### exists
+
+Checks whether the specified path exists.
+
+### getSize
+
+Returns the file size in bytes.
+
+### isDirectory
+
+Checks whether the given path exists and is a directory.
+
+### isFile
+
+Checks whether the given path exists and is a regular file.
+
+### isSymlink
+
+Checks whether the given path exists and is a symlink.
+
+### getModificationTime
+
+Returns the file's modification time as Unix timestamp in seconds.
+
+### getAccessTime
+
+Returns the file's access time as Unix timestamp in seconds.
+
+### getCreationTime
+
+Returns the file's creation time as Unix timestamp in seconds.
+
+### createHardlink
+
+Creates a new hardlink.
+
+### createSymlink
+
+Creates a new symlink.
+
+### resolveSymlink
+
+Resolves a symlink to its target path.
+
+### move
+
+Move / rename a file or directory.
+
+### deleteFile
+
+Deletes a file.
+
+### createDirectory
+
+Creates a directory.
+
+### createDirectoriesRecursively
+
+Creates a directory and its parents.
+
+### deleteDirectory
+
+Deletes a directory.
+
+### listFiles
+
+List all files and subdirectories in a directory.
+
+### changePermissions
+
+Change the permissions of a file or directory.
+
+### changeOwner
+
+Change the ownership of a file or directory.
+
+### touch
+
+Update the access and modification time of the specified path.
+
+If the file does not exist it will be created automatically.
+
+### File
+
+Reference to an open file handle.
+
+#### File::read
+
+See also `File::isReadable`.
+
+#### File::write
+
+See also `File::isWritable`.
+
+#### File::end
+
+See `WritableStream::end()`.
+
+#### File::close
+
+Close the file handle.
+
+ - `File::isClosed()` can be used to check if the file handle has already been closed. 
+ - `File::onClose()` can be used ot register a callback that's called on file handle closure.
+
+#### File::seek
+
+Set the internal pointer position.
+
+ - `SEEK_SET`: Set position equal to offset bytes.
+ - `SEEK_CUR`: Set position to current location plus offset.
+ - `SEEK_END`: Set position to end-of-file plus offset.
+
+Returns the new offset position.
+
+See also `File::isSeekable`.
+
+#### File::tell
+
+Return the current internal offset position of the file handle.
+
+#### File::eof
+
+Test for being at the end of the stream (a.k.a. "end-of-file").
+
+#### File::getPath
+
+Retrieve the path used when opening the file handle.
+
+#### File::getMode
+
+Retrieve the mode used when opening the file handle.
 
-Extensions allow using threading in the background instead of using multiple processes.
- 
- - [`ext-eio`](https://pecl.php.net/package/eio)
- - [`ext-uv`](https://github.com/amphp/ext-uv)
- - [`ext-parallel`](https://github.com/krakjoe/parallel)
+#### File::truncate
 
-`amphp/file` works out of the box without any PHP extensions. It uses multi-processing by default, but also comes with a blocking driver that just uses PHP's blocking functions in the current process.
+Truncates the file to the given length.
+If `$size` is larger than the current file size, the file is extended with NUL bytes.
 
 ## Versioning
 

src/File.php

@@ -16,8 +16,6 @@ interface File extends ReadableStream, WritableStream
 
     /**
      * Read $length bytes from the open file handle.
-     *
-     *
      */
     public function read(?Cancellation $cancellation = null, int $length = self::DEFAULT_READ_LENGTH): ?string;
 
@@ -30,20 +28,17 @@ public function read(?Cancellation $cancellation = null, int $length = self::DEF
      * SEEK_CUR - Set position to current location plus offset.
      * SEEK_END - Set position to end-of-file plus offset.
      *
-     *
      * @return int New offset position.
      */
     public function seek(int $position, int $whence = self::SEEK_SET): int;
 
     /**
      * Return the current internal offset position of the file handle.
-     *
      */
     public function tell(): int;
 
     /**
      * Test for being at the end of the stream (a.k.a. "end-of-file").
-     *
      */
     public function eof(): bool;
 
@@ -54,13 +49,11 @@ public function isSeekable(): bool;
 
     /**
      * Retrieve the path used when opening the file handle.
-     *
      */
     public function getPath(): string;
 
     /**
      * Retrieve the mode used when opening the file handle.
-     *
      */
     public function getMode(): string;
 

src/functions.php

@@ -264,15 +264,15 @@ function listFiles(string $path): array
 }
 
 /**
- * Change permissions of a file or directory.
+ * Change the permissions of a file or directory.
  */
 function changePermissions(string $path, int $mode): void
 {
     filesystem()->changePermissions($path, $mode);
 }
 
 /**
- * Change ownership of a file or directory.
+ * Change the ownership of a file or directory.
  *
  * @param int|null $uid null to ignore
  * @param int|null $gid null to ignore
@@ -296,7 +296,7 @@ function touch(string $path, ?int $modificationTime = null, ?int $accessTime = n
 }
 
 /**
- * Buffer the specified file's contents.
+ * Read the specified file's contents.
  *
  * @param string $path The file path from which to buffer contents.
  */