From 28ee6e7979405feb704d8715ece9749e57277456 Mon Sep 17 00:00:00 2001
From: Gavin John <gavinnjohn@gmail.com>
Date: Sat, 28 Sep 2024 15:43:03 -0700
Subject: [PATCH] (WIP) srcOnly: Add noogle-compatible documentation

---
 pkgs/build-support/src-only/default.nix | 41 ++++++++++++++++++++-----
 1 file changed, 34 insertions(+), 7 deletions(-)

diff --git a/pkgs/build-support/src-only/default.nix b/pkgs/build-support/src-only/default.nix
index d303d35231a9..86fdda489077 100644
--- a/pkgs/build-support/src-only/default.nix
+++ b/pkgs/build-support/src-only/default.nix
@@ -1,12 +1,39 @@
 { lib, stdenvNoCC }:
 
-# srcOnly is a utility builder that only fetches and unpacks the given `src`,
-# and optionally patching with `patches` or adding build inputs.
-#
-# It can be invoked directly, or be used to wrap an existing derivation. Eg:
-#
-# > srcOnly pkgs.hello
-#
+/**
+  A utility builder to get the source code of the input derivation, with any patches applied.
+
+  # Examples
+
+  ```nix
+  srcOnly pkgs.hello
+  => «derivation /nix/store/gyfk2jg9079ga5g5gfms5i4h0k9jhf0f-hello-2.12.1-source.drv»
+
+  srcOnly {
+    inherit (pkgs.hello) name version src stdenv;
+  }
+  => «derivation /nix/store/vf9hdhz38z7rfhzhrk0vi70h755fnsw7-hello-2.12.1-source.drv»
+  ```
+
+  # Type
+
+  ```
+  srcOnly :: (Derivation | AttrSet) -> Derivation
+  ```
+
+  # Input
+
+  `attrs`
+
+  : One of the following:
+
+    - A derivation with (at minimum) an unpackPhase and a patchPhase.
+    - A set of attributes that would be passed to a `stdenv.mkDerivation` or `stdenvNoCC.mkDerivation` call.
+
+  # Output
+
+  A derivation that runs a derivation's `unpackPhase` and `patchPhase`, and then copies the result to the output path.
+*/
 
 attrs:
 let