lib.meta: refactor to use doc-comments (#313589)

* doc: use doc-comments for lib.meta

* adds missing argument to setPrio

1 files changed, 285 insertions, 74 deletions

diff --git a/lib/meta.nix b/lib/meta.nix
index 9a97afb1aa9b0..8fa93d40d5957 100644
--- a/lib/meta.nix
+++ b/lib/meta.nix
@@ -1,5 +1,7 @@
-/* Some functions for manipulating meta attributes, as well as the
-   name attribute. */
+/**
+  Some functions for manipulating meta attributes, as well as the
+  name attribute.
+*/
 
 { lib }:
 
@@ -11,90 +13,225 @@ in
 rec {
 
 
-  /* Add to or override the meta attributes of the given
-     derivation.
+  /**
+    Add to or override the meta attributes of the given
+    derivation.
 
-     Example:
-       addMetaAttrs {description = "Bla blah";} somePkg
+    # Inputs
+
+    `newAttrs`
+
+    : 1\. Function argument
+
+    `drv`
+
+    : 2\. Function argument
+
+
+    # Examples
+    :::{.example}
+    ## `lib.meta.addMetaAttrs` usage example
+
+    ```nix
+    addMetaAttrs {description = "Bla blah";} somePkg
+    ```
+
+    :::
   */
   addMetaAttrs = newAttrs: drv:
     drv // { meta = (drv.meta or {}) // newAttrs; };
 
 
-  /* Disable Hydra builds of given derivation.
+  /**
+    Disable Hydra builds of given derivation.
+
+    # Inputs
+
+    `drv`
+
+    : 1\. Function argument
   */
   dontDistribute = drv: addMetaAttrs { hydraPlatforms = []; } drv;
 
 
-  /*
-  Change the [symbolic name of a derivation](https://nixos.org/manual/nix/stable/language/derivations.html#attr-name).
+  /**
+    Change the [symbolic name of a derivation](https://nixos.org/manual/nix/stable/language/derivations.html#attr-name).
+
+    :::{.warning}
+    Dependent derivations will be rebuilt when the symbolic name is changed.
+    :::
 
-  :::{.warning}
-  Dependent derivations will be rebuilt when the symbolic name is changed.
-  :::
+    # Inputs
+
+    `name`
+
+    : 1\. Function argument
+
+    `drv`
+
+    : 2\. Function argument
   */
   setName = name: drv: drv // {inherit name;};
 
 
-  /* Like `setName`, but takes the previous name as an argument.
+  /**
+    Like `setName`, but takes the previous name as an argument.
+
+    # Inputs
+
+    `updater`
+
+    : 1\. Function argument
+
+    `drv`
+
+    : 2\. Function argument
+
+
+    # Examples
+    :::{.example}
+    ## `lib.meta.updateName` usage example
 
-     Example:
-       updateName (oldName: oldName + "-experimental") somePkg
+    ```nix
+    updateName (oldName: oldName + "-experimental") somePkg
+    ```
+
+    :::
   */
   updateName = updater: drv: drv // {name = updater (drv.name);};
 
 
-  /* Append a suffix to the name of a package (before the version
-     part). */
+  /**
+    Append a suffix to the name of a package (before the version
+    part).
+
+    # Inputs
+
+    `suffix`
+
+    : 1\. Function argument
+  */
   appendToName = suffix: updateName (name:
     let x = builtins.parseDrvName name; in "${x.name}-${suffix}-${x.version}");
 
 
-  /* Apply a function to each derivation and only to derivations in an attrset.
+  /**
+    Apply a function to each derivation and only to derivations in an attrset.
+
+
+    # Inputs
+
+    `f`
+
+    : 1\. Function argument
+
+    `set`
+
+    : 2\. Function argument
   */
   mapDerivationAttrset = f: set: lib.mapAttrs (name: pkg: if lib.isDerivation pkg then (f pkg) else pkg) set;
 
-  /* Set the nix-env priority of the package.
+  /**
+    Set the nix-env priority of the package.
+
+    # Inputs
+
+    `priority`
+    : 1\. Function argument
+
+    `drv`
+    : 2\. Function argument
   */
   setPrio = priority: addMetaAttrs { inherit priority; };
 
-  /* Decrease the nix-env priority of the package, i.e., other
-     versions/variants of the package will be preferred.
+  /**
+    Decrease the nix-env priority of the package, i.e., other
+    versions/variants of the package will be preferred.
+
+    # Inputs
+
+    `drv`
+
+    : 1\. Function argument
+
   */
   lowPrio = setPrio 10;
 
-  /* Apply lowPrio to an attrset with derivations
+  /**
+    Apply lowPrio to an attrset with derivations
+
+
+    # Inputs
+
+    `set`
+
+    : 1\. Function argument
   */
   lowPrioSet = set: mapDerivationAttrset lowPrio set;
 
 
-  /* Increase the nix-env priority of the package, i.e., this
-     version/variant of the package will be preferred.
+  /**
+    Increase the nix-env priority of the package, i.e., this
+    version/variant of the package will be preferred.
+
+    # Inputs
+
+    `drv`
+
+    : 1\. Function argument
   */
   hiPrio = setPrio (-10);
 
-  /* Apply hiPrio to an attrset with derivations
+  /**
+    Apply hiPrio to an attrset with derivations
+
+
+    # Inputs
+
+    `set`
+
+    : 1\. Function argument
   */
   hiPrioSet = set: mapDerivationAttrset hiPrio set;
 
 
-  /* Check to see if a platform is matched by the given `meta.platforms`
-     element.
+  /**
+    Check to see if a platform is matched by the given `meta.platforms`
+    element.
+
+    A `meta.platform` pattern is either
+
+    1. (legacy) a system string.
+
+    2. (modern) a pattern for the entire platform structure (see `lib.systems.inspect.platformPatterns`).
+
+    3. (modern) a pattern for the platform `parsed` field (see `lib.systems.inspect.patterns`).
 
-     A `meta.platform` pattern is either
+    We can inject these into a pattern for the whole of a structured platform,
+    and then match that.
 
-       1. (legacy) a system string.
 
-       2. (modern) a pattern for the entire platform structure (see `lib.systems.inspect.platformPatterns`).
+    # Inputs
 
-       3. (modern) a pattern for the platform `parsed` field (see `lib.systems.inspect.patterns`).
+    `platform`
 
-     We can inject these into a pattern for the whole of a structured platform,
-     and then match that.
+    : 1\. Function argument
 
-     Example:
-      lib.meta.platformMatch { system = "aarch64-darwin"; } "aarch64-darwin"
-      => true
+    `elem`
+
+    : 2\. Function argument
+
+
+    # Examples
+    :::{.example}
+    ## `lib.meta.platformMatch` usage example
+
+    ```nix
+    lib.meta.platformMatch { system = "aarch64-darwin"; } "aarch64-darwin"
+    => true
+    ```
+
+    :::
   */
   platformMatch = platform: elem: (
     # Check with simple string comparison if elem was a string.
@@ -112,39 +249,70 @@ rec {
     ) platform
   );
 
-  /* Check if a package is available on a given platform.
+  /**
+    Check if a package is available on a given platform.
+
+    A package is available on a platform if both
+
+    1. One of `meta.platforms` pattern matches the given
+        platform, or `meta.platforms` is not present.
+
+    2. None of `meta.badPlatforms` pattern matches the given platform.
+
+
+    # Inputs
+
+    `platform`
 
-     A package is available on a platform if both
+    : 1\. Function argument
 
-       1. One of `meta.platforms` pattern matches the given
-          platform, or `meta.platforms` is not present.
+    `pkg`
 
-       2. None of `meta.badPlatforms` pattern matches the given platform.
+    : 2\. Function argument
 
-     Example:
-       lib.meta.availableOn { system = "aarch64-darwin"; } pkg.zsh
-       => true
+
+    # Examples
+    :::{.example}
+    ## `lib.meta.availableOn` usage example
+
+    ```nix
+    lib.meta.availableOn { system = "aarch64-darwin"; } pkg.zsh
+    => true
+    ```
+
+    :::
   */
   availableOn = platform: pkg:
     ((!pkg?meta.platforms) || any (platformMatch platform) pkg.meta.platforms) &&
     all (elem: !platformMatch platform elem) (pkg.meta.badPlatforms or []);
 
-  /* Get the corresponding attribute in lib.licenses
-     from the SPDX ID.
-     For SPDX IDs, see
-     https://spdx.org/licenses
-
-     Type:
-       getLicenseFromSpdxId :: str -> AttrSet
-
-     Example:
-       lib.getLicenseFromSpdxId "MIT" == lib.licenses.mit
-       => true
-       lib.getLicenseFromSpdxId "mIt" == lib.licenses.mit
-       => true
-       lib.getLicenseFromSpdxId "MY LICENSE"
-       => trace: warning: getLicenseFromSpdxId: No license matches the given SPDX ID: MY LICENSE
-       => { shortName = "MY LICENSE"; }
+  /**
+    Get the corresponding attribute in lib.licenses
+    from the SPDX ID.
+    For SPDX IDs, see
+    https://spdx.org/licenses
+
+    # Type
+
+    ```
+    getLicenseFromSpdxId :: str -> AttrSet
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.meta.getLicenseFromSpdxId` usage example
+
+    ```nix
+    lib.getLicenseFromSpdxId "MIT" == lib.licenses.mit
+    => true
+    lib.getLicenseFromSpdxId "mIt" == lib.licenses.mit
+    => true
+    lib.getLicenseFromSpdxId "MY LICENSE"
+    => trace: warning: getLicenseFromSpdxId: No license matches the given SPDX ID: MY LICENSE
+    => { shortName = "MY LICENSE"; }
+    ```
+
+    :::
   */
   getLicenseFromSpdxId =
     let
@@ -156,15 +324,34 @@ rec {
         { shortName = licstr; }
       );
 
-  /* 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
+
+    `x`
+
+    : 1\. Function argument
+
+    # Type
+
+    ```
+    getExe :: package -> string
+    ```
 
-     Type: getExe :: package -> string
+    # Examples
+    :::{.example}
+    ## `lib.meta.getExe` usage example
 
-     Example:
-       getExe pkgs.hello
-       => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello"
-       getExe pkgs.mustache-go
-       => "/nix/store/am9ml4f4ywvivxnkiaqwr0hyxka1xjsf-mustache-go-1.3.0/bin/mustache"
+    ```nix
+    getExe pkgs.hello
+    => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello"
+    getExe pkgs.mustache-go
+    => "/nix/store/am9ml4f4ywvivxnkiaqwr0hyxka1xjsf-mustache-go-1.3.0/bin/mustache"
+    ```
+
+    :::
   */
   getExe = x: getExe' x (x.meta.mainProgram or (
     # This could be turned into an error when 23.05 is at end of life
@@ -173,14 +360,38 @@ rec {
     x
   ));
 
-  /* Get the path of a program of a derivation.
+  /**
+    Get the path of a program of a derivation.
+
+
+    # Inputs
+
+    `x`
+
+    : 1\. Function argument
+
+    `y`
+
+    : 2\. Function argument
+
+    # Type
+
+    ```
+    getExe' :: derivation -> string -> string
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.meta.getExe'` usage example
+
+    ```nix
+    getExe' pkgs.hello "hello"
+    => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello"
+    getExe' pkgs.imagemagick "convert"
+    => "/nix/store/5rs48jamq7k6sal98ymj9l4k2bnwq515-imagemagick-7.1.1-15/bin/convert"
+    ```
 
-     Type: getExe' :: derivation -> string -> string
-     Example:
-       getExe' pkgs.hello "hello"
-       => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello"
-       getExe' pkgs.imagemagick "convert"
-       => "/nix/store/5rs48jamq7k6sal98ymj9l4k2bnwq515-imagemagick-7.1.1-15/bin/convert"
+    :::
   */
   getExe' = x: y:
     assert assertMsg (isDerivation x)