diff --git a/pkgs/build-support/writers/scripts.nix b/pkgs/build-support/writers/scripts.nix
index e882c917688b..81a88391f324 100644
--- a/pkgs/build-support/writers/scripts.nix
+++ b/pkgs/build-support/writers/scripts.nix
@@ -297,25 +297,36 @@ rec {
         ln -s ${inner}/bin/${name} $out
       '';
 
-  # Like writeScript but the first line is a shebang to bash
-  #
-  # Can be called with or without extra arguments.
-  #
-  # Example without arguments:
-  #   writeBash "example" ''
-  #     echo hello world
-  #   ''
-  #
-  # Example with arguments:
-  #   writeBash "example"
-  #     {
-  #       makeWrapperArgs = [
-  #         "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
-  #       ];
-  #     }
-  #     ''
-  #       hello
-  #     ''
+  /**
+    Like writeScript but the first line is a shebang to bash
+    Can be called with or without extra arguments.
+
+    # Examples
+    :::{.example}
+
+    ## Without arguments
+
+    ```nix
+    writeBash "example" ''
+    echo hello world
+    ''
+    ```
+
+    ## With arguments
+
+    ```nix
+    writeBash "example"
+    {
+      makeWrapperArgs = [
+        "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
+      ];
+    }
+    ''
+      hello
+    ''
+    ```
+    :::
+  */
   writeBash =
     name: argsOrScript:
     if lib.isAttrs argsOrScript && !lib.isDerivation argsOrScript then
@@ -323,46 +334,72 @@ rec {
     else
       makeScriptWriter { interpreter = "${lib.getExe pkgs.bash}"; } name argsOrScript;
 
-  # Like writeScriptBin but the first line is a shebang to bash
-  #
-  # Can be called with or without extra arguments.
-  #
-  # Example without arguments:
-  #   writeBashBin "example" ''
-  #     echo hello world
-  #   ''
-  #
-  # Example with arguments:
-  #  writeBashBin "example"
-  #    {
-  #      makeWrapperArgs = [
-  #        "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
-  #      ];
-  #    }
-  #    ''
-  #      hello
-  #    ''
+  /**
+    Like writeScriptBin but the first line is a shebang to bash
+
+    Can be called with or without extra arguments.
+
+    ## Examples
+    :::{.example}
+    ## `pkgs.writers.writeBashBin` example without arguments
+
+    ```nix
+    writeBashBin "example" ''
+      echo hello world
+    ''
+    ```
+    :::
+
+    :::{.example}
+    ## `pkgs.writers.writeBashBin` example with arguments
+
+    ```nix
+    writeBashBin "example"
+    {
+      makeWrapperArgs = [
+        "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
+      ];
+    }
+    ''
+      hello
+    ''
+    ```
+    :::
+  */
   writeBashBin = name: writeBash "/bin/${name}";
 
-  # Like writeScript but the first line is a shebang to dash
-  #
-  # Can be called with or without extra arguments.
-  #
-  # Example without arguments:
-  #   writeDash "example" ''
-  #     echo hello world
-  #   ''
-  #
-  # Example with arguments:
-  #   writeDash "example"
-  #     {
-  #       makeWrapperArgs = [
-  #         "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
-  #       ];
-  #     }
-  #     ''
-  #       hello
-  #     ''
+  /**
+    Like writeScript but the first line is a shebang to dash
+
+    Can be called with or without extra arguments.
+
+    # Example
+    :::{.example}
+    ## `pkgs.writers.writeDash` example without arguments
+
+    ```nix
+    writeDash "example" ''
+      echo hello world
+    ''
+    ```
+    :::
+
+    :::{.example}
+    ## `pkgs.writers.writeDash` example with arguments
+
+    ```nix
+    writeDash "example"
+    {
+      makeWrapperArgs = [
+        "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
+      ];
+    }
+    ''
+      hello
+    ''
+    ```
+    :::
+  */
   writeDash =
     name: argsOrScript:
     if lib.isAttrs argsOrScript && !lib.isDerivation argsOrScript then
@@ -370,46 +407,71 @@ rec {
     else
       makeScriptWriter { interpreter = "${lib.getExe pkgs.dash}"; } name argsOrScript;
 
-  # Like writeScriptBin but the first line is a shebang to dash
-  #
-  # Can be called with or without extra arguments.
-  #
-  # Example without arguments:
-  #   writeDashBin "example" ''
-  #     echo hello world
-  #   ''
-  #
-  # Example with arguments:
-  #  writeDashBin "example"
-  #    {
-  #      makeWrapperArgs = [
-  #        "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
-  #      ];
-  #    }
-  #    ''
-  #      hello
-  #    ''
+  /**
+    Like writeScriptBin but the first line is a shebang to dash
+
+    Can be called with or without extra arguments.
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writeDashBin` without arguments
+
+    ```nix
+    writeDashBin "example" ''
+      echo hello world
+    ''
+    ```
+    :::
+
+    :::{.example}
+    ## `pkgs.writers.writeDashBin` with arguments
+
+    ```nix
+    writeDashBin "example"
+    {
+      makeWrapperArgs = [
+        "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
+      ];
+    }
+    ''
+      hello
+    ''
+    ```
+    :::
+  */
   writeDashBin = name: writeDash "/bin/${name}";
 
-  # Like writeScript but the first line is a shebang to fish
-  #
-  # Can be called with or without extra arguments.
-  #
-  # Example without arguments:
-  #   writeFish "example" ''
-  #     echo hello world
-  #   ''
-  #
-  # Example with arguments:
-  #   writeFish "example"
-  #     {
-  #       makeWrapperArgs = [
-  #         "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
-  #       ];
-  #     }
-  #     ''
-  #       hello
-  #     ''
+  /**
+    Like writeScript but the first line is a shebang to fish
+
+    Can be called with or without extra arguments.
+
+    :::{.example}
+    ## `pkgs.writers.writeFish` without arguments
+
+    ```nix
+    writeFish "example" ''
+      echo hello world
+    ''
+    ```
+    :::
+
+    :::{.example}
+    ## `pkgs.writers.writeFish` with arguments
+
+    ```nix
+    writeFish "example"
+    {
+      makeWrapperArgs = [
+        "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
+      ];
+    }
+    ''
+      hello
+    ''
+    ```
+    :::
+  */
   writeFish =
     name: argsOrScript:
     if lib.isAttrs argsOrScript && !lib.isDerivation argsOrScript then
@@ -426,36 +488,57 @@ rec {
         check = "${lib.getExe pkgs.fish} --no-config --no-execute"; # syntax check only
       } name argsOrScript;
 
-  # Like writeScriptBin but the first line is a shebang to fish
-  #
-  # Can be called with or without extra arguments.
-  #
-  # Example without arguments:
-  #   writeFishBin "example" ''
-  #     echo hello world
-  #   ''
-  #
-  # Example with arguments:
-  #   writeFishBin "example"
-  #     {
-  #       makeWrapperArgs = [
-  #         "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
-  #       ];
-  #     }
-  #     ''
-  #       hello
-  #     ''
+  /**
+    Like writeScriptBin but the first line is a shebang to fish
+
+    Can be called with or without extra arguments.
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writeFishBin` without arguments
+
+    ```nix
+    writeFishBin "example" ''
+      echo hello world
+    ''
+    ```
+    :::
+
+    :::{.example}
+    ## `pkgs.writers.writeFishBin` with arguments
+
+    ```nix
+    writeFishBin "example"
+    {
+      makeWrapperArgs = [
+        "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
+      ];
+    }
+    ''
+      hello
+    ''
+    ```
+    :::
+  */
   writeFishBin = name: writeFish "/bin/${name}";
 
-  # writeHaskell takes a name, an attrset with libraries and haskell version (both optional)
-  # and some haskell source code and returns an executable.
-  #
-  # Example:
-  #   writeHaskell "missiles" { libraries = [ pkgs.haskellPackages.acme-missiles ]; } ''
-  #     import Acme.Missiles
-  #
-  #     main = launchMissiles
-  #   '';
+  /**
+    writeHaskell takes a name, an attrset with libraries and haskell version (both optional)
+    and some haskell source code and returns an executable.
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writeHaskell` usage example
+
+    ```nix
+    writeHaskell "missiles" { libraries = [ pkgs.haskellPackages.acme-missiles ]; } ''
+      import Acme.Missiles
+
+      main = launchMissiles
+    '';
+    ```
+    :::
+  */
   writeHaskell =
     name:
     {
@@ -480,28 +563,43 @@ rec {
       inherit makeWrapperArgs strip;
     } name;
 
-  # writeHaskellBin takes the same arguments as writeHaskell but outputs a directory (like writeScriptBin)
+  /**
+    writeHaskellBin takes the same arguments as writeHaskell but outputs a directory (like writeScriptBin)
+  */
   writeHaskellBin = name: writeHaskell "/bin/${name}";
 
-  # Like writeScript but the first line is a shebang to nu
-  #
-  # Can be called with or without extra arguments.
-  #
-  # Example without arguments:
-  #   writeNu "example" ''
-  #     echo hello world
-  #   ''
-  #
-  # Example with arguments:
-  #   writeNu "example"
-  #     {
-  #       makeWrapperArgs = [
-  #         "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
-  #       ];
-  #     }
-  #     ''
-  #       hello
-  #     ''
+  /**
+    Like writeScript but the first line is a shebang to nu
+
+    Can be called with or without extra arguments.
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writeNu` without arguments
+
+    ```nix
+    writeNu "example" ''
+      echo hello world
+    ''
+    ```
+    :::
+
+    :::{.example}
+    ## `pkgs.writers.writeNu` with arguments
+
+    ```nix
+    writeNu "example"
+      {
+        makeWrapperArgs = [
+          "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
+        ];
+      }
+      ''
+        hello
+      ''
+    ```
+    :::
+  */
   writeNu =
     name: argsOrScript:
     if lib.isAttrs argsOrScript && !lib.isDerivation argsOrScript then
@@ -511,29 +609,44 @@ rec {
     else
       makeScriptWriter { interpreter = "${lib.getExe pkgs.nushell} --no-config-file"; } name argsOrScript;
 
-  # Like writeScriptBin but the first line is a shebang to nu
-  #
-  # Can be called with or without extra arguments.
-  #
-  # Example without arguments:
-  #   writeNuBin "example" ''
-  #     echo hello world
-  #   ''
-  #
-  # Example with arguments:
-  #   writeNuBin "example"
-  #     {
-  #       makeWrapperArgs = [
-  #         "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
-  #       ];
-  #     }
-  #    ''
-  #      hello
-  #    ''
+  /**
+    Like writeScriptBin but the first line is a shebang to nu
+
+    Can be called with or without extra arguments.
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writeNuBin` without arguments
+
+    ```nix
+    writeNuBin "example" ''
+      echo hello world
+    ''
+    ```
+    :::
+
+    :::{.example}
+    ## `pkgs.writers.writeNuBin` with arguments
+
+    ```nix
+    writeNuBin "example"
+      {
+        makeWrapperArgs = [
+          "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
+        ];
+      }
+      ''
+        hello
+      ''
+    ```
+    :::
+  */
   writeNuBin = name: writeNu "/bin/${name}";
 
-  # makeRubyWriter takes ruby and compatible rubyPackages and produces ruby script writer,
-  # If any libraries are specified, ruby.withPackages is used as interpreter, otherwise the "bare" ruby is used.
+  /**
+    makeRubyWriter takes ruby and compatible rubyPackages and produces ruby script writer,
+    If any libraries are specified, ruby.withPackages is used as interpreter, otherwise the "bare" ruby is used.
+  */
   makeRubyWriter =
     ruby: rubyPackages: buildRubyPackages: name:
     {
@@ -552,19 +665,30 @@ rec {
       }
     ) name;
 
-  # Like writeScript but the first line is a shebang to ruby
-  #
-  # Example:
-  #   writeRuby "example" { libraries = [ pkgs.rubyPackages.git ]; } ''
-  #    puts "hello world"
-  #   ''
+  /**
+    Like writeScript but the first line is a shebang to ruby
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writeRuby` usage example
+
+    ```nix
+    writeRuby "example" { libraries = [ pkgs.rubyPackages.git ]; } ''
+     puts "hello world"
+    ''
+    ```
+
+    :::
+  */
   writeRuby = makeRubyWriter pkgs.ruby pkgs.rubyPackages buildPackages.rubyPackages;
 
   writeRubyBin = name: writeRuby "/bin/${name}";
 
-  # makeLuaWriter takes lua and compatible luaPackages and produces lua script writer,
-  # which validates the script with luacheck at build time. If any libraries are specified,
-  # lua.withPackages is used as interpreter, otherwise the "bare" lua is used.
+  /**
+    makeLuaWriter takes lua and compatible luaPackages and produces lua script writer,
+    which validates the script with luacheck at build time. If any libraries are specified,
+    lua.withPackages is used as interpreter, otherwise the "bare" lua is used.
+  */
   makeLuaWriter =
     lua: luaPackages: buildLuaPackages: name:
     {
@@ -587,26 +711,35 @@ rec {
       }
     ) name;
 
-  # writeLua takes a name an attributeset with libraries and some lua source code and
-  # returns an executable (should also work with luajit)
-  #
-  # Example:
-  # writeLua "test_lua" { libraries = [ pkgs.luaPackages.say ]; } ''
-  #   s = require("say")
-  #   s:set_namespace("en")
-  #
-  #   s:set('money', 'I have %s dollars')
-  #   s:set('wow', 'So much money!')
-  #
-  #   print(s('money', {1000})) -- I have 1000 dollars
-  #
-  #   s:set_namespace("fr") -- switch to french!
-  #   s:set('wow', "Tant d'argent!")
-  #
-  #   print(s('wow')) -- Tant d'argent!
-  #   s:set_namespace("en")  -- switch back to english!
-  #   print(s('wow')) -- So much money!
-  # ''
+  /**
+    writeLua takes a name an attributeset with libraries and some lua source code and
+    returns an executable (should also work with luajit)
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writeLua` usage example
+
+    ```nix
+    writeLua "test_lua" { libraries = [ pkgs.luaPackages.say ]; } ''
+      s = require("say")
+      s:set_namespace("en")
+
+      s:set('money', 'I have %s dollars')
+      s:set('wow', 'So much money!')
+
+      print(s('money', {1000})) -- I have 1000 dollars
+
+      s:set_namespace("fr") -- switch to french!
+      s:set('wow', "Tant d'argent!")
+
+      print(s('wow')) -- Tant d'argent!
+      s:set_namespace("en")  -- switch back to english!
+      print(s('wow')) -- So much money!
+    ''
+    ```
+
+    :::
+  */
   writeLua = makeLuaWriter pkgs.lua pkgs.luaPackages buildPackages.luaPackages;
 
   writeLuaBin = name: writeLua "/bin/${name}";
@@ -632,16 +765,39 @@ rec {
 
   writeRustBin = name: writeRust "/bin/${name}";
 
-  # writeJS takes a name an attributeset with libraries and some JavaScript sourcecode and
-  # returns an executable
-  #
-  # Example:
-  #   writeJS "example" { libraries = [ pkgs.uglify-js ]; } ''
-  #     var UglifyJS = require("uglify-js");
-  #     var code = "function add(first, second) { return first + second; }";
-  #     var result = UglifyJS.minify(code);
-  #     console.log(result.code);
-  #   ''
+  /**
+    writeJS takes a name an attributeset with libraries and some JavaScript sourcecode and
+    returns an executable
+
+    # Inputs
+
+    `name`
+
+    : 1\. Function argument
+
+    `attrs`
+
+    : 2\. Function argument
+
+    `content`
+
+    : 3\. Function argument
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writeJS` usage example
+
+    ```nix
+    writeJS "example" { libraries = [ pkgs.uglify-js ]; } ''
+      var UglifyJS = require("uglify-js");
+      var code = "function add(first, second) { return first + second; }";
+      var result = UglifyJS.minify(code);
+      console.log(result.code);
+    ''
+    ```
+
+    :::
+  */
   writeJS =
     name:
     {
@@ -660,7 +816,9 @@ rec {
       exec ${lib.getExe pkgs.nodejs} ${pkgs.writeText "js" content} "$@"
     '';
 
-  # writeJSBin takes the same arguments as writeJS but outputs a directory (like writeScriptBin)
+  /**
+    writeJSBin takes the same arguments as writeJS but outputs a directory (like writeScriptBin)
+  */
   writeJSBin = name: writeJS "/bin/${name}";
 
   awkFormatNginx = builtins.toFile "awkFormat-nginx.awk" ''
@@ -685,14 +843,23 @@ rec {
         gixy $out
       '';
 
-  # writePerl takes a name an attributeset with libraries and some perl sourcecode and
-  # returns an executable
-  #
-  # Example:
-  #   writePerl "example" { libraries = [ pkgs.perlPackages.boolean ]; } ''
-  #     use boolean;
-  #     print "Howdy!\n" if true;
-  #   ''
+  /**
+    writePerl takes a name an attributeset with libraries and some perl sourcecode and
+    returns an executable
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writePerl` usage example
+
+    ```nix
+    writePerl "example" { libraries = [ pkgs.perlPackages.boolean ]; } ''
+      use boolean;
+      print "Howdy!\n" if true;
+    ''
+    ```
+
+    :::
+  */
   writePerl =
     name:
     {
@@ -706,12 +873,38 @@ rec {
       }
     ) name;
 
-  # writePerlBin takes the same arguments as writePerl but outputs a directory (like writeScriptBin)
+  /**
+    writePerlBin takes the same arguments as writePerl but outputs a directory (like writeScriptBin)
+  */
   writePerlBin = name: writePerl "/bin/${name}";
 
-  # makePythonWriter takes python and compatible pythonPackages and produces python script writer,
-  # which validates the script with flake8 at build time. If any libraries are specified,
-  # python.withPackages is used as interpreter, otherwise the "bare" python is used.
+  /**
+    makePythonWriter takes python and compatible pythonPackages and produces python script writer,
+    which validates the script with flake8 at build time. If any libraries are specified,
+    python.withPackages is used as interpreter, otherwise the "bare" python is used.
+
+    # Inputs
+
+    `python`
+
+    : 1\. Function argument
+
+    `pythonPackages`
+
+    : 2\. Function argument
+
+    `buildPythonPackages`
+
+    : 3\. Function argument
+
+    `name`
+
+    : 4\. Function argument
+
+    `attrs`
+
+    : 5\. Function argument
+  */
   makePythonWriter =
     python: pythonPackages: buildPythonPackages: name:
     {
@@ -745,55 +938,86 @@ rec {
       }
     ) name;
 
-  # writePyPy2 takes a name an attributeset with libraries and some pypy2 sourcecode and
-  # returns an executable
-  #
-  # Example:
-  # writePyPy2 "test_pypy2" { libraries = [ pkgs.pypy2Packages.enum ]; } ''
-  #   from enum import Enum
-  #
-  #   class Test(Enum):
-  #       a = "success"
-  #
-  #   print Test.a
-  # ''
+  /**
+    writePyPy2 takes a name an attributeset with libraries and some pypy2 sourcecode and
+    returns an executable
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writePyPy2` usage example
+
+    ```nix
+    writePyPy2 "test_pypy2" { libraries = [ pkgs.pypy2Packages.enum ]; } ''
+      from enum import Enum
+
+      class Test(Enum):
+          a = "success"
+
+      print Test.a
+    ''
+    ```
+
+    :::
+  */
   writePyPy2 = makePythonWriter pkgs.pypy2 pkgs.pypy2Packages buildPackages.pypy2Packages;
 
-  # writePyPy2Bin takes the same arguments as writePyPy2 but outputs a directory (like writeScriptBin)
+  /**
+    writePyPy2Bin takes the same arguments as writePyPy2 but outputs a directory (like writeScriptBin)
+  */
   writePyPy2Bin = name: writePyPy2 "/bin/${name}";
 
-  # writePython3 takes a name an attributeset with libraries and some python3 sourcecode and
-  # returns an executable
-  #
-  # Example:
-  # writePython3 "test_python3" { libraries = [ pkgs.python3Packages.pyyaml ]; } ''
-  #   import yaml
-  #
-  #   y = yaml.safe_load("""
-  #     - test: success
-  #   """)
-  #   print(y[0]['test'])
-  # ''
+  /**
+    writePython3 takes a name an attributeset with libraries and some python3 sourcecode and
+    returns an executable
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writePython3` usage example
+
+    ```nix
+    writePython3 "test_python3" { libraries = [ pkgs.python3Packages.pyyaml ]; } ''
+      import yaml
+
+      y = yaml.safe_load("""
+        - test: success
+      """)
+      print(y[0]['test'])
+    ''
+    ```
+
+    :::
+  */
   writePython3 = makePythonWriter pkgs.python3 pkgs.python3Packages buildPackages.python3Packages;
 
   # writePython3Bin takes the same arguments as writePython3 but outputs a directory (like writeScriptBin)
   writePython3Bin = name: writePython3 "/bin/${name}";
 
-  # writePyPy3 takes a name an attributeset with libraries and some pypy3 sourcecode and
-  # returns an executable
-  #
-  # Example:
-  # writePyPy3 "test_pypy3" { libraries = [ pkgs.pypy3Packages.pyyaml ]; } ''
-  #   import yaml
-  #
-  #   y = yaml.safe_load("""
-  #     - test: success
-  #   """)
-  #   print(y[0]['test'])
-  # ''
+  /**
+    writePyPy3 takes a name an attributeset with libraries and some pypy3 sourcecode and
+    returns an executable
+
+    # Examples
+    :::{.example}
+    ## `pkgs.writers.writePyPy3` usage example
+
+    ```nix
+    writePyPy3 "test_pypy3" { libraries = [ pkgs.pypy3Packages.pyyaml ]; } ''
+      import yaml
+
+      y = yaml.safe_load("""
+        - test: success
+      """)
+      print(y[0]['test'])
+    ''
+    ```
+
+    :::
+  */
   writePyPy3 = makePythonWriter pkgs.pypy3 pkgs.pypy3Packages buildPackages.pypy3Packages;
 
-  # writePyPy3Bin takes the same arguments as writePyPy3 but outputs a directory (like writeScriptBin)
+  /**
+    writePyPy3Bin takes the same arguments as writePyPy3 but outputs a directory (like writeScriptBin)
+  */
   writePyPy3Bin = name: writePyPy3 "/bin/${name}";
 
   makeFSharpWriter =