Documenting REPLs, Inputs/Outputs, and Function Arguments

``` ### REPLs When showing inputs/outputs of any [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), such as a shell or the Nix REPL, use a format as you'd see in the REPL, while trying to visually separate inputs from outputs. This means that for a shell, you should use a format like the following: ```shell $ nix-build -A hello '<nixpkgs>' \ --option require-sigs false \ --option trusted-substituters file:///tmp/hello-cache \ --option substituters file:///tmp/hello-cache /nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1 ``` Note how the input is preceded by `$` on the first line and indented on subsequent lines, and how the output is provided as you'd see on the shell. For the Nix REPL, you should use a format like the following: ```shell nix-repl> builtins.attrNames { a = 1; b = 2; } [ "a" "b" ] ``` Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL. ### Headings for inputs, outputs and examples When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples. Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation. The purpose of this convention is to provide a familiar structure for navigating the manual, so any reader can expect to find content related to inputs in an "inputs" heading, examples in an "examples" heading, and so on. An example: ``` ## buildImage Some explanation about the function here. Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it. ### Inputs Documentation for the inputs of `buildImage`. Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it. ### Passthru outputs Documentation for any passthru outputs of `buildImage`. ### Examples Note that this is the last nested heading in the `buildImage` section. :::{.example #ex-dockerTools-buildImage} # Using `buildImage` Example of how to use `buildImage` goes here. ::: ``` ### Function arguments Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments as well as their [types](https://nixos.org/manual/nix/stable/language/values). For example: ```markdown # pkgs.coolFunction {#pkgs.coolFunction} `pkgs.coolFunction` *`name`* *`config`* Description of what `callPackage` does. ## Inputs {#pkgs-coolFunction-inputs} If something's special about `coolFunction`'s general argument handling, you can say so here. Otherwise, just describe the single argument or start the arguments' definition list without introduction. *`name`* (String) : The name of the resulting image. *`config`* (Attribute set) : 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. `outputHash` (String; _optional_)

This section provides guidelines on how to document REPL interactions, emphasizing the visual separation of inputs and outputs and providing specific formatting examples for both shell and Nix REPL sessions. It also outlines a structured approach for documenting functions, advocating for the use of nested headings to organize inputs, outputs, and examples, with examples positioned as the last nested heading and linked to within the documentation. Additionally, it specifies the use of definition lists for documenting function arguments, including their types and attributes.