Docs: migrate format of comments to doc-comments

1 files changed, 324 insertions, 167 deletions

diff --git a/lib/path/default.nix b/lib/path/default.nix
index e8f0c646c545..62c5b7d3c5da 100644
--- a/lib/path/default.nix
+++ b/lib/path/default.nix
@@ -165,7 +165,7 @@ in
 # No rec! Add dependencies on this file at the top.
 {
 
-  /*
+  /**
     Append a subpath string to a path.
 
     Like `path + ("/" + string)` but safer, because it errors instead of returning potentially surprising results.
@@ -178,34 +178,55 @@ in
 
           append p s == append p (subpath.normalise s)
 
-    Type:
-      append :: Path -> String -> Path
 
-    Example:
-      append /foo "bar/baz"
-      => /foo/bar/baz
+    # Inputs
 
-      # subpaths don't need to be normalised
-      append /foo "./bar//baz/./"
-      => /foo/bar/baz
+    `path`
 
-      # can append to root directory
-      append /. "foo/bar"
-      => /foo/bar
+    : The absolute path to append to
 
-      # first argument needs to be a path value type
-      append "/foo" "bar"
-      => <error>
+    `subpath`
 
-      # second argument needs to be a valid subpath string
-      append /foo /bar
-      => <error>
-      append /foo ""
-      => <error>
-      append /foo "/bar"
-      => <error>
-      append /foo "../bar"
-      => <error>
+    : The subpath string to append
+
+    # Type
+
+    ```
+    append :: Path -> String -> Path
+    ```
+
+    # Examples
+    :::{.example}
+    ## `append` usage example
+
+    ```nix
+    append /foo "bar/baz"
+    => /foo/bar/baz
+
+    # subpaths don't need to be normalised
+    append /foo "./bar//baz/./"
+    => /foo/bar/baz
+
+    # can append to root directory
+    append /. "foo/bar"
+    => /foo/bar
+
+    # first argument needs to be a path value type
+    append "/foo" "bar"
+    => <error>
+
+    # second argument needs to be a valid subpath string
+    append /foo /bar
+    => <error>
+    append /foo ""
+    => <error>
+    append /foo "/bar"
+    => <error>
+    append /foo "../bar"
+    => <error>
+    ```
+
+    :::
   */
   append =
     # The absolute path to append to
@@ -219,7 +240,7 @@ in
           ${subpathInvalidReason subpath}'';
     path + ("/" + subpath);
 
-  /*
+  /**
     Whether the first path is a component-wise prefix of the second path.
 
     Laws:
@@ -228,18 +249,35 @@ in
 
     - `hasPrefix` is a [non-strict partial order](https://en.wikipedia.org/wiki/Partially_ordered_set#Non-strict_partial_order) over the set of all path values.
 
-    Type:
-      hasPrefix :: Path -> Path -> Bool
 
-    Example:
-      hasPrefix /foo /foo/bar
-      => true
-      hasPrefix /foo /foo
-      => true
-      hasPrefix /foo/bar /foo
-      => false
-      hasPrefix /. /foo
-      => true
+    # Inputs
+
+    `path1`
+
+    : 1\. Function argument
+
+    # Type
+
+    ```
+    hasPrefix :: Path -> Path -> Bool
+    ```
+
+    # Examples
+    :::{.example}
+    ## `hasPrefix` usage example
+
+    ```nix
+    hasPrefix /foo /foo/bar
+    => true
+    hasPrefix /foo /foo
+    => true
+    hasPrefix /foo/bar /foo
+    => false
+    hasPrefix /. /foo
+    => true
+    ```
+
+    :::
   */
   hasPrefix =
     path1:
@@ -261,7 +299,7 @@ in
     take (length path1Deconstructed.components) path2Deconstructed.components
     == path1Deconstructed.components;
 
-  /*
+  /**
     Remove the first path as a component-wise prefix from the second path.
     The result is a [normalised subpath string](#function-library-lib.path.subpath.normalise).
 
@@ -271,18 +309,35 @@ in
 
           removePrefix p (append p s) == subpath.normalise s
 
-    Type:
-      removePrefix :: Path -> Path -> String
 
-    Example:
-      removePrefix /foo /foo/bar/baz
-      => "./bar/baz"
-      removePrefix /foo /foo
-      => "./."
-      removePrefix /foo/bar /foo
-      => <error>
-      removePrefix /. /foo
-      => "./foo"
+    # Inputs
+
+    `path1`
+
+    : 1\. Function argument
+
+    # Type
+
+    ```
+    removePrefix :: Path -> Path -> String
+    ```
+
+    # Examples
+    :::{.example}
+    ## `removePrefix` usage example
+
+    ```nix
+    removePrefix /foo /foo/bar/baz
+    => "./bar/baz"
+    removePrefix /foo /foo
+    => "./."
+    removePrefix /foo/bar /foo
+    => <error>
+    removePrefix /. /foo
+    => "./foo"
+    ```
+
+    :::
   */
   removePrefix =
     path1:
@@ -310,7 +365,7 @@ in
           second argument: "${toString path2}" with root "${toString path2Deconstructed.root}"'';
     joinRelPath components;
 
-  /*
+  /**
     Split the filesystem root from a [path](https://nixos.org/manual/nix/stable/language/values.html#type-path).
     The result is an attribute set with these attributes:
     - `root`: The filesystem root of the path, meaning that this directory has no parent directory.
@@ -328,22 +383,39 @@ in
 
           dirOf (splitRoot p).root == (splitRoot p).root
 
-    Type:
-      splitRoot :: Path -> { root :: Path, subpath :: String }
 
-    Example:
-      splitRoot /foo/bar
-      => { root = /.; subpath = "./foo/bar"; }
+    # Inputs
+
+    `path`
+
+    : The path to split the root off of
 
-      splitRoot /.
-      => { root = /.; subpath = "./."; }
+    # Type
 
-      # Nix neutralises `..` path components for all path values automatically
-      splitRoot /foo/../bar
-      => { root = /.; subpath = "./bar"; }
+    ```
+    splitRoot :: Path -> { root :: Path, subpath :: String }
+    ```
 
-      splitRoot "/foo/bar"
-      => <error>
+    # Examples
+    :::{.example}
+    ## `splitRoot` usage example
+
+    ```nix
+    splitRoot /foo/bar
+    => { root = /.; subpath = "./foo/bar"; }
+
+    splitRoot /.
+    => { root = /.; subpath = "./."; }
+
+    # Nix neutralises `..` path components for all path values automatically
+    splitRoot /foo/../bar
+    => { root = /.; subpath = "./bar"; }
+
+    splitRoot "/foo/bar"
+    => <error>
+    ```
+
+    :::
   */
   splitRoot =
     # The path to split the root off of
@@ -358,7 +430,7 @@ in
       subpath = joinRelPath deconstructed.components;
     };
 
-  /*
+  /**
     Whether a [path](https://nixos.org/manual/nix/stable/language/values.html#type-path)
     has a [store path](https://nixos.org/manual/nix/stable/store/store-path.html#store-path)
     as a prefix.
@@ -371,33 +443,50 @@ in
     which occur when Nix files in the store use relative path expressions.
     :::
 
-    Type:
-      hasStorePathPrefix :: Path -> Bool
 
-    Example:
-      # Subpaths of derivation outputs have a store path as a prefix
-      hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo/bar/baz
-      => true
+    # Inputs
+
+    `path`
+
+    : 1\. Function argument
+
+    # Type
 
-      # The store directory itself is not a store path
-      hasStorePathPrefix /nix/store
-      => false
+    ```
+    hasStorePathPrefix :: Path -> Bool
+    ```
 
-      # Derivation outputs are store paths themselves
-      hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo
-      => true
+    # Examples
+    :::{.example}
+    ## `hasStorePathPrefix` usage example
 
-      # Paths outside the Nix store don't have a store path prefix
-      hasStorePathPrefix /home/user
-      => false
+    ```nix
+    # Subpaths of derivation outputs have a store path as a prefix
+    hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo/bar/baz
+    => true
 
-      # Not all paths under the Nix store are store paths
-      hasStorePathPrefix /nix/store/.links/10gg8k3rmbw8p7gszarbk7qyd9jwxhcfq9i6s5i0qikx8alkk4hq
-      => false
+    # The store directory itself is not a store path
+    hasStorePathPrefix /nix/store
+    => false
 
-      # Store derivations are also store paths themselves
-      hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo.drv
-      => true
+    # Derivation outputs are store paths themselves
+    hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo
+    => true
+
+    # Paths outside the Nix store don't have a store path prefix
+    hasStorePathPrefix /home/user
+    => false
+
+    # Not all paths under the Nix store are store paths
+    hasStorePathPrefix /nix/store/.links/10gg8k3rmbw8p7gszarbk7qyd9jwxhcfq9i6s5i0qikx8alkk4hq
+    => false
+
+    # Store derivations are also store paths themselves
+    hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo.drv
+    => true
+    ```
+
+    :::
   */
   hasStorePathPrefix =
     path:
@@ -414,7 +503,7 @@ in
       "lib.path.hasStorePathPrefix: Argument has a filesystem root (${toString deconstructed.root}) that's not /, which is currently not supported.";
     componentsHaveStorePathPrefix deconstructed.components;
 
-  /*
+  /**
     Whether a value is a valid subpath string.
 
     A subpath string points to a specific file or directory within an absolute base directory.
@@ -428,39 +517,56 @@ in
 
     - The string doesn't contain any `..` path components.
 
-    Type:
-      subpath.isValid :: String -> Bool
 
-    Example:
-      # Not a string
-      subpath.isValid null
-      => false
+    # Inputs
+
+    `value`
+
+    : The value to check
+
+    # Type
+
+    ```
+    subpath.isValid :: String -> Bool
+    ```
+
+    # Examples
+    :::{.example}
+    ## `subpath.isValid` usage example
 
-      # Empty string
-      subpath.isValid ""
-      => false
+    ```nix
+    # Not a string
+    subpath.isValid null
+    => false
 
-      # Absolute path
-      subpath.isValid "/foo"
-      => false
+    # Empty string
+    subpath.isValid ""
+    => false
 
-      # Contains a `..` path component
-      subpath.isValid "../foo"
-      => false
+    # Absolute path
+    subpath.isValid "/foo"
+    => false
 
-      # Valid subpath
-      subpath.isValid "foo/bar"
-      => true
+    # Contains a `..` path component
+    subpath.isValid "../foo"
+    => false
 
-      # Doesn't need to be normalised
-      subpath.isValid "./foo//bar/"
-      => true
+    # Valid subpath
+    subpath.isValid "foo/bar"
+    => true
+
+    # Doesn't need to be normalised
+    subpath.isValid "./foo//bar/"
+    => true
+    ```
+
+    :::
   */
   subpath.isValid =
     # The value to check
     value: subpathInvalidReason value == null;
 
-  /*
+  /**
     Join subpath strings together using `/`, returning a normalised subpath string.
 
     Like `concatStringsSep "/"` but safer, specifically:
@@ -492,30 +598,47 @@ in
 
           ps != [] -> subpath.join ps == subpath.normalise (concatStringsSep "/" ps)
 
-    Type:
-      subpath.join :: [ String ] -> String
 
-    Example:
-      subpath.join [ "foo" "bar/baz" ]
-      => "./foo/bar/baz"
+    # Inputs
+
+    `subpaths`
+
+    : The list of subpaths to join together
+
+    # Type
+
+    ```
+    subpath.join :: [ String ] -> String
+    ```
+
+    # Examples
+    :::{.example}
+    ## `subpath.join` usage example
+
+    ```nix
+    subpath.join [ "foo" "bar/baz" ]
+    => "./foo/bar/baz"
 
-      # normalise the result
-      subpath.join [ "./foo" "." "bar//./baz/" ]
-      => "./foo/bar/baz"
+    # normalise the result
+    subpath.join [ "./foo" "." "bar//./baz/" ]
+    => "./foo/bar/baz"
 
-      # passing an empty list results in the current directory
-      subpath.join [ ]
-      => "./."
+    # passing an empty list results in the current directory
+    subpath.join [ ]
+    => "./."
 
-      # elements must be valid subpath strings
-      subpath.join [ /foo ]
-      => <error>
-      subpath.join [ "" ]
-      => <error>
-      subpath.join [ "/foo" ]
-      => <error>
-      subpath.join [ "../foo" ]
-      => <error>
+    # elements must be valid subpath strings
+    subpath.join [ /foo ]
+    => <error>
+    subpath.join [ "" ]
+    => <error>
+    subpath.join [ "/foo" ]
+    => <error>
+    subpath.join [ "../foo" ]
+    => <error>
+    ```
+
+    :::
   */
   subpath.join =
     # The list of subpaths to join together
@@ -537,7 +660,7 @@ in
                 ${subpathInvalidReason path}''
       ) 0 subpaths;
 
-  /*
+  /**
     Split [a subpath](#function-library-lib.path.subpath.isValid) into its path component strings.
     Throw an error if the subpath isn't valid.
     Note that the returned path components are also [valid subpath strings](#function-library-lib.path.subpath.isValid), though they are intentionally not [normalised](#function-library-lib.path.subpath.normalise).
@@ -548,18 +671,35 @@ in
 
           subpath.join (subpath.components s) == subpath.normalise s
 
-    Type:
-      subpath.components :: String -> [ String ]
 
-    Example:
-      subpath.components "."
-      => [ ]
+    # Inputs
+
+    `subpath`
+
+    : The subpath string to split into components
+
+    # Type
+
+    ```
+    subpath.components :: String -> [ String ]
+    ```
+
+    # Examples
+    :::{.example}
+    ## `subpath.components` usage example
+
+    ```nix
+    subpath.components "."
+    => [ ]
+
+    subpath.components "./foo//bar/./baz/"
+    => [ "foo" "bar" "baz" ]
 
-      subpath.components "./foo//bar/./baz/"
-      => [ "foo" "bar" "baz" ]
+    subpath.components "/foo"
+    => <error>
+    ```
 
-      subpath.components "/foo"
-      => <error>
+    :::
   */
   subpath.components =
     # The subpath string to split into components
@@ -569,7 +709,7 @@ in
           ${subpathInvalidReason subpath}'';
     splitRelPath subpath;
 
-  /*
+  /**
     Normalise a subpath. Throw an error if the subpath isn't [valid](#function-library-lib.path.subpath.isValid).
 
     - Limit repeating `/` to a single one.
@@ -602,45 +742,62 @@ in
 
           builtins.tryEval (subpath.normalise p)).success == subpath.isValid p
 
-    Type:
-      subpath.normalise :: String -> String
 
-    Example:
-      # limit repeating `/` to a single one
-      subpath.normalise "foo//bar"
-      => "./foo/bar"
+    # Inputs
+
+    `subpath`
+
+    : The subpath string to normalise
+
+    # Type
+
+    ```
+    subpath.normalise :: String -> String
+    ```
 
-      # remove redundant `.` components
-      subpath.normalise "foo/./bar"
-      => "./foo/bar"
+    # Examples
+    :::{.example}
+    ## `subpath.normalise` usage example
 
-      # add leading `./`
-      subpath.normalise "foo/bar"
-      => "./foo/bar"
+    ```nix
+    # limit repeating `/` to a single one
+    subpath.normalise "foo//bar"
+    => "./foo/bar"
 
-      # remove trailing `/`
-      subpath.normalise "foo/bar/"
-      => "./foo/bar"
+    # remove redundant `.` components
+    subpath.normalise "foo/./bar"
+    => "./foo/bar"
 
-      # remove trailing `/.`
-      subpath.normalise "foo/bar/."
-      => "./foo/bar"
+    # add leading `./`
+    subpath.normalise "foo/bar"
+    => "./foo/bar"
 
-      # Return the current directory as `./.`
-      subpath.normalise "."
-      => "./."
+    # remove trailing `/`
+    subpath.normalise "foo/bar/"
+    => "./foo/bar"
 
-      # error on `..` path components
-      subpath.normalise "foo/../bar"
-      => <error>
+    # remove trailing `/.`
+    subpath.normalise "foo/bar/."
+    => "./foo/bar"
 
-      # error on empty string
-      subpath.normalise ""
-      => <error>
+    # Return the current directory as `./.`
+    subpath.normalise "."
+    => "./."
 
-      # error on absolute path
-      subpath.normalise "/foo"
-      => <error>
+    # error on `..` path components
+    subpath.normalise "foo/../bar"
+    => <error>
+
+    # error on empty string
+    subpath.normalise ""
+    => <error>
+
+    # error on absolute path
+    subpath.normalise "/foo"
+    => <error>
+    ```
+
+    :::
   */
   subpath.normalise =
     # The subpath string to normalise