feat: convert comments to doc comments

snowfall-lib/flake/default.nix

@@ -9,29 +9,52 @@ let
 in
 rec {
   flake = rec {
-    # Remove the `self` attribute from an attribute set.
-    # Type: Attrs -> Attrs
-    # Usage: without-self { self = {}; x = true; }
-    #   result: { x = true; }
+    ## Remove the `self` attribute from an attribute set.
+    ## Example Usage:
+    ## ```nix
+    ## without-self { self = {}; x = true; }
+    ## ```
+    ## Result:
+    ## ```nix
+    ## { x = true; }
+    ## ```
+    #@ Attrs -> Attrs
     without-self = flake-inputs: builtins.removeAttrs flake-inputs [ "self" ];
 
-    # Remove the `src` attribute from an attribute set.
-    # Type: Attrs -> Attrs
-    # Usage: without-src { src = ./.; x = true; }
-    #   result: { x = true; }
+    ## Remove the `src` attribute from an attribute set.
+    ## Example Usage:
+    ## ```nix
+    ## without-src { src = ./.; x = true; }
+    ## ```
+    ## Result:
+    ## ```nix
+    ## { x = true; }
+    ## ```
+    #@ Attrs -> Attrs
     without-src = flake-inputs: builtins.removeAttrs flake-inputs [ "src" ];
 
-    # Remove the `src` and `self` attributes from an attribute set.
-    # Type: Attrs -> Attrs
-    # Usage: without-snowfall-inputs { self = {}; src = ./.; x = true; }
-    #   result: { x = true; }
+    ## Remove the `src` and `self` attributes from an attribute set.
+    ## Example Usage:
+    ## ```nix
+    ## without-snowfall-inputs { self = {}; src = ./.; x = true; }
+    ## ```
+    ## Result:
+    ## ```nix
+    ## { x = true; }
+    ## ```
+    #@ Attrs -> Attrs
     without-snowfall-inputs = snowfall-lib.fp.compose without-self without-src;
 
-    # Remove Snowfall-specific attributes so the rest can be safely
-    # passed to flake-utils-plus.
-    # Type: Attrs -> Attrs
-    # Usage: without-snowfall-options { src = ./.; x = true; }
-    #   result: { x = true; }
+    ## Remove Snowfall-specific attributes so the rest can be safely passed to flake-utils-plus.
+    ## Example Usage:
+    ## ```nix
+    ## without-snowfall-options { src = ./.; x = true; }
+    ## ```
+    ## Result:
+    ## ```nix
+    ## { x = true; }
+    ## ```
+    #@ Attrs -> Attrs
     without-snowfall-options = flake-options:
       builtins.removeAttrs
         flake-options
@@ -51,12 +74,16 @@ rec {
           "snowfall"
         ];
 
-    # Transform an attribute set of inputs into an attribute set where
-    # the values are the inputs' `lib` attribute. Entries without a `lib`
-    # attribute are removed.
-    # Type: Attrs -> Attrs
-    # Usage: get-lib { x = nixpkgs; y = {}; }
-    #   result: { x = nixpkgs.lib; }
+    ## Transform an attribute set of inputs into an attribute set where the values are the inputs' `lib` attribute. Entries without a `lib` attribute are removed.
+    ## Example Usage:
+    ## ```nix
+    ## get-lib { x = nixpkgs; y = {}; }
+    ## ```
+    ## Result:
+    ## ```nix
+    ## { x = nixpkgs.lib; }
+    ## ```
+    #@ Attrs -> Attrs
     get-libs = attrs:
       let
         # @PERF(jakehamilton): Replace filter+map with a fold.