improve docs

Author: jw3126

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
 

src/StructHelpers.jl

@@ -34,20 +34,48 @@ 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)
 
 """
 
     @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)

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