From ffa33c66692c7c539a7ee066627fbe8281aff80a Mon Sep 17 00:00:00 2001
From: Danila Danko <br4ch1st0chr0n3@gmail.com>
Date: Sun, 14 Jan 2024 03:51:55 +0300
Subject: [PATCH] chore: update docs

---
 docs/src/modules_schema.md | 105 +++++++++++++++++++++++++++++++------
 1 file changed, 90 insertions(+), 15 deletions(-)

diff --git a/docs/src/modules_schema.md b/docs/src/modules_schema.md
index 8b9054d3..272a81c6 100644
--- a/docs/src/modules_schema.md
+++ b/docs/src/modules_schema.md
@@ -7,7 +7,7 @@ Add commands to the environment.
 **Type**:
 
 ```console
-list of (submodule)
+list of ((package or string convertible to it) or (list with two elements of types: [ string (package or string convertible to it) ]) or (flatOptions))
 ```
 
 **Default value**:
@@ -37,7 +37,34 @@ list of (submodule)
 
 - [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix)
 
-### `commands.*.package`
+### `commands.*`
+
+A config for a command when the `commands` option is a list.
+
+**Type**:
+
+```console
+(package or string convertible to it) or (list with two elements of types: [ string (package or string convertible to it) ]) or (flatOptions)
+```
+
+**Example value**:
+
+```nix
+[
+  {
+    category = "scripts";
+    package = "black";
+  }
+  [ "[package] print hello" "hello" ]
+  "nodePackages.yarn"
+]
+```
+
+**Declared in**:
+
+- [nix/commands/types.nix](https://github.com/numtide/devshell/tree/main/nix/commands/types.nix)
+
+### `commands.*.package (flatOptions)`
 
 Used to bring in a specific package. This package will be added to the
 environment.
@@ -45,7 +72,7 @@ environment.
 **Type**:
 
 ```console
-null or (package or string convertible to it)
+null or (package or string convertible to it) or package
 ```
 
 **Default value**:
@@ -56,12 +83,12 @@ null
 
 **Declared in**:
 
-- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix)
+- [nix/commands/flatOptions.nix](https://github.com/numtide/devshell/tree/main/nix/commands/flatOptions.nix)
 
-### `commands.*.category`
+### `commands.*.category (flatOptions)`
 
-Set a free text category under which this command is grouped
-and shown in the help menu.
+Sets a free text category under which this command is grouped
+and shown in the devshell menu.
 
 **Type**:
 
@@ -77,9 +104,9 @@ string
 
 **Declared in**:
 
-- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix)
+- [nix/commands/flatOptions.nix](https://github.com/numtide/devshell/tree/main/nix/commands/flatOptions.nix)
 
-### `commands.*.command`
+### `commands.*.command (flatOptions)`
 
 If defined, it will add a script with the name of the command, and the
 content of this value.
@@ -110,9 +137,33 @@ null
 
 **Declared in**:
 
-- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix)
+- [nix/commands/flatOptions.nix](https://github.com/numtide/devshell/tree/main/nix/commands/flatOptions.nix)
+
+### `commands.*.expose (flatOptions)`
 
-### `commands.*.help`
+When `true`, the `command (flatOptions)`
+or the `package (flatOptions)` will be added to the environment.
+  
+Otherwise, they will not be added to the environment, but will be printed
+in the devshell menu.
+
+**Type**:
+
+```console
+boolean
+```
+
+**Default value**:
+
+```nix
+true
+```
+
+**Declared in**:
+
+- [nix/commands/flatOptions.nix](https://github.com/numtide/devshell/tree/main/nix/commands/flatOptions.nix)
+
+### `commands.*.help (flatOptions)`
 
 Describes what the command does in one line of text.
 
@@ -130,11 +181,15 @@ null
 
 **Declared in**:
 
-- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix)
+- [nix/commands/flatOptions.nix](https://github.com/numtide/devshell/tree/main/nix/commands/flatOptions.nix)
+
+### `commands.*.name (flatOptions)`
+
+Name of this command. 
 
-### `commands.*.name`
+Defaults to a `package (flatOptions)` name or pname if present.
 
-Name of this command. Defaults to attribute name in commands.
+The value of this option is required for a `command (flatOptions)`.
 
 **Type**:
 
@@ -150,7 +205,27 @@ null
 
 **Declared in**:
 
-- [modules/commands.nix](https://github.com/numtide/devshell/tree/main/modules/commands.nix)
+- [nix/commands/flatOptions.nix](https://github.com/numtide/devshell/tree/main/nix/commands/flatOptions.nix)
+
+### `commands.*.prefix (flatOptions)`
+
+Prefix of the command name in the devshell menu.
+
+**Type**:
+
+```console
+string
+```
+
+**Default value**:
+
+```nix
+""
+```
+
+**Declared in**:
+
+- [nix/commands/flatOptions.nix](https://github.com/numtide/devshell/tree/main/nix/commands/flatOptions.nix)
 
 ### `devshell.packages`