@KristianJS I've added DocStringExtensions that makes it really easy to document the code. E.g. I write
"""
$(TYPEDSIGNATURE)
And some text explaining this function.
"""
function f(x) = x
and calling the help via ? of this function would automatically replace $(TYPEDSIGNATURES) with the function signature (and their types). In our case this means
julia> using StochasticStir
help?> StochasticStirring
search: StochasticStirring StochasticStir
A SpeedyWeather forcing term that stochastically stirrs relative vorticity in the
BarotropicModel or the ShallowWaterModel.
• trunc::Int64: Spectral resolution as max degree of spherical harmonics
• nlat::Int64: Number of latitude rings, used for latitudinal mask
• decorrelation_time::Dates.Second: Decorrelation time scale τ [days]
• strength::Float64: Stirring strength A [1/s²]
• latitude::Float64: Stirring latitude [˚N]
• width::Float64: Stirring width [˚]
• lmin::Int64: Minimum degree of spherical harmonics to force
• lmax::Int64: Maximum degree of spherical harmonics to force
• mmin::Int64: Minimum order of spherical harmonics to force
• mmax::Int64: Maximum order of spherical harmonics to force
• S::SpeedyWeather.LowerTriangularMatrices.LowerTriangularMatrix{Complex{NF}} where NF:
Stochastic stirring term S
• a::Base.RefValue: a = A*sqrt(1 - exp(-2dt/τ)), the noise factor times the stirring
strength [1/s²]
• b::Base.RefValue: b = exp(-dt/τ), the auto-regressive factor [1]
• lat_mask::Vector: Latitudinal mask, confined to mid-latitude storm track by default
[1]
────────────────────────────────────────────────────────────────────────────────────────────────
StochasticStirring(
SG::SpeedyWeather.SpectralGrid;
kwargs...
) -> StochasticStirring{<:AbstractFloat}
Generator function for StochasticStirring using resolution and number format from a
SpectralGrid. Further options should be provided as keyword arguments.
julia>
Even though I wrote only the short sentences, the rest is inserted automatically.
At the moment it's not easy to see which are the actual options and which are other fields/parameters needed but that are automatically chosen. We can probably change that if needed, but it's already a big step towards self documenting code.
@KristianJS I've added
DocStringExtensions
that makes it really easy to document the code. E.g. I writeand calling the help via
?
of this function would automatically replace$(TYPEDSIGNATURES)
with the function signature (and their types). In our case this meansEven though I wrote only the short sentences, the rest is inserted automatically.
At the moment it's not easy to see which are the actual options and which are other fields/parameters needed but that are automatically chosen. We can probably change that if needed, but it's already a big step towards self documenting code.