lib: Take advantage of section descriptions

See https://github.com/nix-community/nixdoc/releases/tag/v2.6.0

lib/attrsets.nix

@@ -1,5 +1,5 @@
+/* Operations on attribute sets. */
 { lib }:
-# Operations on attribute sets.
 
 let
   inherit (builtins) head tail length;

lib/filesystem.nix

@@ -1,5 +1,7 @@
-# Functions for querying information about the filesystem
+/*
-# without copying any files to the Nix store.
+  Functions for querying information about the filesystem
+  without copying any files to the Nix store.
+*/
 { lib }:
 
 # Tested in lib/tests/filesystem.sh

lib/gvariant.nix

@@ -1,16 +1,17 @@
+/*
+  A partial and basic implementation of GVariant formatted strings.
+  See [GVariant Format Strings](https://docs.gtk.org/glib/gvariant-format-strings.html) for details.
+
+  :::{.warning}
+  This API is not considered fully stable and it might therefore
+  change in backwards incompatible ways without prior notice.
+  :::
+*/
+
 # This file is based on https://github.com/nix-community/home-manager
 # Copyright (c) 2017-2022 Home Manager contributors
-#
-
-
 { lib }:
 
-/* A partial and basic implementation of GVariant formatted strings.
-   See https://docs.gtk.org/glib/gvariant-format-strings.html for detauls.
-
-   Note, this API is not considered fully stable and it might therefore
-   change in backwards incompatible ways without prior notice.
-*/
 let
   inherit (lib)
     concatMapStringsSep concatStrings escape head replaceStrings;

lib/lists.nix

@@ -1,5 +1,4 @@
-# General list operations.
+/* General list operations. */
-
 { lib }:
 let
   inherit (lib.strings) toInt;

lib/options.nix

@@ -1,4 +1,4 @@
-# Nixpkgs/NixOS option handling.
+/* Nixpkgs/NixOS option handling. */
 { lib }:
 
 let

lib/path/default.nix

@@ -1,4 +1,5 @@
-# Functions for working with paths, see ./path.md
+/* Functions for working with path values. */
+# See ./README.md for internal docs
 { lib }:
 let
 

lib/sources.nix

@@ -1,4 +1,4 @@
-# Functions for copying sources to the Nix store.
+/* Functions for copying sources to the Nix store. */
 { lib }:
 
 # Tested in lib/tests/sources.sh