GeneralDomain documentation is unclear

[DanielVandH]

The documentation for GeneralDomain shows the docstring

GeneralDomain(g, u=nothing; nlsolve=NLSOLVEJL_SETUP(), save=true,
                       abstol=nothing, scalefactor=nothing, autonomous=numargs(g)==2,
                       nlopts=Dict(:ftol => 10*eps()))

which should now be

GeneralDomain(g, u = nothing; nlsolve = NLSOLVEJL_SETUP(), save = true,
                       abstol = nothing, scalefactor = nothing,
                       autonomous = maximum(SciMLBase.numargs(g)) == 3,
                       nlopts = Dict(:ftol => 10 * eps()))

Moreover, it initially says that g should be of the form g(u, resid) or g(t, u, resid), and then later says it should be g(resid, u, p) or g(resid, u, p, t). What should it be? It's not exactly clear to me what the "residuals" are either: a vector that tests each component of the solution? A single value testing all components? I thought it would be the former, but the documentation says

- `g`: ... which is zero when the value is in the domain.

which suggests the latter. I guess judging from

https://github.com/SciML/DiffEqCallbacks.jl/blob/f61c6111beec59d7b312786be707c1ee40931437/src/domain.jl#L192-L210

it should be that g is g(resid, u, p) or g(resid, u, p, t), ~~and resid could actually be any mutable value, not necessarily with length(resid) == length(u)~~ (doesn't seem like resid can be defined manually directly actually, and typeof(resid) must == typeof(u)).

I'm also guessing that p is just integrator.p, or is there a way to add on extra parameters here without a closure?

[ChrisRackauckas]

Moreover, it initially says that g should be of the form g(u, resid) or g(t, u, resid), and then later says it should be g(resid, u, p) or g(resid, u, p, t). What should it be?

The latter.

It's not exactly clear to me what the "residuals" are either: a vector that tests each component of the solution?

Yes, the residuals of the nonlinear system.

I'm also guessing that p is just integrator.p, or is there a way to add on extra parameters here without a closure?

That's all it is.

Though, we should probably extend this a little bit and change the nonlinear solving to use NonlinearSolve.jl. That would be a breaking change, but quite worth it because this code is really old. Make it so that way f always has to have t to simplify the code too.

[ChrisRackauckas]

@ArnoStrouwen can you tackle this one?