add docstrings and DocStringExtensions

@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.

SpeedyWeather / StochasticStir.jl

add docstrings and DocStringExtensions #5