Merge pull request SciML#9 from SciML/docstrings

improve docstrings

Project.toml

@@ -1,7 +1,7 @@
 name = "SimpleNonlinearSolve"
 uuid = "727e6d20-b764-4bd8-a329-72de5adea6c7"
 authors = ["SciML"]
-version = "0.1.2"
+version = "0.1.3"
 
 [deps]
 ArrayInterfaceCore = "30b0a656-2188-435a-8636-2ec0e6a096e2"

src/bisection.jl

@@ -1,3 +1,15 @@
+"""
+`Bisection(; exact_left = false, exact_right = false)`
+
+A common bisection method.
+
+### Keyword Arguments
+
+- `exact_left`: whether to enforce whether the left side of the interval must be exactly
+  zero for the returned result. Defualts to false.
+- `exact_right`: whether to enforce whether the right side of the interval must be exactly
+  zero for the returned result. Defualts to false.
+"""
 struct Bisection <: AbstractBracketingAlgorithm
     exact_left::Bool
     exact_right::Bool

src/falsi.jl

@@ -1,3 +1,6 @@
+"""
+`Falsi`: A non-allocating regula falsi method
+"""
 struct Falsi <: AbstractBracketingAlgorithm end
 
 function SciMLBase.solve(prob::IntervalNonlinearProblem, alg::Falsi, args...;

src/raphson.jl

@@ -1,3 +1,33 @@
+"""
+```julia
+SimpleNewtonRaphson(; chunk_size = Val{0}(), autodiff = Val{true}(),
+                                 diff_type = Val{:forward})
+```
+
+A low-overhead implementation of Newton-Raphson. This method is non-allocating on scalar
+and static array problems.
+
+!!! note
+
+    As part of the decreased overhead, this method omits some of the higher level error
+    catching of the other methods. Thus to see better error messages, use one of the other
+    methods like `NewtonRaphson`
+
+### Keyword Arguments
+
+- `chunk_size`: the chunk size used by the internal ForwardDiff.jl automatic differentiation
+  system. This allows for multiple derivative columns to be computed simultaniously,
+  improving performance. Defaults to `0`, which is equivalent to using ForwardDiff.jl's
+  default chunk size mechanism. For more details, see the documentation for
+  [ForwardDiff.jl](https://juliadiff.org/ForwardDiff.jl/stable/).
+- `autodiff`: whether to use forward-mode automatic differentiation for the Jacobian.
+  Note that this argument is ignored if an analytical Jacobian is passed as that will be
+  used instead. Defaults to `Val{true}`, which means ForwardDiff.jl is used by default.
+  If `Val{false}`, then FiniteDiff.jl is used for finite differencing.
+- `diff_type`: the type of finite differencing used if `autodiff = false`. Defaults to
+  `Val{:forward}` for forward finite differences. For more details on the choices, see the
+  [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl) documentation.
+"""
 struct SimpleNewtonRaphson{CS, AD, FDT} <: AbstractNewtonAlgorithm{CS, AD, FDT}
     function SimpleNewtonRaphson(; chunk_size = Val{0}(), autodiff = Val{true}(),
                                  diff_type = Val{:forward})