Fix documentation.

Author: kellertuer

docs/src/plans/index.md

@@ -58,11 +58,29 @@ You can further activate a “Tutorial” mode by `set_parameter!(:Mode, "Tutori
 Manopt.is_tutorial_mode
 ```
 
-# A factory for providing manifold defaults
+## A factory for providing manifold defaults
 
 In several cases a manifold might not yet be known at the time a (keyword) argument should be provided. Therefore, any type with a manifold default can be wrapped into a factory.
 
 ```@docs
 Manopt.ManifoldDefaultsFactory
 Manopt._produce_type
+```
+
+## Keyword arguments and their verification
+
+Internally `Manopt.jl` passes keywords for the (high-level) solver
+functions to several inner functions, e.g. to add debug or caching.
+Besides the documentation, one can check with the internal function [`Manopt.accepted_keywords`](@ref) which keywords a solver accepts.
+
+A solver also warns, if a keyword is passed, that is not handled by the
+solver or any of the inner functions it calls.
+
+```@docs
+Manopt.Keywords
+Manopt.accepted_keywords
+Manopt.add!
+Manopt.calls_with_kwargs
+Manopt.direct_keywords
+Manopt.keywords_accepted
 ```

src/plans/keywords.jl

@@ -152,9 +152,12 @@ accepts when constructed.
 
 This function uses [`direct_keywords`](@ref) to find keywords a function directly accepts,
 and [`calls_with_kwargs`](@ref) to find functions it passes keyword to, where they also
-might be accepted
+might be accepted.
+In order for nonmutating functions `f` to work the same as their mutating variants `f!`,
+the allocating one, one should set [`calls_with_kwargs`](@ref)`(f) = (f,)`.
 
-this also includes keywords that are passed on to internal structures.
+this also includes keywords that are passed on to internal structures, also specified using
+[`calls_with_kwargs`](@ref).
 """
 function accepted_keywords(f)
     kw = direct_keywords(f)
@@ -178,12 +181,7 @@ calls_with_kwargs(f) = ()
     direct_keywords(solver)
     direct_keywords(stepsize)
 
-Return a set of keywords a function directly would work with,
-i.e. that are directly defined in one of its dispatch variants, including
-a mutating variant.
-
-For example `direct_keywords(gradient_descent)` and `direct_keywords(gradient_descent!)`
-should return the same set [`Keywords!`](@ref).
+Return a set of keywords a function directly would work with.
 """
 function direct_keywords(f)
     methods_f = methods(f)

src/plans/stepsize.jl

@@ -836,7 +836,7 @@ $(_var(:Keyword, :vector_transport_method))
 * `bb_max_stepsize=1e3`
 $(_var(:Keyword, :retraction_method))
 * `strategy=direct`
-* `storage=[`StoreStateAction`](@ref)`(M; store_fields=[:Iterate, :Gradient])``
+* `storage=`[`StoreStateAction`](@ref)`(M; store_fields=[:Iterate, :Gradient])`
 * `stepsize_reduction=0.5`
 * `sufficient_decrease=1e-4`
 * `stop_when_stepsize_less=0.0`