lib: convert comments into nixdoc docstrings

lib/builders/default.nix

@@ -1,13 +1,227 @@
 { pkgs, lib, self }:
 
 {
+  /**
+    Create a derivation containing an XDG MIME association listing.
+
+    # Arguments
+
+    It's a sole attribute set with the following attributes:
+
+    config
+    : Nix-representable settings in INI format.
+
+    desktopName
+    : An optional string containing the desktop name. By default, it's empty
+    representing the global settings. Otherwise, it's considered to be
+    desktop-specific.
+
+    addedAssociations
+    : An attrset of MIME associations. This is not set if it's a
+    desktop-specific configuration.
+
+    removedAssociations
+    : An attrset of MIME associations. This is not set if it's a
+    desktop-specific configuration.
+
+    defaultApplications
+    : An attrset of MIME associations for default applications.
+
+    settings
+    : Nix-representable settings in INI format. Mutually exclusive with the
+    proper associations attribute and ignores proper checking if set. By
+    default, it is empty.
+
+    # Type
+
+    ```
+    makeXDGMimeAssociationList :: Attr -> Derivation
+    ```
+
+    # Examples
+
+    ```nix
+    makeXDGMimeAssociationList {
+      defaultApplications = { "application/pdf" = "firefox.desktop"; };
+      addedAssociations = {
+      };
+    }
+    ```
+  */
   makeXDGMimeAssociationList =
     pkgs.callPackage ./xdg/make-association-list.nix { };
+
+  /**
+    Create a derivation containing an XDG Portal configuration.
+
+    # Arguments
+
+    It's a sole attribute set with the following attributes:
+
+    config
+    : The settings as a Nix-representable settings in INI format.
+
+    desktopName
+    : The name of the desktop name. By default, it is set to `common` which is
+    considered as the global namespace. Otherwise, you can just set
+    desktop-specific settings.
+
+    # Type
+
+    ```
+    makeXDGPortalConfiguration :: Attr -> Derivation
+    ```
+
+    # Examples
+
+    ```nix
+    makeXDGPortalConfiguration {
+      desktopName = "one.foodogsquared.SampleDesktop";
+      config.preferred = {
+        default = "gtk";
+        "org.freedesktop.impl.portal.Screencast" = "gnome";
+      };
+    }
+    ```
+  */
   makeXDGPortalConfiguration =
     pkgs.callPackage ./xdg/make-portal-config.nix { };
+
+  /**
+    Create a derivation containing an XDG desktop entry file. Unlike
+    `pkgs.makeDesktopItem`, it's more freeform.
+
+    # Arguments
+
+    It's a sole attribute set with the following attributes:
+
+    name
+    : Name of the desktop entry. Only used as part of the package name and the
+    default value of the destination path.
+
+    config
+    : Nix-representable data to be exported as the desktop entry.
+
+    validate
+    : Add a validation check for the exported desktop entry.
+
+    destination 
+    : Destination path relative to the output path.
+
+    # Type
+
+    ```
+    makeXDGDesktopEntry :: Attr -> Derivation
+    ```
+
+    # Examples
+
+    ```nix
+    makeXDGDesktopEntry {
+      name = "horizontal-hunger";
+      validate = false;
+      config = { "Desktop Entry".Exec = "Hello"; };
+    }
+    ```
+  */
   makeXDGDesktopEntry = pkgs.callPackage ./xdg/make-desktop-entry.nix { };
+
+  /**
+    A wrapper for building Hugo projects.
+
+    # Arguments
+
+    Similar to `pkgs.buildGoModule`.
+
+    # Type
+
+    ```
+    buildHugoSite :: Attr -> Derivation
+    ```
+
+    # Examples
+
+    ```nix
+    buildHugoSite {
+      pname = "foodogsquared-hm-startpage";
+      version = "0.3.0";
+      src = lib.cleanSource ./.;
+
+      vendorHash = "sha256-Mi61QK1yKWIneZ+i79fpJqP9ew5r5vnv7ptr9YGq0Uk=";
+
+      preBuild = ''
+        install -Dm0644 ${
+          ../tinted-theming/base16/bark-on-a-tree.yaml
+        } ./data/foodogsquared-homepage/themes/_dark.yaml
+        install -Dm0644 ${
+          ../tinted-theming/base16/albino-bark-on-a-tree.yaml
+        } ./data/foodogsquared-homepage/themes/_light.yaml
+      '';
+
+      meta = with lib; {
+        description = "foodogsquared's homepage";
+        license = licenses.gpl3Only;
+      };
+    }
+    ```
+  */
   buildHugoSite = pkgs.callPackage ./hugo-build-site { };
+
+  /**
+    An convenient function for building with the custom extended stdenv.
+
+    # Arguments
+
+    Similar to `pkgs.buildEnv`.
+
+    # Type
+
+    ```
+    buildFDSEnv :: Attr -> Derivation
+    ```
+
+    # Examples
+
+    ```nix
+    buildFDSEnv {
+      paths = with pkgs; [ hello ];
+      pathsToLink = [ "/bin" "/share" ];
+    }
+    ```
+  */
   buildFDSEnv =
     pkgs.callPackage ./build-fds-env.nix { extendedStdenv = self.stdenv; };
+
+  /**
+    A wrapper for creating dconf databases.
+
+    # Arguments
+
+    A sole attribute set with the following attributes:
+
+    dir
+    : The directory of the dconf keyfiles.
+
+    name
+    : The name of the dconf database. By default, it is based from the directory name.
+
+    keyfiles
+    : A list of keyfiles to be included in the dconf database compilation.
+
+    # Type
+
+    ```
+    buildDconfDb :: Attr -> Derivation
+    ```
+
+    # Examples
+
+    ```nix
+    buildDconfDb {
+      dir = ./config/dconf;
+      name = "custom-gnome";
+    }
+    ```
+  */
   buildDconfDb = pkgs.callPackage ./build-dconf-db.nix { };
 }

lib/data.nix

@@ -5,14 +5,27 @@
 { pkgs, lib, self }:
 
 {
-  /* Import the YAML file and return it as a Nix object. Unfortunately, this is
+  /**
-     implemented as an import-from-derivation (IFD) so it will not be pretty.
+    Import the YAML file and return it as a Nix object. Unfortunately, this is
+    implemented as an import-from-derivation (IFD) so it will not be pretty.
 
-     Type: importYAML :: Path -> Attrs
+    # Arguments
 
-     Example:
+    path
-       importYAML ./your-mom.yaml
+    : The path of the YAML file.
-       => { name = "Yor Mum"; age = 56; world = "Herown"; }
+
+    # Type
+
+    ```
+    importYAML :: Path -> Attrs
+    ```
+
+    # Examples
+
+    ```nix
+    importYAML ./your-mom.yaml
+    => { name = "Yor Mum"; age = 56; world = "Herown"; }
+    ```
   */
   importYAML = path:
     let
@@ -21,14 +34,37 @@
       '';
     in lib.importJSON dataDrv;
 
-  /* Render a Tera template given a parameter set powered by `tera-cli`. Also
+  /**
-     typically used as an IFD.
+    Render a Tera template given a parameter set powered by `tera-cli`. Also
+    typically used as an IFD.
 
-     Type: renderTeraTemplate :: Attrs -> Path
+    # Arguments
 
-     Example:
+    It's a sole attribute set with the following attributes:
-       renderTeraTemplate { path = ./template.tera; context = { hello = 34; }; }
+
-       => /nix/store/HASH-tera-render-template
+    template
+    : The template file to be used.
+
+    context
+    : An attribute set containing the data used alongside the template.
+
+    extraArgs
+    : An attrset of command line arguments (same as
+    `lib.cli.toGNUCommandLineShell`) to be added on top of the typical
+    arguments used by the function.
+
+    # Type
+
+    ```
+    renderTeraTemplate :: Attrs -> Path
+    ```
+
+    # Example
+
+    ```nix
+    renderTeraTemplate { path = ./template.tera; context = { hello = 34; }; }
+    => /nix/store/HASH-tera-render-template
+    ```
   */
   renderTeraTemplate = { template, context, extraArgs ? { } }:
     let
@@ -45,14 +81,37 @@
       tera --out "$out" ${extraArgs'} --template "${template}" "${contextFile}"
     '';
 
-  /* Render a Mustache template given a parameter set powered by `mustache-go`.
+  /**
-     Also typically used as an IFD.
+    Render a Mustache template given a parameter set powered by `mustache-go`.
+    Also typically used as an IFD.
 
-     Type: renderMustacheTemplate :: Attrs -> Path
+    # Arguments
 
-     Example:
+    It's a sole attribute set with the following attributes:
-       renderMustacheTemplate { path = ./template.mustache; context = { hello = 34; }; }
+
-       => /nix/store/HASH-mustache-render-template
+    template
+    : The path containing the template file.
+
+    context
+    : An attribute set of metadata used in the template file.
+
+    extraArgs
+    : An attrset of additional command line arguments (same as the argument
+    used in `lib.cli.toGNUCommandLineShell`) on top of the typical arguments
+    used in the function.
+
+    # Type
+
+    ```
+    renderMustacheTemplate :: Attrs -> Path
+    ```
+
+    # Examples
+
+    ```nix
+    renderMustacheTemplate { path = ./template.mustache; context = { hello = 34; }; }
+    => /nix/store/HASH-mustache-render-template
+    ```
   */
   renderMustacheTemplate = { template, context, extraArgs ? { } }:
     let extraArgs' = lib.cli.toGNUCommandLineShell { } extraArgs;

lib/fetchers/default.nix

@@ -1,6 +1,84 @@
 { pkgs, lib, self }:
 
 {
+  /**
+    A convenient wrapper for fetching contents from the Internet Archive.
+
+    # Arguments
+
+    It's a sole attribute set with the extra following attributes:
+
+    id
+    : The identifier of the item typically found in the URL of the object.
+
+    formats
+    : An array of formats to be downloaded. Mutually exclusive with `file`
+    attribute.
+
+    file
+    : The specific file to be downloaded. Mutually exclusive with `formats`
+    attribute.
+
+    It can also accept other arguments as an extra attributes for its fetcher
+    function (e.g., `hash` for fixed-output derivations).
+
+    # Type
+
+    ```
+    fetchInternetArchive :: Attr -> Derivation
+    ```
+
+    # Examples
+
+    ```nix
+    fetchInternetArchive {
+      id = "md_music_sonic_the_hedgehog";
+      formats = [ "TEXT" "PNG" ];
+      hash = "sha256-xbhasJ/wEgcY+EcBAJp5UoYB4N4It3QV/iIeGGdCET8=";
+    }
+
+    fetchInternetArchive {
+      id = "md_music_sonic_the_hedgehog";
+      file = "01 - Title Theme - Masato Nakamura.flac";
+      hash = "sha256-kGjsVjtjXK9imqyi4GF6qkFVmobiTAe/ZAeEwiouqS4=";
+    }
+    ```
+  */
   fetchInternetArchive = pkgs.callPackage ./fetch-internet-archive { };
+
+  /**
+    An convenient wrapper for downloading Ugee drivers.
+
+    # Arguments
+
+    It's a sole attribute set with the following attributes:
+
+    fileId
+    : The file identifier containing the driver.
+
+    pid
+    : The identifier of the model.
+
+    ext
+    : The file extension expected for the file.
+
+    # Type
+
+    ```
+    fetchUgeeDriver :: Attr -> Derivation
+    ```
+
+    # Examples
+
+    ```nix
+    # Ugee M908.
+    fetchUgeeDriver {
+      fileId = "943";
+      pid = "505";
+      hash = "sha256-50Dbyaaa1B8nQu3+tTGvh/yjQqwaARB2MWtKSOUYsKg=";
+      ext = "tar.gz";
+    }
+    ```
+  */
   fetchUgeeDriver = pkgs.callPackage ./fetch-ugee-driver { };
 }

lib/math.nix

@@ -2,24 +2,58 @@
 { pkgs, lib, self }:
 
 rec {
-  /* Returns the absolute value of the given number.
+  /**
+    Returns the absolute value of the given number.
 
-     Example:
+    # Arguments
-       abs -4
-       => 4
 
-       abs (1 / 5)
+    number
-       => 0.2
+    : The numerical value.
+
+    # Type
+
+    ```
+    abs :: Number -> Number
+    ```
+
+    # Examples
+
+    ```nix
+    abs -4
+    => 4
+
+    abs (1 / 5)
+    => 0.2
+    ```
   */
   abs = number: if number < 0 then -(number) else number;
-  /* Exponentiates the given base with the exponent.
 
-     Example:
+  /**
-       pow 2 3
+    Exponentiates the given base with the exponent.
-       => 8
 
-       pow 6 4
+    # Arguments
-       => 1296
+
+    base
+    : The base value.
+
+    exponent
+    : The exponent value.
+
+    # Type
+
+    ```
+    pow :: Integer -> Integer -> Integer
+    ```
+
+    # Examples
+
+    ```nix
+    pow 2 3
+    => 8
+
+    pow 6 4
+    => 1296
+    ```
   */
   pow = base: exponent:
     # Just to be a contrarian, I'll just make this as a tail recursive function

lib/trivial.nix

@@ -1,36 +1,89 @@
 { pkgs, lib, self }:
 
 rec {
-  /* Force a numerical value to be a floating value.
+  /**
+    Force a numerical value to be a floating value.
 
-     Example:
+    # Arguments
-       toFloat 5698
-       => 5698.0
 
-       toFloat 9859.55
+    x
-       => 9859.55
+    : The (numerical) value to be converted.
+
+    # Type
+
+    ```
+    toFloat :: Number -> Float
+    ```
+
+    # Examples
+
+    ```nix
+    toFloat 5698
+    => 5698.0
+
+    toFloat 9859.55
+    => 9859.55
+    ```
   */
   toFloat = x: x / 1.0;
 
-  /* Count the attributes with the given predicate.
+  /**
+    Count the attributes with the given predicate.
 
-     Examples:
+    # Arguments
-       countAttrs (name: value: value) { d = true; f = true; a = false; }
-       => 2
 
-       countAttrs (name: value: value.enable) { d = { enable = true; }; f = { enable = false; package = [ ]; }; }
+    pred
-       => 1
+    : The predicate function to be used per-attribute key-value. Its expected
+    arguments are the attribute key and the attribute value in that order.
+
+    attrs
+    : The attribute set to be used.
+
+    # Type
+
+    ```
+    countAttrs :: Function -> Attr -> Integer
+    ```
+
+    # Examples
+
+    ```nix
+    countAttrs (name: value: value) { d = true; f = true; a = false; }
+    => 2
+
+    countAttrs (name: value: value.enable) { d = { enable = true; }; f = { enable = false; package = [ ]; }; }
+    => 1
+    ```
   */
   countAttrs = pred: attrs:
     lib.count (attr: pred attr.name attr.value)
     (lib.mapAttrsToList lib.nameValuePair attrs);
 
-  /* Filters and groups the attribute set into two separate attribute where it
+  /**
-     either accepted or denied from a given predicate function.
+    Filters and groups the attribute set into two separate attribute where it
+    either accepted or denied from a given predicate function.
 
-     Example:
+    # Arguments
-       filterAttrs' (n: v: v == 4) { a = 4; b = 2; c = 6; }
+
-       => { ok = { a = 4; }; notOk = { b = 2; c = 6; }; }
+    f
+    : The filter function to be used per-attribute. Its expected arguments are
+    the attribute key and the attribute value, in that order.
+
+    attrs
+    : The attribute set to be used.
+
+    # Type
+
+    ```
+    filterAttrs :: Function -> Attr -> Attr
+    ```
+
+    # Example
+
+    ```nix
+    filterAttrs' (n: v: v == 4) { a = 4; b = 2; c = 6; }
+    => { ok = { a = 4; }; notOk = { b = 2; c = 6; }; }
+    ```
   */
   filterAttrs' = f: attrs:
     lib.foldlAttrs (acc: name: value:
@@ -43,22 +96,52 @@ rec {
         notOk = { };
       } attrs;
 
-  /* Convenient function for converting bits to bytes.
+  /**
+    Convenient function for converting bits to bytes.
 
-     Example:
+    # Arguments
-       bitsToBytes 1600
+
-       => 200
+    x
+    : An integer value expected to be the number of bits.
+
+    # Type
+
+    ```
+    bitsToBytes :: Integer -> Integer
+    ```
+
+    # Example
+
+    ```nix
+    bitsToBytes 1600
+    => 200
+    ```
   */
   bitsToBytes = x: x / 8.0;
 
-  /* Gives the exponent with the associated SI prefix.
+  /**
+    Gives the exponent with the associated SI prefix.
 
-     Example:
+    # Arguments
-       SIPrefixExponent "M"
-       => 6
 
-       SIPrefixExponent "Q"
+    c
-       => 30
+    : The SI prefix itself.
+
+    # Type
+
+    ```
+    SIPrefixExponent :: String -> Integer
+    ```
+
+    # Example
+
+    ```nix
+    SIPrefixExponent "M"
+    => 6
+
+    SIPrefixExponent "Q"
+    => 30
+    ```
   */
   SIPrefixExponent = c:
     let
@@ -90,28 +173,45 @@ rec {
       };
     in prefixes.${c};
 
-  /* Gives the multiplier for the metric units.
+  /**
+    Gives the multiplier for the metric units.
 
-     Example:
+    # Arguments
-      metricPrefixMultiplier "M"
-      => 1000000
 
-      metricPrefixMultiplier "G"
+    It has a similar argument to `foodogsquaredLib.trivial.SIPrefixExponent`.
-      => 1000000000
+
+    # Examples
+
+    ```nix
+    metricPrefixMultiplier "M"
+    => 1000000
+
+    metricPrefixMultiplier "G"
+    => 1000000000
+    ```
   */
   metricPrefixMultiplier = c: self.math.pow 10 (SIPrefixExponent c);
 
-  /* Gives the exponent with the associated binary prefix.
+  /**
+    Gives the exponent with the associated binary prefix.
 
-     As an implementation detail, we don't follow the proper IEC unit prefixes
+    As an implementation detail, we don't follow the proper IEC unit prefixes
-     and instead mapping this to the SI prefix for convenience.
+    and instead mapping this to the SI prefix for convenience.
 
-     Example:
+    # Arguments
-       SIPrefixExponent "M"
-       => 6
 
-       SIPrefixExponent "Q"
+    Similar argument to `foodogsquaredLib.trivial.SIPrefixExponent` but only
-       => 30
+    for select SI prefixes instead.
+
+    # Examples
+
+    ```nix
+    SIPrefixExponent "M"
+    => 6
+
+    SIPrefixExponent "Q"
+    => 30
+    ```
   */
   binaryPrefixExponent = c:
     let
@@ -127,30 +227,48 @@ rec {
       };
     in prefixes.${c};
 
-  /* Gives the multiplier for the given byte unit. Essentially returns the
+  /**
-     value in number of bytes.
+    Gives the multiplier for the given byte unit. Essentially returns the
+    value in number of bytes.
 
-     Example:
+    # Argument
-       binaryPrefixMultiplier "M"
-       => 1048576
 
-       binaryPrefixMultiplier "G"
+    Similar argument to `foodogsquaredLib.trivial.binaryPrefixExponent`.
-       => 1.099511628×10¹²
+
+    # Examples
+
+    ```nix
+    binaryPrefixMultiplier "M"
+    => 1048576
+
+    binaryPrefixMultiplier "G"
+    => 1.099511628×10¹²
+    ```
   */
   binaryPrefixMultiplier = c: self.math.pow 2 (binaryPrefixExponent c);
 
-  /* Parse the given string containing the size into its appropriate value.
+  /**
-     Returns the value in number of bytes.
+    Parse the given string containing the size into its appropriate value.
+    Returns the value in number of bytes.
 
-     Example:
+    # Arguments
-      parseBytesSizeIntoInt "4GiB"
-      => 4294967296
 
-      parseBytesSizeIntoInt "2 MB"
+    str
-      => 2000000
+    : The string expecting to contain an integer and its suffix (e.g., `4GiB`,
+    `2 Mb`). Whitespace characters in between them is accepted.
 
-      parseBytesSizeIntoInt "2 Mb"
+    # Examples
-      => 250000
+
+    ```nix
+    parseBytesSizeIntoInt "4GiB"
+    => 4294967296
+
+    parseBytesSizeIntoInt "2 MB"
+    => 2000000
+
+    parseBytesSizeIntoInt "2 Mb"
+    => 250000
+    ```
   */
   parseBytesSizeIntoInt = str:
     let
@@ -169,14 +287,32 @@ rec {
       bitDivider = if lib.hasSuffix "b" suffix then 8 else 1;
     in numeral * multiplier / bitDivider;
 
-  /* Given an attrset of unit size object, return the size in bytes.
+  /**
+    Given an attrset of unit size object, return the size in bytes.
 
-     Example:
+    # Arguments
-       unitsToInt { size = 4; prefix = "G"; type = "binary"; }
-       => 4294967296
 
-       unitsToInt { size = 4; prefix = "G"; type = "metric"; }
+    It is a sole attribute set with the following attributes:
-       => 4000000000
+
+    size
+    : An integer value representing the numerical value of the unit.
+
+    prefix
+    : The SI prefix similar to `foodogsquaredLib.trivial.SIPrefixExponent`.
+
+    type
+    : Indicates the type of multiplier to be used. Only accepts `binary` and
+    `metric` as the value.
+
+    # Examples
+
+    ```nix
+    unitsToInt { size = 4; prefix = "G"; type = "binary"; }
+    => 4294967296
+
+    unitsToInt { size = 4; prefix = "G"; type = "metric"; }
+    => 4000000000
+    ```
   */
   unitsToInt = { size, prefix, type ? "binary" }:
     let