From 47c33cfae1216636da1ae4890fddc2efc0969fba Mon Sep 17 00:00:00 2001
From: anntnzrb <anntnzrb@proton.me>
Date: Wed, 8 Oct 2025 23:11:44 -0500
Subject: [PATCH] docs: add comments explaining unsafeDiscardStringContext
 usage

Add clear documentation for all uses of unsafeDiscardStringContext,
explaining that it's necessary when building flake outputs based on
file paths, as Nix doesn't allow using paths as attribute names directly.
---
 snowfall-lib/checks/default.nix  | 2 ++
 snowfall-lib/module/default.nix  | 2 ++
 snowfall-lib/overlay/default.nix | 4 ++++
 snowfall-lib/shell/default.nix   | 2 ++
 4 files changed, 10 insertions(+)

diff --git a/snowfall-lib/checks/default.nix b/snowfall-lib/checks/default.nix
index 8a5efde..1c203f5 100644
--- a/snowfall-lib/checks/default.nix
+++ b/snowfall-lib/checks/default.nix
@@ -48,6 +48,8 @@ in
             };
           in
           {
+            # We are building flake outputs based on file paths. Nix doesn't allow this
+            # so we have to explicitly discard the string's path context to use it as an attribute name.
             name = builtins.unsafeDiscardStringContext (snowfall-lib.path.get-parent-directory check);
             drv = callPackageWith extra-inputs check { };
           };
diff --git a/snowfall-lib/module/default.nix b/snowfall-lib/module/default.nix
index 97f892a..27f38f3 100644
--- a/snowfall-lib/module/default.nix
+++ b/snowfall-lib/module/default.nix
@@ -41,6 +41,8 @@ in
         create-module-metadata = module: {
           name =
             let
+              # We are building flake outputs based on file paths. Nix doesn't allow this
+              # so we have to explicitly discard the string's path context for string manipulation.
               path-name = builtins.replaceStrings [ (builtins.toString src) "/default.nix" ] [ "" "" ] (
                 builtins.unsafeDiscardStringContext module
               );
diff --git a/snowfall-lib/overlay/default.nix b/snowfall-lib/overlay/default.nix
index 8d01cc6..4736399 100644
--- a/snowfall-lib/overlay/default.nix
+++ b/snowfall-lib/overlay/default.nix
@@ -111,6 +111,8 @@ in
         create-overlay = (
           overlays: file:
           let
+            # We are building flake outputs based on file paths. Nix doesn't allow this
+            # so we have to explicitly discard the string's path context to use it as an attribute name.
             name = builtins.unsafeDiscardStringContext (snowfall-lib.path.get-parent-directory file);
             overlay =
               final: prev:
@@ -159,6 +161,8 @@ in
         create-package-overlay =
           package-overlays: file:
           let
+            # We are building flake outputs based on file paths. Nix doesn't allow this
+            # so we have to explicitly discard the string's path context to use it as an attribute name.
             name = builtins.unsafeDiscardStringContext (snowfall-lib.path.get-parent-directory file);
             overlay =
               final: prev:
diff --git a/snowfall-lib/shell/default.nix b/snowfall-lib/shell/default.nix
index 77352a7..fae6832 100644
--- a/snowfall-lib/shell/default.nix
+++ b/snowfall-lib/shell/default.nix
@@ -48,6 +48,8 @@ in
             };
           in
           {
+            # We are building flake outputs based on file paths. Nix doesn't allow this
+            # so we have to explicitly discard the string's path context to use it as an attribute name.
             name = builtins.unsafeDiscardStringContext (snowfall-lib.path.get-parent-directory shell);
             drv = callPackageWith extra-inputs shell { };
           };