From 055ba65fed8eac15b13ed68f70a7d506f9b2d291 Mon Sep 17 00:00:00 2001
From: Silvan Mosberger <silvan.mosberger@tweag.io>
Date: Mon, 20 Nov 2023 03:02:11 +0100
Subject: [PATCH] lib: Take advantage of section descriptions

See https://github.com/nix-community/nixdoc/releases/tag/v2.6.0
---
 lib/attrsets.nix     |  2 +-
 lib/filesystem.nix   |  6 ++++--
 lib/gvariant.nix     | 19 ++++++++++---------
 lib/lists.nix        |  3 +--
 lib/options.nix      |  2 +-
 lib/path/default.nix |  3 ++-
 lib/sources.nix      |  2 +-
 7 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/lib/attrsets.nix b/lib/attrsets.nix
index b0460ab139e8..bf6c90bf1be6 100644
--- a/lib/attrsets.nix
+++ b/lib/attrsets.nix
@@ -1,5 +1,5 @@
+/* Operations on attribute sets. */
 { lib }:
-# Operations on attribute sets.
 
 let
   inherit (builtins) head tail length;
diff --git a/lib/filesystem.nix b/lib/filesystem.nix
index f5bb8e9b5950..5569b8ac80fd 100644
--- a/lib/filesystem.nix
+++ b/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
diff --git a/lib/gvariant.nix b/lib/gvariant.nix
index 3142ffc5f149..708213224d3e 100644
--- a/lib/gvariant.nix
+++ b/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;
diff --git a/lib/lists.nix b/lib/lists.nix
index 15047f488f4d..a56667ec9c38 100644
--- a/lib/lists.nix
+++ b/lib/lists.nix
@@ -1,5 +1,4 @@
-# General list operations.
-
+/* General list operations. */
 { lib }:
 let
   inherit (lib.strings) toInt;
diff --git a/lib/options.nix b/lib/options.nix
index 7821924873dc..9c10dfc8b36a 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -1,4 +1,4 @@
-# Nixpkgs/NixOS option handling.
+/* Nixpkgs/NixOS option handling. */
 { lib }:
 
 let
diff --git a/lib/path/default.nix b/lib/path/default.nix
index 1a55a2a7be8d..ab8a9e2202e9 100644
--- a/lib/path/default.nix
+++ b/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
 
diff --git a/lib/sources.nix b/lib/sources.nix
index 8b7cd5c84f62..f61ea306aec5 100644
--- a/lib/sources.nix
+++ b/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