Better docstrings for scalar diffusivity closures (#2334)

* better docstrings for scalardiffusivities

* better docstrings for scalarbiharmonicdiffusivities

* Update Project.toml

Co-authored-by: Gregory L. Wagner <wagner.greg@gmail.com>

Project.toml

@@ -1,6 +1,6 @@
 name = "Oceananigans"
 uuid = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
-version = "0.72.2"
+version = "0.72.3"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"

src/TurbulenceClosures/turbulence_closure_implementations/scalar_biharmonic_diffusivity.jl

@@ -28,7 +28,19 @@ required_halo_size(::ScalarBiharmonicDiffusivity) = 2
                                 ν=0, κ=0,
                                 discrete_form = false)
 
-Returns parameters for a scalar biharmonic diffusivity model.
+Return a scalar biharmonic diffusivity turbulence closure with viscosity coefficient `ν` and tracer
+diffusivities `κ` for each tracer field in `tracers`. If a single `κ` is provided, it is applied to
+all tracers. Otherwise `κ` must be a `NamedTuple` with values for every tracer individually.
+
+Arguments
+=========
+
+* `formulation`:
+  - `HorizontalFormulation()` for diffusivity applied in the horizontal direction(s)
+  - `VerticalFormulation()` for diffusivity applied in the vertical direction,
+  - `ThreeDimensionalFormulation()` (default) for diffusivity applied isotropically to all directions
+
+* `FT`: the float datatype (default: `Float64`)
 
 Keyword arguments
 =================
@@ -39,11 +51,6 @@ Keyword arguments
          `NamedTuple` of diffusivities with entries for each tracer.
 
   - `discrete_form`: `Boolean`.
-
-  - `formulation`: formulation used for the discretization of the diffusivity operator.
-                   Options are `VerticalFormulation()`, `HorizontalFormulation()` and
-                   `ThreeDimensionalFormulation()`.
-
 """
 function ScalarBiharmonicDiffusivity(formulation=ThreeDimensionalFormulation(), FT=Float64;
                                      ν=0, κ=0,

src/TurbulenceClosures/turbulence_closure_implementations/scalar_diffusivity.jl

@@ -11,21 +11,30 @@ struct ScalarDiffusivity{TD, F, N, K} <: AbstractScalarDiffusivity{TD, F}
 end
 
 """
-    ScalarDiffusivity([time_discretization=ExplicitTimeDiscretization,
+    ScalarDiffusivity([time_discretization=ExplicitTimeDiscretization(),
                       formulation=ThreeDimensionalFormulation(), FT=Float64];
                       ν=0, κ=0,
                       discrete_form = false) 
 
-Return `ScalarDiffusivity` with viscosity `ν` and tracer diffusivities `κ`
-for each tracer field in `tracers`. If a single `κ` is provided, it is
-applied to all tracers. Otherwise `κ` must be a `NamedTuple` with values
-for every tracer individually.
+Return `ScalarDiffusivity` turbulence closure with viscosity `ν` and tracer diffusivities `κ`
+for each tracer field in `tracers`. If a single `κ` is provided, it is applied to all tracers.
+Otherwise `κ` must be a `NamedTuple` with values for every tracer individually.
 
-`formulation`:
+Arguments
+=========
+
+* `time_discretization`: either `ExplicitTimeDiscretization()` (default) or `VerticallyImplicitTimeDiscretization()`.
+
+* `formulation`:
   - `HorizontalFormulation()` for diffusivity applied in the horizontal direction(s)
   - `VerticalFormulation()` for diffusivity applied in the vertical direction,
   - `ThreeDimensionalFormulation()` (default) for diffusivity applied isotropically to all directions
 
+* `FT`: the float datatype (default: `Float64`)
+
+Keyword arguments
+=================
+
 `ν` and the fields of `κ` may be constants (converted to `FT`), arrays, fields or
   - functions of `(x, y, z, t)` if `discrete_form = false`
   - functions of `(i, j, k, grid, LX, LY, LZ)` with `LX`, `LY` and `LZ` are either `Face()` or `Center()` if
@@ -49,9 +58,23 @@ end
 const VerticalScalarDiffusivity{TD} = ScalarDiffusivity{TD, VerticalFormulation} where TD
 const HorizontalScalarDiffusivity{TD} = ScalarDiffusivity{TD, HorizontalFormulation} where TD
 
+"""
+    VerticalScalarDiffusivity([time_discretization=ExplicitTimeDiscretization(),
+                              FT::DataType=Float64;]
+                              kwargs...)
+
+Shorthand for a `ScalarDiffusivity` with `VerticalFormulation()`. See [`ScalarDiffusivity`](@ref).
+"""
 VerticalScalarDiffusivity(time_discretization=ExplicitTimeDiscretization(), FT::DataType=Float64; kwargs...) =
     ScalarDiffusivity(time_discretization, VerticalFormulation(), FT; kwargs...)
 
+"""
+    HorizontalScalarDiffusivity([time_discretization=ExplicitTimeDiscretization(),
+                                FT::DataType=Float64;]
+                                kwargs...)
+
+Shorthand for a `ScalarDiffusivity` with `HorizontalFormulation()`. See [`ScalarDiffusivity`](@ref).
+"""
 HorizontalScalarDiffusivity(time_discretization=ExplicitTimeDiscretization(), FT::DataType=Float64; kwargs...) =
     ScalarDiffusivity(time_discretization, HorizontalFormulation(), FT; kwargs...)