docs/lib: use backticks for nix names

lib/asserts.nix

@@ -14,7 +14,7 @@ in
 rec {
 
   /**
-    Throw if pred is false, else return pred.
+    Throw if `pred` is false, else return `pred`.
     Intended to be used to augment asserts with helpful error messages.
 
     # Inputs

lib/attrsets.nix

@@ -918,8 +918,8 @@ rec {
     ) [ { } ] (attrNames attrsOfLists);
 
   /**
-    Return the result of function f applied to the cartesian product of attribute set value combinations.
-    Equivalent to using cartesianProduct followed by map.
+    Return the result of function `f` applied to the cartesian product of attribute set value combinations.
+    Equivalent to using `cartesianProduct` followed by `map`.
 
     # Inputs
 
@@ -1522,7 +1522,7 @@ rec {
     );
 
   /**
-    Merge sets of attributes and use the function f to merge attribute values.
+    Merge sets of attributes and use the function `f` to merge attribute values.
     Like `lib.attrsets.zipAttrsWithNames` with all key names are passed for `names`.
 
     Implementation note: Common names appear multiple times in the list of
@@ -1628,7 +1628,7 @@ rec {
       binaryMerge 0 (length list);
 
   /**
-    Does the same as the update operator '//' except that attributes are
+    Does the same as the update operator `//` except that attributes are
     merged until the given predicate is verified.  The predicate should
     accept 3 arguments which are the path to reach the attribute, a part of
     the first attribute set and a part of the second attribute set.  When
@@ -1701,7 +1701,7 @@ rec {
     f [ ] [ rhs lhs ];
 
   /**
-    A recursive variant of the update operator ‘//’.  The recursion
+    A recursive variant of the update operator `//`.  The recursion
     stops when one of the attribute values is not an attribute set,
     in which case the right hand side value takes precedence over the
     left hand side value.
@@ -2183,7 +2183,7 @@ rec {
   recurseIntoAttrs = attrs: attrs // { recurseForDerivations = true; };
 
   /**
-    Undo the effect of recurseIntoAttrs.
+    Undo the effect of `recurseIntoAttrs`.
 
     # Inputs
 

lib/cli.nix

@@ -85,7 +85,7 @@
     `optionValueSeparator`
 
     : How to separate an option from its flag;
-    By default, there is no separator, so option `-c` and value `5` would become ["-c" "5"].
+    By default, there is no separator, so option `-c` and value `5` would become `["-c" "5"]`.
     This is useful if the command requires equals, for example, `-c=5`.
 
     # Examples

lib/customisation.nix

@@ -323,7 +323,7 @@ rec {
       abort "lib.customisation.callPackageWith: ${error}";
 
   /**
-    Like callPackage, but for a function that returns an attribute
+    Like `callPackage`, but for a function that returns an attribute
     set of derivations. The override function is added to the
     individual attributes.
 
@@ -665,7 +665,7 @@ rec {
     };
 
   /**
-    Like makeScope, but aims to support cross compilation. It's still ugly, but
+    Like `makeScope`, but aims to support cross compilation. It's still ugly, but
     hopefully it helps a little bit.
 
     # Type
@@ -775,7 +775,7 @@ rec {
         `excludeFunctionArgNames` is useful for argument deprecation while avoiding ellipses.
 
       `extendDrvArgs` (required)
-      : An extension (overlay) of the argument set, like the one taken by [overrideAttrs](#sec-pkg-overrideAttrs) but applied before passing to `constructDrv`.
+      : An extension (overlay) of the argument set, like the one taken by [`overrideAttrs`](#sec-pkg-overrideAttrs) but applied before passing to `constructDrv`.
 
       `inheritFunctionArgs` (default to `true`)
       : Whether to inherit `__functionArgs` from the base build helper.

lib/derivations.nix

@@ -86,7 +86,7 @@ in
       This can be used for adding package attributes, such as `tests`.
 
     `outputs`
-    : Optional list of assumed outputs. Default: ["out"]
+    : Optional list of assumed outputs. Default: `[ "out" ]`
 
       This must match the set of outputs that the returned derivation has.
       You must use this when the derivation has multiple outputs.

lib/filesystem.nix

@@ -28,7 +28,8 @@ in
 
   /**
     The type of a path. The path needs to exist and be accessible.
-    The result is either "directory" for a directory, "regular" for a regular file, "symlink" for a symlink, or "unknown" for anything else.
+    The result is either `"directory"` for a directory, `"regular"` for a
+    regular file, `"symlink"` for a symlink, or `"unknown"` for anything else.
 
     # Inputs
 
@@ -160,9 +161,9 @@ in
     in
     builtins.listToAttrs cabal-subdirs;
   /**
-    Find the first directory containing a file matching 'pattern'
-    upward from a given 'file'.
-    Returns 'null' if no directories contain a file matching 'pattern'.
+    Find the first directory containing a file matching `pattern`
+    upward from a given `file`.
+    Returns `null` if no directories contain a file matching `pattern`.
 
     # Inputs
 

lib/fixed-points.nix

@@ -329,7 +329,7 @@ rec {
 
   /**
     Compose two overlay functions and return a single overlay function that combines them.
-    For more details see: [composeManyExtensions](#function-library-lib.fixedPoints.composeManyExtensions).
+    For more details see: [`composeManyExtensions`](#function-library-lib.fixedPoints.composeManyExtensions).
   */
   composeExtensions =
     f: g: final: prev:

lib/generators.nix

@@ -129,11 +129,11 @@ rec {
       err "this value is" (toString v);
 
   /**
-    Generate a line of key k and value v, separated by
-    character sep. If sep appears in k, it is escaped.
+    Generate a line of key `k` and value `v`, separated by
+    character `sep`. If `sep` appears in `k`, it is escaped.
     Helper for synaxes with different separators.
 
-    mkValueString specifies how values should be formatted.
+    `mkValueString` specifies how values should be formatted.
 
     ```nix
     mkKeyValueDefault {} ":" "f:oo" "bar"
@@ -430,7 +430,7 @@ rec {
     toINI_ (gitFlattenAttrs attrs);
 
   /**
-    mkKeyValueDefault wrapper that handles dconf INI quirks.
+    `mkKeyValueDefault` wrapper that handles dconf INI quirks.
     The main differences of the format is that it requires strings to be quoted.
   */
   mkDconfKeyValue = mkKeyValueDefault { mkValueString = v: toString (gvariant.mkValue v); } "=";
@@ -509,9 +509,9 @@ rec {
 
     Structured function argument
     : allowPrettyValues
-      : If this option is true, attrsets like { __pretty = fn; val = …; }
-        will use fn to convert val to a pretty printed representation.
-        (This means fn is type Val -> String.)
+      : If this option is true, attrsets like `{ __pretty = fn; val = …; }`
+        will use `fn` to convert `val` to a pretty printed representation.
+        (This means `fn` is type `Val -> String`.)
     : multiline
       : If this option is true, the output is indented with newlines for attribute sets and lists
     : indent
@@ -748,13 +748,13 @@ rec {
 
   /**
     Translate a simple Nix expression to Lua representation with occasional
-    Lua-inlines that can be constructed by mkLuaInline function.
+    Lua-inlines that can be constructed by `mkLuaInline` function.
 
     Configuration:
 
-    * multiline - by default is true which results in indented block-like view.
-    * indent - initial indent.
-    * asBindings - by default generate single value, but with this use attrset to set global vars.
+    * `multiline` - by default is true which results in indented block-like view.
+    * `indent` - initial indent.
+    * `asBindings` - by default generate single value, but with this use attrset to set global vars.
 
     Attention:
 
@@ -868,7 +868,7 @@ rec {
       abort "generators.toLua: type ${typeOf v} is unsupported";
 
   /**
-    Mark string as Lua expression to be inlined when processed by toLua.
+    Mark string as Lua expression to be inlined when processed by `toLua`.
 
     # Inputs
 

lib/lists.nix

@@ -439,7 +439,7 @@ rec {
   flatten = x: if isList x then concatMap (y: flatten y) x else [ x ];
 
   /**
-    Remove elements equal to 'e' from a list.  Useful for buildInputs.
+    Remove elements equal to `e` from a list.  Useful for `buildInputs`.
 
     # Inputs
 
@@ -1926,7 +1926,7 @@ rec {
   allUnique = list: (length (unique list) == length list);
 
   /**
-    Intersects list 'list1' and another list (`list2`).
+    Intersects list `list1` and another list (`list2`).
 
     O(nm) complexity.
 
@@ -1954,7 +1954,7 @@ rec {
   intersectLists = e: filter (x: elem x e);
 
   /**
-    Subtracts list 'e' from another list (`list2`).
+    Subtracts list `e` from another list (`list2`).
 
     O(nm) complexity.
 
@@ -1983,7 +1983,7 @@ rec {
 
   /**
     Test if two lists have no common element.
-    It should be slightly more efficient than (intersectLists a b == [])
+    It should be slightly more efficient than `intersectLists a b == []`.
 
     # Inputs
 

lib/meta.nix

@@ -180,7 +180,7 @@ rec {
   lowPrio = setPrio 10;
 
   /**
-    Apply lowPrio to an attrset with derivations.
+    Apply `lowPrio` to an attrset with derivations.
 
     # Inputs
 
@@ -203,7 +203,7 @@ rec {
   hiPrio = setPrio (-10);
 
   /**
-    Apply hiPrio to an attrset with derivations.
+    Apply `hiPrio` to an attrset with derivations.
 
     # Inputs
 
@@ -414,7 +414,7 @@ rec {
     licstr: default: lowercaseLicenses.${lib.toLower licstr} or default;
 
   /**
-    Get the path to the main program of a package based on meta.mainProgram
+    Get the path to the main program of a package based on `meta.mainProgram`
 
     # Inputs
 

lib/options.nix

@@ -77,7 +77,7 @@ rec {
   isOption = lib.isType "option";
 
   /**
-    Creates an Option attribute set. mkOption accepts an attribute set with the following keys:
+    Creates an Option attribute set. `mkOption` accepts an attribute set with the following keys:
 
     # Inputs
 
@@ -152,7 +152,7 @@ rec {
     attrs // { _type = "option"; };
 
   /**
-    Creates an option declaration with a default value of ´false´, and can be defined to ´true´.
+    Creates an option declaration with a default value of `false`, and can be defined to `true`.
 
     # Inputs
 
@@ -516,7 +516,7 @@ rec {
       ) (head defs) (tail defs)).value;
 
   /**
-    Extracts values of all "value" keys of the given list.
+    Extracts values of all `value` keys of the given list.
 
     # Type
 
@@ -538,7 +538,7 @@ rec {
   getValues = map (x: x.value);
 
   /**
-    Extracts values of all "file" keys of the given list
+    Extracts values of all `file` keys of the given list
 
     # Type
 
@@ -615,7 +615,7 @@ rec {
     (on the order of megabytes) and is not actually used by the
     manual generator.
 
-    This function was made obsolete by renderOptionValue and is kept for
+    This function was made obsolete by `renderOptionValue` and is kept for
     compatibility with out-of-tree code.
 
     # Inputs

lib/sources.nix

@@ -20,7 +20,7 @@ let
 
   /**
     A basic filter for `cleanSourceWith` that removes
-    directories of version control system, backup files (*~)
+    directories of version control system, backup files (`*~`)
     and some generated files.
 
     # Inputs
@@ -72,7 +72,7 @@ let
     );
 
   /**
-    Filters a source tree removing version control files and directories using cleanSourceFilter.
+    Filters a source tree removing version control files and directories using `cleanSourceFilter`.
 
     # Inputs
 

lib/strings.nix

@@ -124,7 +124,7 @@ rec {
   concatMapStrings = f: list: concatStrings (map f list);
 
   /**
-    Like `concatMapStrings` except that the f functions also gets the
+    Like `concatMapStrings` except that the function `f` also gets the
     position as a parameter.
 
     # Inputs
@@ -733,7 +733,7 @@ rec {
       );
 
   /**
-    Depending on the boolean `cond', return either the given string
+    Depending on the boolean `cond`, return either the given string
     or the empty string. Useful to concatenate against a bigger string.
 
     # Inputs
@@ -1937,7 +1937,7 @@ rec {
   versionOlder = v1: v2: compareVersions v2 v1 == 1;
 
   /**
-    Returns true if string v1 denotes a version equal to or newer than v2.
+    Returns true if string `v1` denotes a version equal to or newer than `v2`.
 
     # Inputs
 
@@ -2576,7 +2576,7 @@ rec {
     lib.warnIf (!precise) "Imprecise conversion from float to string ${result}" result;
 
   /**
-    Check whether a list or other value `x` can be passed to toString.
+    Check whether a list or other value `x` can be passed to `toString`.
 
     Many types of value are coercible to string this way, including `int`, `float`,
     `null`, `bool`, `list` of similarly coercible values.
@@ -2675,7 +2675,7 @@ rec {
 
   /**
     Parse a string as an int. Does not support parsing of integers with preceding zero due to
-    ambiguity between zero-padded and octal numbers. See toIntBase10.
+    ambiguity between zero-padded and octal numbers. See `toIntBase10`.
 
     # Inputs
 

lib/trivial.nix

@@ -913,7 +913,7 @@ in
   throwIfNot = cond: msg: if cond then x: x else throw msg;
 
   /**
-    Like throwIfNot, but negated (throw if the first argument is `true`).
+    Like `throwIfNot`, but negated (throw if the first argument is `true`).
 
     # Inputs
 
@@ -991,8 +991,8 @@ in
     setFunctionArgs : (a → b) → Map String Bool → (a → b)
 
     This function is necessary because you can't dynamically create a
-    function of the { a, b ? foo, ... }: format, but some facilities
-    like callPackage expect to be able to query expected arguments.
+    function of the `{ a, b ? foo, ... }:` format, but some facilities
+    like `callPackage` expect to be able to query expected arguments.
 
     # Inputs
 
@@ -1012,9 +1012,9 @@ in
 
   /**
     Extract the expected function arguments from a function.
-    This works both with nix-native { a, b ? foo, ... }: style
-    functions and functions with args set with 'setFunctionArgs'. It
-    has the same return type and semantics as builtins.functionArgs.
+    This works both with nix-native `{ a, b ? foo, ... }:` style
+    functions and functions with args set with `setFunctionArgs`. It
+    has the same return type and semantics as `builtins.functionArgs`.
     setFunctionArgs : (a → b) → Map String Bool.
 
     # Inputs
@@ -1180,8 +1180,8 @@ in
     i: lib.concatMapStrings toHexDigit (toBaseDigits 16 i);
 
   /**
-    `toBaseDigits base i` converts the positive integer i to a list of its
-    digits in the given base. For example:
+    `toBaseDigits base i` converts the positive integer `i` to a list of its
+    digits in the given base.
 
     toBaseDigits 10 123 => [ 1 2 3 ]