update generated docs and yavascript.d.ts

Author: suchipi

meta/generated-docs/ChildProcess.md

@@ -25,7 +25,16 @@
 
 # ChildProcess (interface)
 
-A class which represents a child process. The process may or may not be running.
+A class which represents a child process. The process may or may not be
+running.
+
+This class is the API used internally by the [exec](/meta/generated-docs/exec.md#exec-interface) function to spawn child
+processes.
+
+Generally, you should not need to use the `ChildProcess` class directly, and
+should use [exec](/meta/generated-docs/exec.md#exec-interface) or [$](/meta/generated-docs/exec.md#-function) instead. However, you may need to use it in some
+special cases, like when specifying custom stdio for a process, or spawning a
+non-blocking long-running process.
 
 ```ts
 declare interface ChildProcess {

meta/generated-docs/README.md

@@ -281,3 +281,10 @@ For convenience, two builtin modules from QuickJS are also available as globals.
 [`Number.MAX_VALUE`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_VALUE
 [`Number.EPSILON`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/EPSILON
 [`BigFloatEnv.RNDNA`]: /meta/generated-docs/quickjs-extensions.md#bigfloatenvconstructorrndna-bigfloatroundingmode-property
+[`console.log`]: /meta/generated-docs/console.md#consolelog-method
+[`console.clear`]: /meta/generated-docs/console.md#consoleclear-method
+[`console.info`]: /meta/generated-docs/console.md#consoleinfo-method
+[`console.error`]: /meta/generated-docs/console.md#consoleerror-method
+[`console.warn`]: /meta/generated-docs/console.md#consolewarn-method
+[`BaseExecOptions`]: /meta/generated-docs/exec.md#baseexecoptions-type
+[`Path.normalize`]: /meta/generated-docs/path.md#pathnormalize-static-method

meta/generated-docs/assert.md

@@ -33,9 +33,11 @@ Throws an error if `value` is not truthy.
 
 ## assert.type (function property)
 
-Throws an error if `value` is not of the type `type`.
+Throws an error if its argument isn't the correct type.
 
-`type` should be either a [TypeValidator](/meta/generated-docs/types.md#typevalidator-type), or a value which can be coerced into one via [types.coerce](/meta/generated-docs/types.md#typescoerce-function-property).
+- `@param` _value_ — The value to test the type of
+- `@param` _type_ — The type that `value` should be, as either a `TypeValidator` (from the `types.*` namespace) or a value which can be coerced into a `TypeValidator` via the `types.coerce` function, like `String`, `Boolean`, etc.
+- `@param` _message_ — An optional error message to use. If unspecified, a generic-but-descriptive message will be used.
 
 ```ts
 type: <T extends TypeValidator<any> | CoerceableToTypeValidator>(value: any, type: T, optionalMessage?: string) => asserts value is UnwrapTypeFromCoerceableOrValidator<T>;

meta/generated-docs/basename.md

@@ -6,6 +6,8 @@ Return the last component of a path string.
 
 Provides the same functionality as the unix binary of the same name.
 
+> Example: `basename("/home/suchipi/something")` returns `"something"`, the last part.
+
 ```ts
 declare function basename(path: string | Path): string;
 ```

meta/generated-docs/cat.md

@@ -9,6 +9,12 @@
 Reads the contents of one or more files from disk as either one UTF-8 string
 or one ArrayBuffer.
 
+Provides the same functionality as the unix binary of the same name.
+
+> Example: If you have a file called `hi.txt` in the current working
+> directory, and it contains the text "hello", running `cat("hi.txt")`
+> returns `"hello"`.
+
 ```ts
 const cat: {
   (paths: string | Path | Array<string | Path>): string;

meta/generated-docs/cd.md

@@ -2,7 +2,7 @@
 
 # cd (function)
 
-Change the process's current working directory to the specified path. If no
+Changes the process's current working directory to the specified path. If no
 path is specified, moves to the user's home directory.
 
 Provides the same functionality as the shell builtin of the same name.

meta/generated-docs/chmod.md

@@ -1,6 +1,75 @@
+- [chmod (function)](#chmod-function)
 - [ChmodPermissionsWho (type)](#chmodpermissionswho-type)
 - [ChmodPermissionsWhat (type)](#chmodpermissionswhat-type)
-- [chmod (function)](#chmod-function)
+
+# chmod (function)
+
+Set the permission bits for the specified file.
+
+- `@param` _permissions_ — The permission bits to set. This can be a number, a string
+  containing an octal number, or an object.
+- `@param` _path_ — The path to the file.
+
+Provides the same functionality as the unix binary of the same name.
+
+The `permissions` argument can be either:
+
+- a number (best expressed using octal, eg `0o655`)
+- a string (which will be interpreted as an octal number, eg `'777'`)
+- or an object (see below).
+
+> NOTE: At this time there are no "add"/"remove" semantics; the existing
+> permissions will be completely overwritten with your specified permissions.
+> This will be changed later as this is not intuitive.
+
+When permissions is an object, each of the object's own properties' keys must
+be one of these strings:
+
+- `"user"`
+- `"group"`
+- `"others"`
+- `"all"` (meaning "user", "group", and "others")
+- `"u"` (alias for "user")
+- `"g"` (alias for "group")
+- `"o"` (alias for "others")
+- `"a"` (alias for "all")
+- `"ug"` ("user" plus "group")
+- `"go"` ("group" plus "others")
+- `"uo"` ("user" plus "others")
+
+and their values must be one of these strings:
+
+- `"read"` (permission to read the contents of the file)
+- `"write"` (permission to write to the file's contents)
+- `"execute"` (permission to run the file as an executable)
+- `"readwrite"` (both "read" and "write")
+- `"none"` (no permissions)
+- `"full"` ("read", "write", and "execute")
+- `"r"` (alias for "read")
+- `"w"` (alias for "write")
+- `"x"` (alias for "execute")
+- `"rw"` (alias for "readwrite")
+- `"rx"` ("read" and "execute")
+- `"wx"` ("write" and "execute")
+- `"rwx"` (alias for "full")
+
+Some example objects:
+
+```ts
+chmod({ user: "readwrite", group: "read", others: "none" });
+chmod({ ug: "rw", o: "w" });
+chmod({ all: "full" });
+```
+
+```ts
+declare function chmod(
+  permissions:
+    | number
+    | string
+    | Record<ChmodPermissionsWho, ChmodPermissionsWhat>,
+  path: string | Path
+): void;
+```
 
 # ChmodPermissionsWho (type)
 
@@ -41,20 +110,3 @@ declare type ChmodPermissionsWhat =
   | "wx"
   | "rwx";
 ```
-
-# chmod (function)
-
-Set the permission bits for the specified file.
-
-- `@param` _permissions_ — The permission bits to set. This can be a number, a string containing an octal number, or an object.
-- `@param` _path_ — The path to the file.
-
-```ts
-declare function chmod(
-  permissions:
-    | number
-    | string
-    | Record<ChmodPermissionsWho, ChmodPermissionsWhat>,
-  path: string | Path
-): void;
-```

meta/generated-docs/console.md

@@ -9,7 +9,10 @@
 
 # clear (function)
 
-Clear the contents and scrollback buffer of the tty by printing special characters into stdout.
+Prints special ANSI escape characters to stdout which instruct your terminal
+emulator to clear the screen and clear your terminal scrollback.
+
+Identical to [console.clear](/meta/generated-docs/console.md#consoleclear-method).
 
 ```ts
 declare function clear(): void;
@@ -29,39 +32,68 @@ interface Console {
 
 ## Console.log (method)
 
-Writes to stdout, with newline appended.
+Logs its arguments to stdout, with a newline appended.
+
+Any value can be logged, not just strings. Non-string values will be
+formatted using [inspect](/meta/generated-docs/inspect.md#inspect-inspectfunction).
+
+Functionally identical to [console.info](/meta/generated-docs/console.md#consoleinfo-method), [echo](/meta/generated-docs/echo.md#echo-value), and
+[print](/meta/generated-docs/print.md#print-function). Contrast with [console.error](/meta/generated-docs/console.md#consoleerror-method), which prints to stderr
+instead of stdout.
 
 ```ts
 log(message?: any, ...optionalParams: any[]): void;
 ```
 
 ## Console.info (method)
 
-Writes to stdout, with newline appended.
+Logs its arguments to stdout, with a newline appended.
+
+Any value can be logged, not just strings. Non-string values will be
+formatted using [inspect](/meta/generated-docs/inspect.md#inspect-inspectfunction).
+
+Functionally identical to [console.log](/meta/generated-docs/console.md#consolelog-method), [echo](/meta/generated-docs/echo.md#echo-value), and
+[print](/meta/generated-docs/print.md#print-function). Contrast with [console.error](/meta/generated-docs/console.md#consoleerror-method), which prints to stderr
+instead of stdout.
 
 ```ts
 info(message?: any, ...optionalParams: any[]): void;
 ```
 
 ## Console.warn (method)
 
-Writes to stderr, with newline appended.
+Logs its arguments to stderr, with a newline appended.
+
+Any value can be logged, not just strings. Non-string values will be
+formatted using [inspect](/meta/generated-docs/inspect.md#inspect-inspectfunction).
+
+Functionally identical to [console.error](/meta/generated-docs/console.md#consoleerror-method). Contrast with
+[console.log](/meta/generated-docs/console.md#consolelog-method), which prints to stdout instead of stderr.
 
 ```ts
 warn(message?: any, ...optionalParams: any[]): void;
 ```
 
 ## Console.error (method)
 
-Writes to stderr, with newline appended.
+Logs its arguments to stderr, with a newline appended.
+
+Any value can be logged, not just strings. Non-string values will be
+formatted using [inspect](/meta/generated-docs/inspect.md#inspect-inspectfunction).
+
+Functionally identical to [console.warn](/meta/generated-docs/console.md#consolewarn-method). Contrast with
+[console.log](/meta/generated-docs/console.md#consolelog-method), which prints to stdout instead of stderr.
 
 ```ts
 error(message?: any, ...optionalParams: any[]): void;
 ```
 
 ## Console.clear (method)
 
-Same as [clear](/meta/generated-docs/console.md#clear-function)().
+Prints special ANSI escape characters to stdout which instruct your terminal
+emulator to clear the screen and clear your terminal scrollback.
+
+Identical to [clear](/meta/generated-docs/console.md#clear-function).
 
 ```ts
 clear(): void;

meta/generated-docs/csv.md

@@ -4,6 +4,17 @@
 
 # CSV (object)
 
+Serializes or deserializes CSV data.
+
+The `CSV` object contains a `parse` function and a `stringify` function which
+can be used to parse strings of CSV (comma-separated values) data into
+arrays-of-arrays-of-strings and serialize arrays-of-arrays-of-strings into
+strings of CSV data.
+
+Its interface is similar to `JSON.parse` and `JSON.stringify`, but CSV does
+not support the spacing/replacer/reviver options that `JSON.parse` and
+`JSON.stringify` have.
+
 ```ts
 const CSV: {
   parse(input: string): Array<Array<string>>;

meta/generated-docs/dirname.md

@@ -6,6 +6,9 @@ Removes the final component from a path string.
 
 Provides the same functionality as the unix binary of the same name.
 
+> Example: `dirname("/home/suchipi/something")` returns
+> `"/home/suchipi"`, everything except the last part.
+
 ```ts
 declare function dirname(path: string | Path): Path;
 ```