Improve documentation of AbstractModel interface #4797
Description
I think it would be helpful to more thoroughly document (and use) the method interface for AbstractModel defined in Models.jl.
First, this comment:
# We assume that model has some properties, eg:
# - model.clock::Clock
# - model.architecture.
# - model.timestepper with timestepper.G⁻ and timestepper.Gⁿ :spiral_eyes:should probably be moved to the docstring for AbstractModel.
Second, I would suggest the following docstrings for these methods:
"""
$SIGNATURES
Returns the current iteration of the `model.clock`.
"""
iteration(model::AbstractModel) = model.clock.iteration
"""
$SIGNATURES
Returns the device architecture defined by the underlying model `grid`.
"""
architecture(model::AbstractModel) = model.grid.architecture
"""
$SIGNATURES
TODO: what does this method do in addition to the constructor?
"""
initialize!(model::AbstractModel) = nothing
"""
$SIGNATURES
TODO
"""
total_velocities(model::AbstractModel) = nothing
"""
$SIGNATURES
Returns the `TimeStepper` used by the given `model`.
"""
timestepper(model::AbstractModel) = model.timestepper
"""
$SIGNATURES
Defines initialization routines for the first call to `update_state!` after initialization. Defaults to invoking `update_state!(model; kw...)`.
"""
initialization_update_state!(model::AbstractModel; kw...) = update_state!(model; kw...) # fallback
"""
$SIGNATURES
Updates all `FieldTimeSeries` fields defined on the given `model. The default implementation assumes that the `model` that does not contain any `FieldTimeSeries` and returns `nothing`.
"""
update_model_field_time_series!(model::AbstractModel, clock::Clock) = nothing
"""
Base.time(model::AbstractModel)
Returns the current `time` from the given `model.clock`.
"""
Base.time(model::AbstractModel) = model.clock.time
"""
Base.eltype(model::AbstractModel)
Returns the numeric `eltype` of `model.grid` and all associated `Field`s.
"""
Base.eltype(model::AbstractModel) = eltype(model.grid)I would also be in favor of adding get_clock (or just clock) and get_grid methods but this isn't strictly necessary.
I guess we should also add a doc page on the AbstractModel interface to the appendix.