Skip to content

Commit 2a8d751

Browse files
deempdeemp
committed
refactor: descriptions
1 parent 83f233b commit 2a8d751

File tree

2 files changed

+65
-57
lines changed

2 files changed

+65
-57
lines changed

‎nix/commands/flatOptions.nix‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{ lib, strOrPackage, flatOptionsType }:
22
with lib;
3+
let flat = name: "`${name} (${flatOptionsType.name})`"; in
34
# These are all the options available for the commands.
45
{
56
prefix = mkOption {
@@ -14,11 +15,11 @@ with lib;
1415
type = types.nullOr types.str;
1516
default = null;
1617
description = ''
17-
Name of this command.
18+
Name of the command.
1819
19-
Defaults to a `package (${flatOptionsType.name})` name or pname if present.
20+
Defaults to a ${flat "package"} name or pname if present.
2021
21-
The value of this option is required for a `command (${flatOptionsType.name})`.
22+
The value of this option is required for ${flat "command"}.
2223
'';
2324
};
2425

@@ -68,11 +69,12 @@ with lib;
6869
type = types.bool;
6970
default = true;
7071
description = ''
71-
When `true`, the `command (${flatOptionsType.name})`
72-
or the `package (${flatOptionsType.name})` will be added to the environment.
72+
When `true`, ${flat "command"}
73+
or ${flat "package"} will be added to the environment.
7374
7475
Otherwise, they will not be added to the environment, but will be printed
7576
in the devshell menu.
7677
'';
78+
example = true;
7779
};
7880
}

‎nix/commands/nestedOptions.nix‎

Lines changed: 58 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,19 @@
88
, maxDepth
99
}:
1010
with pkgs.lib;
11+
let
12+
flat = name: "`${name} (${flatOptionsType.name})`";
13+
nested = name: "`${name} (${nestedOptionsType.name})`";
14+
in
1115
{
1216
prefix = mkOption {
1317
type = types.nullOr types.str;
1418
default = "";
1519
description = ''
16-
Possible `(${flatOptionsType.name}) prefix`.
20+
Can be used as ${flat "prefix"} for all
21+
${nested "packages"} and ${nested "commands"}.
1722
18-
Priority of this option when selecting a prefix: `1`.
23+
Priority of this option when selecting a ${flat "prefix"}: `1`.
1924
2025
Lowest priority: `1`.
2126
'';
@@ -30,10 +35,11 @@ with pkgs.lib;
3035
type = types.nullOr (attrsNestedOf types.str);
3136
default = { };
3237
description = ''
33-
A leaf value becomes a `(${flatOptionsType.name}) prefix`
34-
of a `package` (`command`) with a matching path in `packages` (`commands`).
38+
A leaf value becomes ${flat "prefix"}
39+
of ${flat "package"} or ${flat "command"}
40+
with a matching path in ${nested "packages"} or ${nested "commands"}.
3541
36-
Priority of this option when selecting a prefix: `2`.
42+
Priority of this option when selecting a ${flat "prefix"}: `2`.
3743
3844
Lowest priority: `1`.
3945
'';
@@ -54,38 +60,35 @@ with pkgs.lib;
5460
]));
5561
default = { };
5662
description = ''
57-
A nested (max depth is ${toString maxDepth}) attrset of `(${flatOptionsType.name}) package`-s
58-
to describe in the devshell menu
59-
and optionally bring to the environment.
63+
A leaf value:
6064
61-
A path to a leaf value is concatenated via `.`
62-
and used as a `(${flatOptionsType.name}) name`.
63-
64-
A leaf value can be of three types.
65-
6665
1. When a `string` with a value `<string>`,
6766
devshell tries to resolve a derivation
68-
`pkgs.<string>` and use it as a `(${flatOptionsType.name}) package`.
67+
`pkgs.<string>` and use it as ${flat "package"}.
6968
70-
2. When a `derivation`, it's used as a `(${flatOptionsType.name}) package`.
69+
2. When a `derivation`, it's used as ${flat "package"}.
7170
7271
3. When a list with two elements:
7372
1. The first element is a `string`
74-
that is used to select a `(${flatOptionsType.name}) help`.
75-
- Priority of this `string` (if present) when selecting a `(${flatOptionsType.name}) help`: `4`.
73+
that is used to select ${flat "help"}.
74+
75+
Priority of this `string` (if present) when selecting ${flat "help"}: `4`.
7676
77-
Lowest priority: `1`.
77+
Lowest priority: `1`.
7878
2. The second element is interpreted as if
7979
the leaf value were initially a `string` or a `derivation`.
80-
81-
Priority of `package.meta.description` (if present in the resolved `(${flatOptionsType.name}) package`)
82-
when selecting a `(${flatOptionsType.name}) help`: 2
80+
81+
A path to a leaf value is concatenated via `.`
82+
and used as ${flat "name"}.
83+
84+
Priority of `package.meta.description` (if present in the resolved ${flat "package"})
85+
when selecting ${flat "help"}: `2`
8386
8487
Lowest priority: `1`.
8588
86-
A user may prefer not to bring the environment some of the packages.
89+
A user may prefer to not bring to the environment some of the packages.
8790
88-
Priority of `expose = false` when selecting a `(${flatOptionsType.name}) expose`: `1`.
91+
Priority of `expose = false` when selecting ${flat "expose"}: `1`.
8992
9093
Lowest priority: `1`.
9194
'';
@@ -104,34 +107,33 @@ with pkgs.lib;
104107
pairHelpCommandType
105108
]));
106109
default = { };
107-
description = ''
108-
A nested (max depth is ${toString maxDepth}) attrset of `(${flatOptionsType.name}) command`-s
109-
to describe in the devshell menu
110-
and bring to the environment.
110+
description = ''
111+
A leaf value:
111112
112-
A path to a leaf value is concatenated via `.`
113-
and used in the `(${flatOptionsType.name}) name`.
114-
115-
A leaf value can be of two types.
116-
117-
1. When a `string`, it's used as a `(${flatOptionsType.name}) command`.
113+
1. When a `string`, it's used as ${flat "command"}.
118114
119115
2. When a list with two elements:
120-
1. the first element of type `string` with a value `<string>`
121-
that is used to select a `help`;
116+
1. The first element of type `string` with a value `<string>`
117+
is used to select ${flat "help"}.
122118
123-
Priority of the `<string>` (if present) when selecting a `(${flatOptionsType.name}) help`: `4`
119+
Priority of the `<string>` (if present) when selecting ${flat "help"}: `4`
124120
125121
Lowest priority: `1`.
126-
1. the second element of type `string` is used as a `(${flatOptionsType.name}) command`.
122+
1. The second element of type `string` is used as ${flat "command"}.
123+
124+
A path to the leaf value is concatenated via `.`
125+
and used as ${flat "name"}.
127126
'';
128127
};
129128

130129
help = mkOption {
131130
type = types.nullOr types.str;
132131
default = "";
133132
description = ''
134-
Priority of this option when selecting a `(${flatOptionsType.name}) help`: `1`.
133+
Can be used as ${flat "hel"} for all
134+
${nested "packages"} and ${nested "commands"}.
135+
136+
Priority of this option when selecting a ${flat "help"}: `1`.
135137
136138
Lowest priority: `1`.
137139
'';
@@ -146,11 +148,11 @@ with pkgs.lib;
146148
type = types.nullOr (attrsNestedOf types.str);
147149
default = { };
148150
description = ''
149-
A leaf value can be used as `(${flatOptionsType.name}) help`
150-
for a `(${flatOptionsType.name}) package` (`(${flatOptionsType.name}) command`)
151-
with a matching path in `(${nestedOptionsType.name}) packages` (`(${nestedOptionsType.name}) commands`).
151+
A leaf value can be used as ${flat "help"}
152+
for ${flat "package"} or ${flat "command"}
153+
with a matching path in ${nested "packages"} or ${nested "commands"}.
152154
153-
Priority of this option when selecting a `(${flatOptionsType.name}) help`: `3`.
155+
Priority of this option when selecting ${flat "help"}: `3`.
154156
155157
Lowest priority: `1`.
156158
'';
@@ -166,12 +168,14 @@ with pkgs.lib;
166168
type = types.nullOr types.bool;
167169
default = false;
168170
description = ''
169-
When `true`, all `packages` can be added to the environment.
171+
Can be used as ${flat "expose"} for all
172+
${nested "packages"} and ${nested "commands"}.
170173
171-
Otherwise, they can not be added to the environment,
172-
but will be printed in the devshell description.
174+
Priority of this option when selecting ${flat "expose"}: `2`.
173175
174-
Priority of this option when selecting a `(${flatOptionsType.name}) expose`: `2`.
176+
When selecting ${flat "expose"} for
177+
- ${flat "package"}, priority of `false`: `1`.
178+
- ${flat "command"}, priority of `true`: `1`.
175179
176180
Lowest priority: `1`.
177181
'';
@@ -186,14 +190,16 @@ with pkgs.lib;
186190
type = types.nullOr (attrsNestedOf types.bool);
187191
default = { };
188192
description = ''
189-
A nested (max depth is ${toString maxDepth}) attrset of `(${flatOptionsType.name}) expose`-s.
190-
191-
A leaf value can be used as `(${flatOptionsType.name}) expose`
192-
for a `(${flatOptionsType.name}) package` (`(${flatOptionsType.name}) command`)
193-
with a matching path in `(${nestedOptionsType.name}) packages` (`(${nestedOptionsType.name}) commands`).
193+
A leaf value can be used as ${flat "expose"}
194+
for ${flat "package"} or ${flat "command"}
195+
with a matching path in ${nested "packages"} or ${nested "commands"}.
194196
195-
Priority of this option when selecting a `(${flatOptionsType.name}) expose`: `3`.
197+
Priority of this option when selecting ${flat "expose"}: `3`.
196198
199+
When selecting ${flat "expose"} for
200+
- ${flat "package"}, priority of `false`: `1`.
201+
- ${flat "command"}, priority of `true`: `1`.
202+
197203
Lowest priority: `1`.
198204
'';
199205
example = literalExpression ''

0 commit comments

Comments
 (0)