You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/README.md
+25-8Lines changed: 25 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -251,25 +251,42 @@ You, as the writer of documentation, are still in charge of its content.
251
251
For example:
252
252
253
253
```markdown
254
-
# pkgs.coolFunction
254
+
# pkgs.coolFunction {#pkgs.coolFunction}
255
255
256
-
Description of what `coolFunction` does.
256
+
`pkgs.coolFunction` *`name`* *`config`*
257
257
258
-
## Inputs
258
+
Description of what `callPackage` does.
259
259
260
-
`coolFunction` expects a single argument which should be an attribute set, with the following possible attributes:
261
260
262
-
`name` (String)
261
+
## Inputs {#pkgs-coolFunction-inputs}
262
+
263
+
If something's special about `coolFunction`'s general argument handling, you can say so here.
264
+
Otherwise, just describe the single argument or start the arguments' definition list without introduction.
265
+
266
+
*`name`* (String)
263
267
264
268
: The name of the resulting image.
265
269
266
-
`tag` (String; _optional_)
270
+
*`config`* (Attribute set)
271
+
272
+
: Introduce the parameter. Maybe you have a test to make sure `{ }` is a sensible default; then you can say: these attributes are optional; `{ }` is a valid argument.
267
273
268
-
: Tag of the generated image.
274
+
`outputHash` (String; _optional_)
269
275
270
-
_Default:_ the output path's hash.
276
+
: A brief explanation including when and when not to pass this attribute.
277
+
278
+
: _Default:_ the output path's hash.
271
279
```
272
280
281
+
Checklist:
282
+
- Start with a synopsis, to show the order of positional arguments.
283
+
- Metavariables are in emphasized code spans: ``` *`arg1`* ```. Metavariables are placeholders where users may write arbitrary expressions. This includes positional arguments.
284
+
- Attribute names are regular code spans: ``` `attr1` ```. These identifiers can _not_ be picked freely by users, so they are _not_ metavariables.
285
+
-_optional_ attributes have a _`Default:`_ if it's easily described as a value.
286
+
-_optional_ attributes have a _`Default behavior:`_ if it's not easily described using a value.
287
+
- Nix types aren't in code spans, because they are not code
288
+
- Nix types are capitalized, to distinguish them from the camelCase [Module System](#module-system) types, which _are_ code and behave like functions.
289
+
273
290
#### Examples
274
291
275
292
To define a referenceable figure use the following fencing:
0 commit comments