docs: update docs

socketsupply · Oct 3, 2023 · f97f0b6 · f97f0b6
1 parent 753edb9
commit f97f0b6
Show file tree

Hide file tree

Showing 12 changed files with 211 additions and 125 deletions.
diff --git a/api/README.md b/api/README.md
diff --git a/api/crypto.js b/api/crypto.js
@@ -22,7 +22,7 @@ import * as exports from './crypto.js'
 
 /**
  * WebCrypto API
- * @see {https://developer.mozilla.org/en-US/docs/Web/API/Crypto}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Crypto}
  */
 export let webcrypto = globalThis.crypto?.webcrypto ?? globalThis.crypto
 
@@ -57,8 +57,8 @@ export const ready = Promise.all(pending)
 
 /**
  * libsodium API
- * @see {https://doc.libsodium.org/}
- * @see {https://github.com/jedisct1/libsodium.js}
+ * @see {@link https://doc.libsodium.org/}
+ * @see {@link https://github.com/jedisct1/libsodium.js}
  */
 export { sodium }
 
@@ -87,6 +87,10 @@ export function getRandomValues (buffer, ...args) {
 // so this is re-used instead of creating new one each rand64() call
 const tmp = new Uint32Array(2)
 
+/**
+ * Generate a random 64-bit number.
+ * @returns {BigInt} - A random 64-bit number.
+ */
 export function rand64 () {
   getRandomValues(tmp)
   return (BigInt(tmp[0]) << 32n) | BigInt(tmp[1])

diff --git a/api/errors.js b/api/errors.js
@@ -20,7 +20,7 @@ export const TIMEOUT_ERR = 23
 export class AbortError extends Error {
   /**
    * The code given to an `ABORT_ERR` `DOMException`
-   * @see {https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
    */
   static get code () { return ABORT_ERR }
 
@@ -268,7 +268,7 @@ export class InternalError extends Error {
 export class InvalidAccessError extends Error {
   /**
    * The code given to an `INVALID_ACCESS_ERR` `DOMException`
-   * @see {https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
    */
   static get code () { return INVALID_ACCESS_ERR }
 
@@ -301,7 +301,7 @@ export class InvalidAccessError extends Error {
 export class NetworkError extends Error {
   /**
    * The code given to an `NETWORK_ERR` `DOMException`
-   * @see {https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
    */
   static get code () { return NETWORK_ERR }
 
@@ -336,7 +336,7 @@ export class NetworkError extends Error {
 export class NotAllowedError extends Error {
   /**
    * The code given to an `NOT_ALLOWED_ERR` `DOMException`
-   * @see {https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
    */
   static get code () { return NOT_ALLOWED_ERR }
 
@@ -369,7 +369,7 @@ export class NotAllowedError extends Error {
 export class NotFoundError extends Error {
   /**
    * The code given to an `NOT_FOUND_ERR` `DOMException`
-   * @see {https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
    */
   static get code () { return NOT_FOUND_ERR }
 
@@ -402,7 +402,7 @@ export class NotFoundError extends Error {
 export class NotSupportedError extends Error {
   /**
    * The code given to an `NOT_SUPPORTED_ERR` `DOMException`
-   * @see {https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
    */
   static get code () { return NOT_SUPPORTED_ERR }
 
@@ -494,7 +494,7 @@ export class OperationError extends Error {
 export class TimeoutError extends Error {
   /**
    * The code given to an `TIMEOUT_ERR` `DOMException`
-   * @see {https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMException}
    */
   static get code () { return TIMEOUT_ERR }
 

diff --git a/api/fs/dir.js b/api/fs/dir.js
@@ -37,7 +37,7 @@ export function sortDirectoryEntries (a, b) {
  * A containerr for a directory and its entries. This class supports scanning
  * a directory entry by entry with a `read()` method. The `Symbol.asyncIterator`
  * interface is exposed along with an AsyncGenerator `entries()` method.
- * @see {https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#class-fsdir}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#class-fsdir}
  */
 export class Dir {
   static from (fdOrHandle, options) {
@@ -179,7 +179,7 @@ export class Dir {
 
 /**
  * A container for a directory entry.
- * @see {https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#class-fsdirent}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#class-fsdirent}
  */
 export class Dirent {
   static get UNKNOWN () { return UV_DIRENT_UNKNOWN }

diff --git a/api/fs/handle.js b/api/fs/handle.js
@@ -43,7 +43,7 @@ export const kClosed = Symbol.for('fs.FileHandle.closed')
 /**
  * A container for a descriptor tracked in `fds` and opened in the native layer.
  * This class implements the Node.js `FileHandle` interface
- * @see {https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#class-filehandle}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#class-filehandle}
  */
 export class FileHandle extends EventEmitter {
   static get DEFAULT_ACCESS_MODE () { return F_OK }
@@ -109,7 +109,7 @@ export class FileHandle extends EventEmitter {
 
   /**
    * Asynchronously open a file.
-   * @see {https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fspromisesopenpath-flags-mode}
+   * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fspromisesopenpath-flags-mode}
    * @param {string | Buffer | URL} path
    * @param {string=} [flags = 'r']
    * @param {string=} [mode = 0o666]

diff --git a/api/fs/index.js b/api/fs/index.js
@@ -76,7 +76,7 @@ async function visit (path, options, callback) {
 /**
  * Asynchronously check access a file for a given mode calling `callback`
  * upon success or error.
- * @see {@link https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fsopenpath-flags-mode-callback}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fsopenpath-flags-mode-callback}
  * @param {string | Buffer | URL} path
  * @param {string?|function(Error?)?} [mode = F_OK(0)]
  * @param {function(Error?)?} [callback]
@@ -159,7 +159,7 @@ export function chown (path, uid, gid, callback) {
 
 /**
  * Asynchronously close a file descriptor calling `callback` upon success or error.
- * @see {https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fsclosefd-callback}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fsclosefd-callback}
  * @param {number} fd
  * @param {function(Error?)?} [callback]
  */
@@ -179,6 +179,14 @@ export function close (fd, callback) {
   }
 }
 
+/**
+ * Asynchronously copies `src` to `dest` calling `callback` upon success or error.
+ * @param {string} src - The source file path.
+ * @param {string} dest - The destination file path.
+ * @param {number} flags - Modifiers for copy operation.
+ * @param {function(Error=)=} [callback] - The function to call after completion.
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fscopyfilesrc-dest-mode-callback}
+ */
 export function copyFile (src, dest, flags, callback) {
   if (typeof src !== 'string') {
     throw new TypeError('The argument \'src\' must be a string')
@@ -202,7 +210,7 @@ export function copyFile (src, dest, flags, callback) {
 }
 
 /**
- * @see {@link https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fscreatewritestreampath-options}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fscreatewritestreampath-options}
  * @param {string | Buffer | URL} path
  * @param {object?} [options]
  * @returns {ReadStream}
@@ -242,7 +250,7 @@ export function createReadStream (path, options) {
 }
 
 /**
- * @see {@link https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fscreatewritestreampath-options}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fscreatewritestreampath-options}
  * @param {string | Buffer | URL} path
  * @param {object?} [options]
  * @returns {WriteStream}
@@ -285,7 +293,7 @@ export function createWriteStream (path, options) {
  * Invokes the callback with the <fs.Stats> for the file descriptor. See
  * the POSIX fstat(2) documentation for more detail.
  *
- * @see {@link https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fsfstatfd-options-callback}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fsfstatfd-options-callback}
  *
  * @param {number} fd - A file descriptor.
  * @param {object?|function?} [options] - An options object.
@@ -389,7 +397,7 @@ export function mkdir (path, options, callback) {
 
 /**
  * Asynchronously open a file calling `callback` upon success or error.
- * @see {https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fsopenpath-flags-mode-callback}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fsopenpath-flags-mode-callback}
  * @param {string | Buffer | URL} path
  * @param {string?} [flags = 'r']
  * @param {string?} [mode = 0o666]
@@ -442,7 +450,7 @@ export function open (path, flags = 'r', mode = 0o666, options = null, callback)
 
 /**
  * Asynchronously open a directory calling `callback` upon success or error.
- * @see {https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fsreaddirpath-options-callback}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fsreaddirpath-options-callback}
  * @param {string | Buffer | URL} path
  * @param {object?|function(Error?, Dir?)} [options]
  * @param {string?} [options.encoding = 'utf8']
@@ -467,7 +475,7 @@ export function opendir (path, options = {}, callback) {
 
 /**
  * Asynchronously read from an open file descriptor.
- * @see {https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fsreadfd-buffer-offset-length-position-callback}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fsreadfd-buffer-offset-length-position-callback}
  * @param {number} fd
  * @param {object | Buffer | TypedArray} buffer - The buffer that the data will be written to.
  * @param {number} offset - The position in buffer to write the data to.
@@ -502,7 +510,7 @@ export function read (fd, buffer, offset, length, position, options, callback) {
 
 /**
  * Asynchronously read all entries in a directory.
- * @see {https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fsreaddirpath-options-callback}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fsreaddirpath-options-callback}
  * @param {string | Buffer | URL } path
  * @param {object?|function(Error?, object[])} [options]
  * @param {string?} [options.encoding ? 'utf8']
@@ -765,7 +773,7 @@ export function unlink (path, callback) {
 }
 
 /**
- * @see {@url https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fswritefilefile-data-options-callback}
+ * @see {@url https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fswritefilefile-data-options-callback}
  * @param {string | Buffer | URL | number } path - filename or file descriptor
  * @param {string | Buffer | TypedArray | DataView | object } data
  * @param {object?} options

diff --git a/api/fs/promises.js b/api/fs/promises.js
@@ -78,7 +78,7 @@ async function visit (path, options, callback) {
 
 /**
  * Asynchronously check access a file.
- * @see {@link https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fspromisesaccesspath-mode}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fspromisesaccesspath-mode}
  * @param {string | Buffer | URL} path
  * @param {string?} [mode]
  * @param {object?} [options]
@@ -251,7 +251,7 @@ export async function opendir (path, options) {
 }
 
 /**
- * @see {@link https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fspromisesreaddirpath-options}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fspromisesreaddirpath-options}
  * @param {string | Buffer | URL} path
  * @param {object?} options
  * @param {string?} [options.encoding = 'utf8']
@@ -282,7 +282,7 @@ export async function readdir (path, options) {
 }
 
 /**
- * @see {@link https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fspromisesreadfilepath-options}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fspromisesreadfilepath-options}
  * @param {string} path
  * @param {object?} [options]
  * @param {(string|null)?} [options.encoding = null]
@@ -432,7 +432,7 @@ export async function unlink (path) {
 }
 
 /**
- * @see {@link https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fspromiseswritefilefile-data-options}
+ * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fspromiseswritefilefile-data-options}
  * @param {string | Buffer | URL | FileHandle} path - filename or FileHandle
  * @param {string|Buffer|Array|DataView|TypedArray} data
  * @param {object?} [options]