From 54658a47d04f10182ae428733c0c44d15f61cf95 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Thu, 29 Feb 2024 10:38:03 +0100
Subject: [PATCH] doc: improve pkgs.writers comments

---
 pkgs/build-support/writers/data.nix | 81 ++++++++++++++++++-----------
 1 file changed, 51 insertions(+), 30 deletions(-)

diff --git a/pkgs/build-support/writers/data.nix b/pkgs/build-support/writers/data.nix
index 45ed5360eaeb..02f08b9ca0b6 100644
--- a/pkgs/build-support/writers/data.nix
+++ b/pkgs/build-support/writers/data.nix
@@ -1,28 +1,34 @@
-{ lib, pkgs, formats, runCommand, dasel }:
+{ lib, pkgs, formats, runCommand }:
 let
-  daselBin = lib.getExe dasel;
-
   inherit (lib)
     last
     optionalString
     types
     ;
 in
-rec {
-  # Creates a transformer function that writes input data to disk, transformed
-  # by both the `input` and `output` arguments.
-  #
-  # Type: makeDataWriter :: input -> output -> nameOrPath -> data -> (any -> string) -> string -> string -> any -> derivation
-  #
-  #   input :: T -> string: function that takes the nix data and returns a string
-  #   output :: string: script that takes the $inputFile and write the result into $out
-  #   nameOrPath :: string: if the name contains a / the files gets written to a sub-folder of $out. The derivation name is the basename of this argument.
-  #   data :: T: the data that will be converted.
-  #
-  # Example:
-  #   writeJSON = makeDataWriter { input = builtins.toJSON; output = "cp $inputPath $out"; };
-  #   myConfig = writeJSON "config.json" { hello = "world"; }
-  #
+{
+  /**
+    Creates a transformer function that writes input data to disk, transformed
+    by both the `input` and `output` arguments.
+
+    # Example
+
+    ```nix
+    writeJSON = makeDataWriter { input = builtins.toJSON; output = "cp $inputPath $out"; };
+    myConfig = writeJSON "config.json" { hello = "world"; }
+    ```
+
+    # Type
+
+    ```
+    makeDataWriter :: input -> output -> nameOrPath -> data -> (any -> string) -> string -> string -> any -> derivation
+
+    input :: T -> string: function that takes the nix data and returns a string
+    output :: string: script that takes the $inputFile and write the result into $out
+    nameOrPath :: string: if the name contains a / the files gets written to a sub-folder of $out. The derivation name is the basename of this argument.
+    data :: T: the data that will be converted.
+    ```
+  */
   makeDataWriter = lib.warn "pkgs.writers.makeDataWriter is deprecated. Use pkgs.writeTextFile." ({ input ? lib.id, output ? "cp $inputPath $out" }: nameOrPath: data:
     assert lib.or (types.path.check nameOrPath) (builtins.match "([0-9A-Za-z._])[0-9A-Za-z._-]*" nameOrPath != null);
     let
@@ -44,21 +50,36 @@ rec {
 
   inherit (pkgs) writeText;
 
-  # Writes the content to a JSON file.
-  #
-  # Example:
-  #   writeJSON "data.json" { hello = "world"; }
+  /**
+    Writes the content to a JSON file.
+
+    # Example
+
+    ```nix
+    writeJSON "data.json" { hello = "world"; }
+    ```
+  */
   writeJSON = (pkgs.formats.json {}).generate;
 
-  # Writes the content to a TOML file.
-  #
-  # Example:
-  #   writeTOML "data.toml" { hello = "world"; }
+  /**
+    Writes the content to a TOML file.
+
+    # Example
+
+    ```nix
+    writeTOML "data.toml" { hello = "world"; }
+    ```
+  */
   writeTOML = (pkgs.formats.toml {}).generate;
 
-  # Writes the content to a YAML file.
-  #
-  # Example:
-  #   writeYAML "data.yaml" { hello = "world"; }
+  /**
+    Writes the content to a YAML file.
+
+    # Example
+
+    ```nix
+    writeYAML "data.yaml" { hello = "world"; }
+    ```
+  */
   writeYAML = (pkgs.formats.yaml {}).generate;
 }