From 9615c0d08ac69b3eeeec2a4521d7a8011d7bdafe Mon Sep 17 00:00:00 2001
From: Tim Holy <tim.holy@gmail.com>
Date: Sat, 17 Aug 2024 14:18:38 -0500
Subject: [PATCH] Add examples to docstrings (#589)

---
 src/Cthulhu.jl | 45 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 3 deletions(-)

diff --git a/src/Cthulhu.jl b/src/Cthulhu.jl
index 99bd3e0c..814ff2ac 100644
--- a/src/Cthulhu.jl
+++ b/src/Cthulhu.jl
@@ -107,6 +107,16 @@ export ascend
 
 Evaluates the arguments to the function or macro call, determines their
 types, and calls [`descend_code_typed`](@ref) on the resulting expression.
+See [`Cthulhu.CONFIG`](@ref) for options and their defaults.
+
+# Examples
+```julia
+julia> @descend_code_typed sin(1)
+[...]
+
+julia> @descend_code_typed optimize=false sin(1)
+[...]
+```
 """
 macro descend_code_typed(ex0...)
     InteractiveUtils.gen_call_with_extracted_types_and_kwargs(__module__, :descend_code_typed, ex0)
@@ -126,6 +136,22 @@ end
 
 Evaluates the arguments to the function or macro call, determines their
 types, and calls [`descend_code_warntype`](@ref) on the resulting expression.
+See [`Cthulhu.CONFIG`](@ref) for options and their defaults.
+
+# Examples
+```julia
+julia> function foo()
+           T = rand() > 0.5 ? Int64 : Float64
+           sin(rand(T))
+       end
+foo (generic function with 1 method)
+
+julia> @descend_code_warntype foo()
+[...]
+
+julia> @descend_code_warntype hide_type_stable=true foo()
+[...]
+```
 """
 macro descend_code_warntype(ex0...)
     InteractiveUtils.gen_call_with_extracted_types_and_kwargs(__module__, :descend_code_warntype, ex0)
@@ -136,6 +162,16 @@ end
 
 Evaluates the arguments to the function or macro call, determines their
 types, and calls [`descend`](@ref) on the resulting expression.
+See [`Cthulhu.CONFIG`](@ref) for options and their defaults.
+
+# Examples
+```julia
+julia> @descend sin(1)
+[...]
+
+julia> @descend iswarn=false foo()
+[...]
+```
 """
 macro descend(ex0...)
     InteractiveUtils.gen_call_with_extracted_types_and_kwargs(__module__, :descend, ex0)
@@ -150,6 +186,7 @@ end
 Given a function and a tuple-type, interactively explore the output of
 `code_typed` by descending into `invoke` statements. Type enter to select an
 `invoke` to descend into, select `↩`  to ascend, and press `q` or `control-c` to quit.
+See [`Cthulhu.CONFIG`](@ref) for `kwargs` and their defaults.
 
 # Usage:
 ```julia
@@ -164,7 +201,7 @@ julia> descend_code_typed(Tuple{typeof(sin), Int})
 
 julia> descend_code_typed() do
            T = rand() > 0.5 ? Int64 : Float64
-           sin(rand(T)
+           sin(rand(T))
        end
 [...]
 ```
@@ -181,6 +218,7 @@ descend_code_typed(@nospecialize(args...); kwargs...) =
 Given a function and a tuple-type, interactively explore the output of
 `code_warntype` by descending into `invoke` statements. Type enter to select an
 `invoke` to descend into, select `↩` to ascend, and press `q` or `control-c` to quit.
+See [`Cthulhu.CONFIG`](@ref) for `kwargs` and their defaults.
 
 # Usage:
 ```julia
@@ -195,7 +233,7 @@ julia> descend_code_warntype(Tuple{typeof(sin), Int})
 
 julia> descend_code_warntype() do
            T = rand() > 0.5 ? Int64 : Float64
-           sin(rand(T)
+           sin(rand(T))
        end
 [...]
 ```
@@ -245,6 +283,7 @@ default_terminal() = REPL.LineEdit.terminal(Base.active_repl)
 Given a function and a tuple-type, interactively explore the source code of functions
 annotated with inferred types by descending into `invoke` statements. Type enter to select an
 `invoke` to descend into, select `↩` to ascend, and press `q` or `control-c` to quit.
+See [`Cthulhu.CONFIG`](@ref) for `kwargs` and their defaults.
 
 # Usage:
 ```julia
@@ -259,7 +298,7 @@ julia> descend(Tuple{typeof(sin), Int})
 
 julia> descend() do
            T = rand() > 0.5 ? Int64 : Float64
-           sin(rand(T)
+           sin(rand(T))
        end
 [...]
 ```