AdapterInterface documentation

Author: WyriHaximus

src/AdapterInterface.php

@@ -3,6 +3,7 @@
 namespace React\Filesystem;
 
 use React\EventLoop\LoopInterface;
+use React\Promise\PromiseInterface;
 
 interface AdapterInterface
 {
@@ -15,137 +16,180 @@ interface AdapterInterface
     public function __construct(LoopInterface $loop, array $options = []);
 
     /**
+     * Return the loop associated with this adapter.
+     *
      * @return LoopInterface
      */
     public function getLoop();
 
     /**
+     * Set the relevant filesystem for this adapter.
+     *
+     * @internal
      * @param FilesystemInterface $filesystem
      * @return void
      */
     public function setFilesystem(FilesystemInterface $filesystem);
 
     /**
+     * Set the call invoker for this adapter.
+     *
      * @param CallInvokerInterface $invoker
      * @return void
      */
     public function setInvoker(CallInvokerInterface $invoker);
 
     /**
+     * Call the underlying filesystem.
+     *
+     * @internal
      * @param string $function
      * @param array $args
      * @param int $errorResultCode
-     * @return \React\Promise\Promise
+     * @return PromiseInterface
      */
     public function callFilesystem($function, $args, $errorResultCode = -1);
 
     /**
+     * Create a directory at the given path with the given mode.
+     *
      * @param string $path
      * @param $mode
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function mkdir($path, $mode = self::CREATION_MODE);
 
     /**
+     * Remove the given directory.
+     *
      * @param string $path
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function rmdir($path);
 
     /**
+     * Remove the given file.
+     *
      * @param string $filename
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function unlink($filename);
 
     /**
+     * Change the mode of the given path.
+     *
      * @param string $path
      * @param int $mode
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function chmod($path, $mode);
 
     /**
+     * Change the owner of the given path.
+     *
      * @param string $path
      * @param int $uid
      * @param int $gid
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function chown($path, $uid, $gid);
 
     /**
+     * Stat the node, returning information such as the file, c/m/a-time, mode, g/u-id, and more.
+     *
      * @param string $filename
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function stat($filename);
 
     /**
+     * List contents of the given path.
+     *
      * @param string $path
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function ls($path);
 
     /**
+     * Touch the given path, either creating a file, or updating mtime on the file.
+     *
      * @param string $path
      * @param $mode
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function touch($path, $mode = self::CREATION_MODE);
 
     /**
+     * Open a file for reading or writing at the given path. This will return a file descriptor,
+     * which can be used to read or write to the file. And ultimately close the file descriptor.
+     *
      * @param string $path
      * @param string $flags
      * @param $mode
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface<file descriptor>
      */
     public function open($path, $flags, $mode = self::CREATION_MODE);
 
     /**
+     * Read from the given file descriptor.
+     *
      * @param $fileDescriptor
      * @param int $length
      * @param int $offset
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function read($fileDescriptor, $length, $offset);
 
     /**
+     * Write to the given file descriptor.
+     *
      * @param $fileDescriptor
      * @param string $data
      * @param int $length
      * @param int $offset
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function write($fileDescriptor, $data, $length, $offset);
 
     /**
+     * Close the given file descriptor.
+     *
      * @param resource $fd
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function close($fd);
 
     /**
+     * Rename a node.
+     *
      * @param string $fromPath
      * @param string $toPath
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function rename($fromPath, $toPath);
 
     /**
+     * Read link information from the given path (has to be a symlink).
+     *
      * @param string $path
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function readlink($path);
 
     /**
+     * Create a symlink from $fromPath to $toPath.
+     *
      * @param string $fromPath
      * @param string $toPath
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function symlink($fromPath, $toPath);
 
     /**
+     * Detect the type of the given path.
+     *
      * @param string $path
-     * @return \React\Promise\PromiseInterface
+     * @return PromiseInterface
      */
     public function detectType($path);
 }