Merge pull request #163 from jow-/docs-improvements

fs: complete function documentation coverage

1 files changed, 224 insertions, 3 deletions

diff --git a/lib/fs.c b/lib/fs.c
index bd053f2..55e09c5 100644
--- a/lib/fs.c
+++ b/lib/fs.c
@@ -268,6 +268,28 @@ uc_fs_fileno_common(uc_vm_t *vm, size_t nargs, const char *type)
  * handle.fileno();
  *
  * handle.close();
+ *
+ * handle.error();
+ */
+
+/**
+ * Query error information.
+ *
+ * Returns a string containing a description of the last occurred error or
+ * `null` if there is no error information.
+ *
+ * @function module:fs.proc#error
+ *
+ * @returns {string|null}
+ *
+ * @example
+ * // Trigger error
+ * const fp = popen("command");
+ * fp.close();
+ * fp.close(); // already closed
+ *
+ * // Print error (should yield "Bad file descriptor")
+ * print(fp.error(), "\n");
  */
 
 /**
@@ -518,6 +540,28 @@ uc_fs_popen(uc_vm_t *vm, size_t nargs)
  * handle.fileno();
  *
  * handle.close();
+ *
+ * handle.error();
+ */
+
+/**
+ * Query error information.
+ *
+ * Returns a string containing a description of the last occurred error or
+ * `null` if there is no error information.
+ *
+ * @function module:fs.file#error
+ *
+ * @returns {string|null}
+ *
+ * @example
+ * // Trigger error
+ * const fp = open("file.txt");
+ * fp.close();
+ * fp.close(); // already closed
+ *
+ * // Print error (should yield "Bad file descriptor")
+ * print(fp.error(), "\n");
  */
 
 /**
@@ -645,6 +689,45 @@ uc_fs_write(uc_vm_t *vm, size_t nargs)
 	return uc_fs_write_common(vm, nargs, "fs.file");
 }
 
+/**
+ * Set file read position.
+ *
+ * Set the read position of the open file handle to the given offset and
+ * position.
+ *
+ * Returns `true` if the read position was set.
+ *
+ * Returns `null` if an error occurred.
+ *
+ * @function module:fs.file#seek
+ *
+ * @param {number} [offset=0]
+ * The offset in bytes.
+ *
+ * @param {number} [position=0]
+ * The position of the offset.
+ *
+ * | Position | Description                                                                                  |
+ * |----------|----------------------------------------------------------------------------------------------|
+ * | `0`      | The given offset is relative to the start of the file. This is the default value if omitted. |
+ * | `1`      | The given offset is relative to the current read position.                                   |
+ * | `2`      | The given offset is relative to the end of the file.                                         |
+ *
+ * @returns {boolean|null}
+ *
+ * @example
+ * const fp = open("file.txt", "r");
+ *
+ * print(fp.read(100), "\n");  // read 100 bytes...
+ * fp.seek(0, 0);              // ... and reset position to start of file
+ * print(fp.read(100), "\n");  // ... read same 100 bytes again
+ *
+ * fp.seek(10, 1);  // skip 10 bytes forward, relative to current offset ...
+ * fp.tell();       // ... position is at 110 now
+ *
+ * fp.seek(-10, 2);            // set position to ten bytes before EOF ...
+ * print(fp.read(100), "\n");  // ... reads 10 bytes at most
+ */
 static uc_value_t *
 uc_fs_seek(uc_vm_t *vm, size_t nargs)
 {
@@ -680,6 +763,19 @@ uc_fs_seek(uc_vm_t *vm, size_t nargs)
 	return ucv_boolean_new(true);
 }
 
+/**
+ * Obtain current read position.
+ *
+ * Obtains the current, absolute read position of the open file.
+ *
+ * Returns an integer containing the current read offset in bytes.
+ *
+ * Returns `null` if an error occurred.
+ *
+ * @function module:fs.file#tell
+ *
+ * @returns {number|null}
+ */
 static uc_value_t *
 uc_fs_tell(uc_vm_t *vm, size_t nargs)
 {
@@ -698,6 +794,22 @@ uc_fs_tell(uc_vm_t *vm, size_t nargs)
 	return ucv_int64_new(offset);
 }
 
+/**
+ * Check for TTY.
+ *
+ * Checks whether the open file handle refers to a TTY (terminal) device.
+ *
+ * Returns `true` if the handle refers to a terminal.
+ *
+ * Returns `false` if the handle refers to another kind of file.
+ *
+ * Returns `null` on error.
+ *
+ * @function module:fs.file#isatty
+ *
+ * @returns {boolean|null}
+ *
+ */
 static uc_value_t *
 uc_fs_isatty(uc_vm_t *vm, size_t nargs)
 {
@@ -929,6 +1041,57 @@ uc_fs_fdopen(uc_vm_t *vm, size_t nargs)
 }
 
 
+/**
+ * Represents a handle for interacting with a directory opened by `opendir()`.
+ *
+ * @namespace module:fs.dir
+ * @example
+ *
+ * const handle = opendir(…);
+ *
+ * handle.read();
+ *
+ * handle.tell();
+ * handle.seek(…);
+ *
+ * handle.close();
+ *
+ * handle.error();
+ */
+
+/**
+ * Query error information.
+ *
+ * Returns a string containing a description of the last occurred error or
+ * `null` if there is no error information.
+ *
+ * @function module:fs.dir#error
+ *
+ * @returns {string|null}
+ *
+ * @example
+ * // Trigger error
+ * const fp = opendir("/tmp");
+ * fp.close();
+ * fp.close(); // already closed
+ *
+ * // Print error (should yield "Bad file descriptor")
+ * print(fp.error(), "\n");
+ */
+
+/**
+ * Read the next entry from the open directory.
+ *
+ * Returns a string containing the entry name.
+ *
+ * Returns `null` if there are no more entries to read.
+ *
+ * Returns `null` if an error occurred.
+ *
+ * @function module:fs.dir#read
+ *
+ * @returns {string|null}
+ */
 static uc_value_t *
 uc_fs_readdir(uc_vm_t *vm, size_t nargs)
 {
@@ -947,6 +1110,22 @@ uc_fs_readdir(uc_vm_t *vm, size_t nargs)
 	return ucv_string_new(e->d_name);
 }
 
+/**
+ * Obtain current read position.
+ *
+ * Returns the current read position in the open directory handle which can be
+ * passed back to the `seek()` function to return to this position. This is
+ * mainly useful to read an open directory handle (or specific items) multiple
+ * times.
+ *
+ * Returns an integer referring to the current position.
+ *
+ * Returns `null` if an error occurred.
+ *
+ * @function module:fs.dir#tell
+ *
+ * @returns {number|null}
+ */
 static uc_value_t *
 uc_fs_telldir(uc_vm_t *vm, size_t nargs)
 {
@@ -964,6 +1143,35 @@ uc_fs_telldir(uc_vm_t *vm, size_t nargs)
 	return ucv_int64_new((int64_t)position);
 }
 
+/**
+ * Set read position.
+ *
+ * Sets the read position within the open directory handle to the given offset
+ * value. The offset value should be obtained by a previous call to `tell()` as
+ * the specific integer values are implementation defined.
+ *
+ * Returns `true` if the read position was set.
+ *
+ * Returns `null` if an error occurred.
+ *
+ * @function module:fs.dir#seek
+ *
+ * @param {number} offset
+ * Position value obtained by `tell()`.
+ *
+ * @returns {boolean|null}
+ *
+ * @example
+ *
+ * const handle = opendir("/tmp");
+ * const begin = handle.tell();
+ *
+ * print(handle.read(), "\n");
+ *
+ * handle.seek(begin);
+ *
+ * print(handle.read(), "\n");  // prints the first entry again
+ */
 static uc_value_t *
 uc_fs_seekdir(uc_vm_t *vm, size_t nargs)
 {
@@ -984,6 +1192,19 @@ uc_fs_seekdir(uc_vm_t *vm, size_t nargs)
 	return ucv_boolean_new(true);
 }
 
+/**
+ * Closes the directory handle.
+ *
+ * Closes the underlying file descriptor referring to the opened directory.
+ *
+ * Returns `true` if the handle was properly closed.
+ *
+ * Returns `null` if an error occurred.
+ *
+ * @function module:fs.dir#close
+ *
+ * @returns {boolean|null}
+ */
 static uc_value_t *
 uc_fs_closedir(uc_vm_t *vm, size_t nargs)
 {
@@ -1011,7 +1232,7 @@ uc_fs_closedir(uc_vm_t *vm, size_t nargs)
  * @param {string} path
  * The path to the directory.
  *
- * @returns {Object|null}
+ * @returns {module:fs.dir|null}
  *
  * @example
  * // Open a directory
@@ -1933,7 +2154,7 @@ uc_fs_lsdir(uc_vm_t *vm, size_t nargs)
  * @param {string} [template="/tmp/XXXXXX"]
  * The path template to use when forming the temporary file name.
  *
- * @returns {Object|null}
+ * @returns {module:fs.file|null}
  *
  * @example
  * // Create a unique temporary file in the current working directory
@@ -2325,7 +2546,7 @@ uc_fs_realpath(uc_vm_t *vm, size_t nargs)
  *
  * @function module:fs#pipe
  *
- * @returns {Object[]|null}
+ * @returns {module:fs.file[]|null}
  *
  * @example
  * // Create a pipe