Merge pull request #329400 from NixOS/doc-function-inputs

doc/README: Add function Inputs guidelines

doc/README.md

@@ -251,25 +251,42 @@ You, as the writer of documentation, are still in charge of its content.
   For example:
 
   ```markdown
-  # pkgs.coolFunction
+  # pkgs.coolFunction {#pkgs.coolFunction}
 
-  Description of what `coolFunction` does.
+  `pkgs.coolFunction` *`name`* *`config`*
 
-  ## Inputs
+  Description of what `callPackage` does.
 
-  `coolFunction` expects a single argument which should be an attribute set, with the following possible attributes:
 
-  `name` (String)
+  ## 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.
 
-  `tag` (String; _optional_)
+  *`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.
 
-  : Tag of the generated image.
+    `outputHash` (String; _optional_)
 
-    _Default:_ the output path's hash.
+    : A brief explanation including when and when not to pass this attribute.
+
+    : _Default:_ the output path's hash.
   ```
 
+  Checklist:
+  - Start with a synopsis, to show the order of positional arguments.
+  - Metavariables are in emphasized code spans: ``` *`arg1`* ```. Metavariables are placeholders where users may write arbitrary expressions. This includes positional arguments.
+  - Attribute names are regular code spans: ``` `attr1` ```. These identifiers can _not_ be picked freely by users, so they are _not_ metavariables.
+  - _optional_ attributes have a _`Default:`_ if it's easily described as a value.
+  - _optional_ attributes have a _`Default behavior:`_ if it's not easily described using a value.
+  - Nix types aren't in code spans, because they are not code
+  - Nix types are capitalized, to distinguish them from the camelCase [Module System](#module-system) types, which _are_ code and behave like functions.
+
 #### Examples
 
 To define a referenceable figure use the following fencing: