docs: add docstrings to all julia models

src/julia-models/additive.jl

@@ -1,5 +1,5 @@
 """
-    XS_PowerLaw(K, a)
+    PowerLaw
 
 $(FIELDS)
 
@@ -59,7 +59,7 @@ end
 end
 
 """
-    XS_BlackBody(K, T)
+    BlackBody
 
 $(FIELDS)
 
@@ -110,6 +110,41 @@ end
     end
 end
 
+"""
+    GaussianLine
+
+$(FIELDS)
+
+# Example
+
+```julia
+energy = collect(range(0.1, 20.0, 100))
+invokemodel(energy, GuassianLine())
+```
+
+```
+                       GaussianLine                
+        ┌────────────────────────────────────────┐ 
+   0.09 │                                        │ 
+        │            ..                          │ 
+        │           .':                          │ 
+        │           : :                          │ 
+        │           : '.                         │ 
+        │          .'  :                         │ 
+        │          :   :                         │ 
+        │          :   :                         │ 
+        │          :   '.                        │ 
+        │         :     :                        │ 
+        │         :     :                        │ 
+        │         :     :                        │ 
+        │        .'      :                       │ 
+        │        :       '.                      │ 
+      0 │.......:         :......................│ 
+        └────────────────────────────────────────┘ 
+         0                                     20  
+                          E (keV)                  
+```
+"""
 struct GaussianLine{T} <: AbstractSpectralModel{T,Additive}
     "Normalisation."
     K::T
@@ -130,6 +165,47 @@ end
     end
 end
 
+"""
+    DeltaLine
+
+$(FIELDS)
+
+# Example
+
+```julia
+energy = collect(range(0.1, 20.0, 100))
+invokemodel(energy, DeltaLine())
+```
+
+```
+                        DeltaLine                 
+       ┌────────────────────────────────────────┐ 
+   0.4 │         .                              │ 
+       │         :                              │ 
+       │         :                              │ 
+       │         :                              │ 
+       │         :                              │ 
+       │         :                              │ 
+       │         ::                             │ 
+       │         ::                             │ 
+       │         ::                             │ 
+       │         ::                             │ 
+       │         ::                             │ 
+       │         ::                             │ 
+       │         ::                             │ 
+       │         ::                             │ 
+     0 │.........::.............................│ 
+       └────────────────────────────────────────┘ 
+        0                                     20  
+                         E (keV)                 
+```
+
+!!! note
+    The `DeltaLine` model is not a true delta function, as this would be
+    extremely difficult to define in a numerical model that needs to be able to
+    propagate gradients. Instead, it is a very narrow [`GaussianLine`](@ref)
+    model.
+"""
 struct DeltaLine{W<:Number,T} <: AbstractSpectralModel{T,Additive}
     _width::W
     "Normalisation."

src/julia-models/convolutional.jl

@@ -1,4 +1,21 @@
+"""
+    Log10Flux
 
+Used to measure the (log) flux of the models it is applied to. Note that the
+additive components must have their normalisations frozen for this model to work
+properly.
+
+$(FIELDS)
+
+## Example
+
+```julia
+model = PowerLaw()
+model.K.frozen = true
+
+flux_model = Log10Flux()(model)
+```
+"""
 struct Log10Flux{T} <: AbstractSpectralModel{T,Convolutional}
     E_min::T
     E_max::T
@@ -66,4 +83,4 @@ function _or_else(value::Union{Nothing,T}, v::T)::T where {T}
     end
 end
 
-export AsConvolution
+export Log10Flux

src/julia-models/multiplicative.jl

@@ -1,3 +1,8 @@
+"""
+    PhotoelectricAbsorption
+
+$(FIELDS)
+"""
 struct PhotoelectricAbsorption{D,T} <: AbstractTableModel{T,Multiplicative}
     table::D
     "Equivalent hydrogen column (units of 10²² atoms per cm⁻²)."

src/meta-models/caching.jl

@@ -11,6 +11,22 @@ mutable struct CacheEntry{T}
     end
 end
 
+"""
+    AutoCache
+
+Used to automatically create a cache of another model, to avoid re-evaluating
+the model if the next parameters are close to the previous parameters. The
+intended use is for fitting expensive models which.
+
+## Example
+
+```julia
+model = PhotoelectricAbsorption() * AutoCache(PowerLaw())
+```
+
+In the above model, the [`PowerLaw`](@ref) component will be augmented with the
+caching behaviour.
+"""
 struct AutoCache{M,T,K,C<:CacheEntry} <: AbstractModelWrapper{M,T,K}
     model::M
     cache::C

src/meta-models/functions.jl

@@ -1,3 +1,17 @@
+"""
+    AsConvolution
+
+Turn an additive model into a convolutional model.
+
+## Example
+
+```
+convolution_model = AsConvolution(GaussianLine())
+```
+
+The above model will now convolve the [`GaussianLine`](@ref) model onto whatever
+it is applied to.
+"""
 struct AsConvolution{M,T,V,P} <: AbstractModelWrapper{M,T,Convolutional}
     model::M
     # the domain on which we evaluate this model
@@ -79,3 +93,5 @@ function Reflection.make_constructor(
         Reflection.make_constructor(Model, closures[(num_closures+1):end], model_params, T)
     :($(Base.typename(M).name)($(model_constructor), $(my_closures...)))
 end
+
+export AsConvolution

test/models/test-model-consistency.jl

@@ -1,5 +1,6 @@
 using Test
 using SpectralFitting
+using XSPECModels
 
 
 # ensure PowerLaw and XS_PowerLaw behave exactly the same