From ab9ef1c948e14e09a6a0160cfbf76b71b4b9dd3d Mon Sep 17 00:00:00 2001
From: Jan Weidner <jw3126@gmail.com>
Date: Thu, 16 Sep 2021 10:02:42 +0200
Subject: [PATCH] improve docs

---
 README.md            |  4 ++++
 src/StructHelpers.jl | 42 +++++++++++++++++++++++++++++++++++++-----
 test/runtests.jl     |  2 +-
 3 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 40614ed..4729ebe 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,10 @@ end
 @batteries S hash=false # don't overload `Base.hash`
 @batteries S kwconstructor=true # add a keyword constructor
 ```
+For all supported options and defaults, consult the docstring:
+```julia
+julia>?@batteries
+```
 
 # Alternatives
 
diff --git a/src/StructHelpers.jl b/src/StructHelpers.jl
index 6501e2f..bc855c4 100644
--- a/src/StructHelpers.jl
+++ b/src/StructHelpers.jl
@@ -34,11 +34,41 @@ function def_kwconstructor(T, propertynames)
 end
 
 const BATTERIES_DEFAULTS = (
-    eq=true, hash=true,
-    kwconstructor=false, kwshow=false,
-    getproperties=true, constructorof=true,
+    eq            = true ,
+    hash          = true ,
+    kwconstructor = false,
+    kwshow        = false,
+    getproperties = true ,
+    constructorof = true ,
 )
 
+const BATTERIES_DOCSTRINGS = (
+    eq            = "Define `Base.(==)` structurally.",
+    hash          = "Define `Base.hash` structurally.",
+    kwconstructor = "Add a keyword constructor.",
+    kwshow        = "Overload `Base.show` such that the names of each field are printed.",
+    getproperties = "Overload `ConstructionBase.getproperties`.",
+    constructorof = "Overload `ConstructionBase.constructorof`.",
+)
+
+if (keys(BATTERIES_DEFAULTS) != keys(BATTERIES_DOCSTRINGS))
+    error("""
+          keys(BATTERIES_DEFAULTS) == key(BATTERIES_DOCSTRINGS) must hold.
+          Got:
+          keys(BATTERIES_DEFAULTS) = $(keys(BATTERIES_DEFAULTS))
+          keys(BATTERIES_DOCSTRINGS) = $(keys(BATTERIES_DOCSTRINGS))
+    """)
+end
+@assert keys(BATTERIES_DEFAULTS) == keys(BATTERIES_DOCSTRINGS)
+
+function doc_batteries_options()
+    lines = map(propertynames(BATTERIES_DEFAULTS)) do key
+        "* **$key** = $(BATTERIES_DEFAULTS[key]):\n $(BATTERIES_DOCSTRINGS[key])"
+    end
+    join(lines, "\n")
+end
+
+
 const ALLOWED_KW = keys(BATTERIES_DEFAULTS)
 
 """
@@ -46,8 +76,6 @@ const ALLOWED_KW = keys(BATTERIES_DEFAULTS)
     @batteries T [options]
 
 Automatically derive several methods for type `T`.
-Supported options are:
-$BATTERIES_DEFAULTS
 
 # Example
 ```julia
@@ -60,6 +88,10 @@ end
 @batteries S hash=false # don't overload `Base.hash`
 @batteries S kwconstructor=true # add a keyword constructor
 ```
+
+Supported options and defaults are:
+
+$(doc_batteries_options())
 """
 macro batteries(T, kw...)
     nt = parse_all_macro_kw(kw)
diff --git a/test/runtests.jl b/test/runtests.jl
index 236c039..9719b73 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -27,6 +27,7 @@ struct Empty2 end
 @batteries Empty1
 @batteries Empty2
 
+struct SErrors;a;b;c;end
 
 @testset "@batteries" begin
     @test SBatteries(1,2) == SBatteries(1,2)
@@ -63,7 +64,6 @@ struct Empty2 end
     @test Empty1() != Empty2()
     @test hash(Empty1()) != hash(Empty2())
 
-    struct SErrors;a;b;c;end
     @test_throws Exception @macroexpand @batteries SErrors kwconstructor="true"
     @test_throws Exception @macroexpand @batteries SErrors nonsense=true
     @macroexpand @batteries SErrors kwconstructor=true