From b5549d90f263871da428ae89e82bd5a6d7092cdf Mon Sep 17 00:00:00 2001
From: Anderson Torres <torres.anderson.85@protonmail.com>
Date: Sun, 16 Jul 2023 23:24:31 -0300
Subject: [PATCH] wafHook: documentation

A very comprehensive one!
---
 doc/hooks/waf.section.md | 49 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/doc/hooks/waf.section.md b/doc/hooks/waf.section.md
index ee1bccff1d0..ad48586b064 100644
--- a/doc/hooks/waf.section.md
+++ b/doc/hooks/waf.section.md
@@ -1,3 +1,50 @@
 # wafHook {#wafhook}
 
-Overrides the configure, build, and install phases. This will run the “waf” script used by many projects. If `wafPath` (default `./waf`) doesn’t exist, it will copy the version of waf available in Nixpkgs. `wafFlags` can be used to pass flags to the waf script.
+[Waf](https://waf.io) is a Python-based software building system.
+
+In Nixpkgs, `wafHook` overrides the default configure, build, and install phases.
+
+## Variables controlling wafHook
+
+### `wafPath` {#wafPath}
+
+Location of the `waf` tool. It defaults to `./waf`, to honor software projects that include it directly inside their source trees.
+
+If `wafPath` doesn't exist, then `wafHook` will copy the `waf` provided from Nixpkgs to it.
+
+### `wafConfigureFlags` {#wafConfigureFlags}
+
+Controls the flags passed to waf tool during configure phase.
+
+### `wafFlags` {#wafFlags}
+
+Controls the flags passed to waf tool during build and install phases.
+
+### `dontAddWafCrossFlags` {#dontAddWafCrossFlags}
+
+When set to `true`, don't add cross compilation flags during configure phase.
+
+### `dontUseWafConfigure` {#dontUseWafConfigure}
+
+When set to true, don't use the predefined `wafConfigurePhase`.
+
+### `dontUseWafBuild` {#dontUseWafBuild}
+
+When set to true, don't use the predefined `wafBuildPhase`.
+
+### `dontUseWafInstall` {#dontUseWafInstall}
+
+When set to true, don't use the predefined `wafInstallPhase`.
+
+### Variables honored by wafHook {#variablesHonoredByWafHook}
+
+The following variables commonly used by `stdenv.mkDerivation` are also honored by `wafHook`.
+
+- `prefixKey`
+- `configureTargets`
+- `enableParallelBuilding`
+- `enableParallelInstalling`
+- `buildFlags`
+- `buildTargets`
+- `installFlags`
+- `installTargets`