Fix docstring for SeawaterBuoyancy (#3334)

* Update seawater_buoyancy.jl

* Update src/BuoyancyModels/seawater_buoyancy.jl

Co-authored-by: Navid C. Constantinou <[email protected]>

* Update src/BuoyancyModels/seawater_buoyancy.jl

Co-authored-by: Navid C. Constantinou <[email protected]>

* fix doctests

* delete duplicate doctests

* fix spacing

---------

Co-authored-by: Navid C. Constantinou <[email protected]>

src/BuoyancyModels/seawater_buoyancy.jl

@@ -43,22 +43,65 @@ end
     SeawaterBuoyancy([FT = Float64;]
                      gravitational_acceleration = g_Earth,
                      equation_of_state = LinearEquationOfState(FT),
-                     constant_temperature = false,
-                     constant_salinity = false)
+                     constant_temperature = nothing,
+                     constant_salinity = nothing)
 
-Returns parameters for a temperature- and salt-stratified seawater buoyancy model
+Return parameters for a temperature- and salt-stratified seawater buoyancy model
 with a `gravitational_acceleration` constant (typically called ``g``), and an
 `equation_of_state` that related temperature and salinity (or conservative temperature
 and absolute salinity) to density anomalies and buoyancy.
 
-`constant_temperature` indicates that buoyancy depends only on salinity. For a nonlinear
-equation of state, `constant_temperature` is used as the temperature of the system.
-The same logic, with the roles of salinity and temperature reversed, holds when
-`constant_salinity` is provided.
+Setting `constant_temperature` to something that is not `nothing` indicates that buoyancy depends only on salinity.
+For a nonlinear equation of state, the value provided `constant_temperature` is used as the temperature of the system.
+Vice versa, setting `constant_salinity` indicates that buoyancy depends only on temperature.
 
 For a linear equation of state, the values of `constant_temperature` or `constant_salinity`
-are irrelevant; in this case, `constant_temperature=true` (and similar for `constant_salinity`)
-is valid input.
+are irrelevant.
+
+Examples
+========
+
+The "TEOS10" equation of state, see https://www.teos-10.org
+
+```jldoctest seawaterbuoyancy
+julia> using SeawaterPolynomials.TEOS10: TEOS10EquationOfState
+
+julia> teos10 = TEOS10EquationOfState()
+BoussinesqEquationOfState{Float64}:
+    ├── seawater_polynomial: TEOS10SeawaterPolynomial{Float64}
+    └── reference_density: 1020.0
+```
+
+Buoyancy that depends on both temperature and salinity
+
+```jldoctest seawaterbuoyancy
+julia> using Oceananigans
+
+julia> buoyancy = SeawaterBuoyancy(equation_of_state=teos10)
+SeawaterBuoyancy{Float64}:
+├── gravitational_acceleration: 9.80665
+└── equation of state: BoussinesqEquationOfState{Float64}
+```
+
+Buoyancy that depends only on salinity with temperature held at 20 degrees Celsius
+
+```jldoctest seawaterbuoyancy
+julia> salinity_dependent_buoyancy = SeawaterBuoyancy(equation_of_state=teos10, constant_temperature=20) 
+SeawaterBuoyancy{Float64}:
+├── gravitational_acceleration: 9.80665
+├── constant_temperature: 20
+└── equation of state: BoussinesqEquationOfState{Float64}
+```
+
+Buoyancy that depends only on temperature with salinity held at 35 psu
+
+```jldoctest seawaterbuoyancy
+julia> temperature_dependent_buoyancy = SeawaterBuoyancy(equation_of_state=teos10, constant_salinity=35)
+SeawaterBuoyancy{Float64}:
+├── gravitational_acceleration: 9.80665
+├── constant_salinity: 35
+└── equation of state: BoussinesqEquationOfState{Float64}
+```
 """
 function SeawaterBuoyancy(FT = Float64;
                           gravitational_acceleration = g_Earth,