From f326bccdbd455bde8930ab31185dc118bd5e64b5 Mon Sep 17 00:00:00 2001
From: h7x4 <h7x4@nani.wtf>
Date: Sun, 16 Jun 2024 20:44:48 +0200
Subject: [PATCH] nixos/doc: move implementation notes for formats.hocon to
 docs

(cherry picked from commit 141a8a6c86a4b14554add0457c864182c6fb6332)
---
 nixos/doc/manual/development/settings-options.section.md | 8 ++++++++
 pkgs/pkgs-lib/formats/hocon/default.nix                  | 4 ----
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/nixos/doc/manual/development/settings-options.section.md b/nixos/doc/manual/development/settings-options.section.md
index ae15113567f6..030d5ae3dce0 100644
--- a/nixos/doc/manual/development/settings-options.section.md
+++ b/nixos/doc/manual/development/settings-options.section.md
@@ -199,6 +199,14 @@ have a predefined type and string generator already declared under
           }
         ```
 
+    `Implementation notes:`
+
+    - classpath includes are not implemented in pyhocon,
+      which is used for validating the HOCON output. This
+      means that if you are using classpath includes,
+      you will want to either use an alternative validator
+      or set `doCheck = false` in the format options.
+
 `pkgs.formats.json` { }
 
 :   A function taking an empty attribute set (for future extensibility)
diff --git a/pkgs/pkgs-lib/formats/hocon/default.nix b/pkgs/pkgs-lib/formats/hocon/default.nix
index 0ae9c569ed2b..4abe70335cb1 100644
--- a/pkgs/pkgs-lib/formats/hocon/default.nix
+++ b/pkgs/pkgs-lib/formats/hocon/default.nix
@@ -27,13 +27,9 @@ let
   '';
 in
 {
-  # https://github.com/lightbend/config/blob/main/HOCON.md
   format = {
     generator ? hocon-generator
     , validator ? hocon-validator
-    # `include classpath("")` is not implemented in pyhocon.
-    # In the case that you need this functionality,
-    # you will have to disable pyhocon validation.
     , doCheck ? true
   }: let
     hoconLib = {