start docstring overhaul

Author: ArnoStrouwen

.gitignore

@@ -7,3 +7,4 @@ Manifest.toml
 .vscode
 profile.pb.gz
 .*.swp
+docs/build

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 
 [compat]
 Documenter = "0.27"

src/OrdinaryDiffEq.jl

@@ -103,7 +103,10 @@ import Preferences
 DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing
 
 include("misc_utils.jl")
+
 include("algorithms.jl")
+include("algorithms/explicit_rk.jl")
+
 include("alg_utils.jl")
 
 include("nlsolve/type.jl")

src/algorithms.jl

@@ -505,49 +505,6 @@ function Base.show(io::IO, alg::RK46NL)
           ", thread = ", alg.thread, ")")
 end
 
-"""
-    Heun(; stage_limiter! = OrdinaryDiffEq.trivial_limiter!,
-           step_limiter! = OrdinaryDiffEq.trivial_limiter!,
-           thread = OrdinaryDiffEq.False())
-
-Explicit Runge-Kutta Method
-The second order Heun's method. Uses embedded Euler method for adaptivity.
-
-Like SSPRK methods, this method also takes optional arguments `stage_limiter!`
-and `step_limiter!`, where `stage_limiter!` and `step_limiter!` are functions
-of the form `limiter!(u, integrator, p, t)`.
-
-The argument `thread` determines whether internal broadcasting on
-appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`,
-default) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when
-Julia is started with multiple threads.
-"""
-struct Heun{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm
-    stage_limiter!::StageLimiter
-    step_limiter!::StepLimiter
-    thread::Thread
-end
-
-function Heun(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!,
-              thread = False())
-    Heun{typeof(stage_limiter!), typeof(step_limiter!), typeof(thread)}(stage_limiter!,
-                                                                        step_limiter!,
-                                                                        thread)
-end
-
-# for backwards compatibility
-function Heun(stage_limiter!, step_limiter! = trivial_limiter!)
-    Heun{typeof(stage_limiter!), typeof(step_limiter!), False}(stage_limiter!,
-                                                               step_limiter!,
-                                                               False())
-end
-
-function Base.show(io::IO, alg::Heun)
-    print(io, "Heun(stage_limiter! = ", alg.stage_limiter!,
-          ", step_limiter! = ", alg.step_limiter!,
-          ", thread = ", alg.thread, ")")
-end
-
 """
     Ralston(; stage_limiter! = OrdinaryDiffEq.trivial_limiter!,
              step_limiter! = OrdinaryDiffEq.trivial_limiter!,

src/algorithms/explicit_rk.jl

@@ -0,0 +1,50 @@
+function explicit_rk_docstring(description::String)
+    start_docstring = """
+       ```julia
+       $FUNCTIONNAME(; stage_limiter! = OrdinaryDiffEq.trivial_limiter!,
+       step_limiter! = OrdinaryDiffEq.trivial_limiter!,
+       thread = OrdinaryDiffEq.False())
+       ```
+
+       Explicit Runge-Kutta Method.
+       """
+    end_docstring = """
+
+        ### Keyword Arguments
+
+         - `stage_limiter!`: function of the form `limiter!(u, integrator, p, t)`
+         - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)`
+         - `thread`: determines whether internal broadcasting on
+            appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`,
+            default) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when
+            Julia is started with multiple threads.
+        """
+    start_docstring * description * end_docstring
+end
+
+@doc explicit_rk_docstring("The second order Heun's method. Uses embedded Euler method for adaptivity.")
+struct Heun{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm
+    stage_limiter!::StageLimiter
+    step_limiter!::StepLimiter
+    thread::Thread
+end
+
+function Heun(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!,
+              thread = False())
+    Heun{typeof(stage_limiter!), typeof(step_limiter!), typeof(thread)}(stage_limiter!,
+                                                                        step_limiter!,
+                                                                        thread)
+end
+
+# for backwards compatibility
+function Heun(stage_limiter!, step_limiter! = trivial_limiter!)
+    Heun{typeof(stage_limiter!), typeof(step_limiter!), False}(stage_limiter!,
+                                                               step_limiter!,
+                                                               False())
+end
+
+function Base.show(io::IO, alg::Heun)
+    print(io, "Heun(stage_limiter! = ", alg.stage_limiter!,
+          ", step_limiter! = ", alg.step_limiter!,
+          ", thread = ", alg.thread, ")")
+end