fix: Add some documentation fixes

docs/src/models/xspec-models.md

@@ -20,7 +20,7 @@ using SpectralFitting, XSPECModels
     The convention is that models that have are imported from XSPEC or have XSPEC ABI are prefixed with `XS_` in their name. For example, the XSPEC equivalent of [`PowerLaw`](@ref) is [`XS_PowerLaw`](@ref).
 
 
-The XSPEC models are wrapped into SpectralFitting models using the [`@xspecmodel`] macro. If a model you require is not already wrapped, this macro will make that easy to do. Please consider upstreaming your wrapper via a PR to the SpectralFitting GitHub repository.
+The XSPEC models are wrapped into SpectralFitting models using the [`XSPECModels.@xspecmodel`] macro. If a model you require is not already wrapped, this macro will make that easy to do. Please consider upstreaming your wrapper via a PR to the SpectralFitting GitHub repository.
 
 ```@docs
 @xspecmodel
@@ -45,4 +45,4 @@ XS_WarmAbsorption
 XS_CalculateFlux
 XS_KerrDisk
 XS_KyrLine
-```
+```

docs/src/reference.md

@@ -4,6 +4,7 @@
 
 ```@docs
 SpectralFitting.AbstractMultiDataset
+SpectralFitting.AbstractStatistic
 SpectralFitting.ParameterTriple
 SpectralFitting.AbstractTableModel
 SpectralFitting.Constant
@@ -31,4 +32,6 @@ XSPECModels.XS_Optxagnf
 XSPECModels.XS_Jet
 XSPECModels.XS_CutOffPowerLaw
 XSPECModels.XS_Kerrconv
+XSPECModels._safe_ffi_invoke!
+XSPECModels._unsafe_ffi_invoke!
 ```

docs/src/walkthrough.md

@@ -18,7 +18,7 @@ The first thing we want to do is load our datasets. Unlike in XSPEC, we have no
 using SpectralFitting, XSPECModels, Plots
 
 DATADIR = "..."
-DATADIR = length(get(ENV, "CI", "")) > 0 ? @__DIR__() * "/../../ex-datadir" : expanduser("~/developer/jl/ex-datadir") # hide
+DATADIR = normpath(@__DIR__(), "..", "..", "ex-datadir") # hide
 spec1_path = joinpath(DATADIR, "s54405.pha")
 data = OGIPDataset(spec1_path)
 ```
@@ -38,7 +38,7 @@ To visualize our data, we can use some of the [Plots.jl](https://docs.juliaplots
 plot(data, xlims = (0.5, 70), xscale = :log10)
 ```
 
-Note that the units are currently not divided by the energy bin widths. We can either do that manually, or use the [`normalize!`](@ref) to convert whatever units the data is currently in to the defacto standard `counts s⁻¹ keV⁻¹` for fitting. Whilst we're at it, we see in the model card that there are 40 [bad quality bins](https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007.pdf) still present in our data. We can drop those as well, and plot the data on log-log axes:
+Note that the units are currently not divided by the energy bin widths. We can either do that manually, or use the [`normalize!`](@ref) to convert whatever units the data is currently in to the de facto standard `counts s⁻¹ keV⁻¹` for fitting. Whilst we're at it, we see in the model card that there are 40 [bad quality bins](https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007.pdf) still present in our data. We can drop those as well, and plot the data on log-log axes:
 
 ```@example walk
 normalize!(data)
@@ -100,11 +100,7 @@ result = fit(prob, LevenbergMarquadt())
 Here we can see the parameter vector, the estimated error on each parameter, and the measure of the fit statistic (here chi squared). We can overplot our result on our data easily:
 
 ```@example walk
-plot(data,
-    ylims = (0.001, 2.0),
-    xscale = :log10,
-    yscale = :log10
-)
+plot(data, ylims = (0.001, 2.0), xscale = :log10, yscale = :log10)
 plot!(result)
 ```
 
@@ -116,11 +112,7 @@ result = fit(prob, LevenbergMarquadt())
 ```
 
 ```@example walk
-plot(data,
-    ylims = (0.001, 2.0),
-    xscale = :log10,
-    yscale = :log10
-)
+plot(data, ylims = (0.001, 2.0), xscale = :log10, yscale = :log10)
 plot!(result, label = "PowerLaw")
 ```
 
@@ -146,7 +138,7 @@ Note we have set the random number generator seed with `seed = 42` to allow our
 
 The `goodness` command will return the percent of simulations with a fit statistic better than the result, in addition to the statistics of each individual trial.
 
-Next we want to calculate the flux in an energy range observed by the detector. We can do this with [`LogFlux`](@ref) or [`XS_CalculateFlux`](@ref), as they are both equivalent implementations.
+Next we want to calculate the flux in an energy range observed by the detector. We can do this with [`Log10Flux`](@ref) or [`XS_CalculateFlux`](@ref), as they are both equivalent implementations.
 
 We can modify our model by accessing properties from the model card and writing a new expression:
 
@@ -177,11 +169,7 @@ Now to fit we can repeat the above procedure, and even overplot the region of fl
 ```@example walk
 flux_result = fit(flux_problem, LevenbergMarquadt())
 
-plot(data,
-    ylims = (0.001, 2.0),
-    xscale = :log10,
-    yscale = :log10
-)
+plot(data, ylims = (0.001, 2.0), xscale = :log10, yscale = :log10)
 plot!(flux_result)
 vspan!([flux_model.c1.E_min.value, flux_model.c1.E_max.value], alpha = 0.5)
 ```
@@ -202,11 +190,9 @@ result2 = fit!(prob2, LevenbergMarquadt())
 Let's overplot this result against our power law result:
 
 ```@example walk
-dp = plot(data,
-    ylims = (0.001, 2.0),
-    xscale = :log10,
-    yscale = :log10,
-    legend = :bottomleft,
+dp = plot(
+    data, ylims = (0.001, 2.0),
+    xscale = :log10, yscale = :log10, legend = :bottomleft,
 )
 plot!(dp, result, label = "PowerLaw $(round(sum(result.stats)))")
 plot!(dp, result2, label = "BlackBody $(round(sum(result2.stats)))")
@@ -254,11 +240,9 @@ We can do all that plotting work with some of the builtin recipes:
 
 ```@example walk
 function plot_result(data, results...)
-    p1 = plot(data,
-        ylims = (0.001, 2.0),
-        xscale = :log10,
-        yscale = :log10,
-        legend = :bottomleft,
+    p1 = plot(
+        data, ylims = (0.001, 2.0),
+        xscale = :log10, yscale = :log10, legend = :bottomleft,
     )
     p2 = plot(xscale = :log10)
     for r in results
@@ -389,11 +373,8 @@ Using PairPlots.jl to create corner plots:
 ```@example walk
 import PairPlots, Makie, CairoMakie
 
-table = (; # named tuple syntax
-    K = vec(chain["K"]),
-    a = vec(chain["a"]),
-    ηH = vec(chain["ηH"])
-)
+# named tuple syntax
+table = (; K = vec(chain[:K]), a = vec(chain[:a]), ηH = vec(chain[:ηH]))
 
 PairPlots.pairplot(table)
 ```

src/abstract-models.jl

@@ -61,7 +61,7 @@ struct Convolutional <: AbstractSpectralModelKind end
     abstract type AbstractSpectralModel{T,K<:AbstractSpectralModelKind} end
 
 Supertype of all spectral models, tracking the number type `T` and
-[`AbstractSpectralModelKind`](@def) denoted `K`.
+[`AbstractSpectralModelKind`](@ref) denoted `K`.
 
 ## Implementation
 

src/datasets/spectraldata.jl

@@ -392,7 +392,7 @@ end
 
 Unfold the dataset using the response and ancillary, as in e.g. ISIS.
 
-Returns a new [`Spectrum`](@abs) that has had the domain masking applied.
+Returns a new [`Spectrum`](@ref) that has had the domain masking applied.
 """
 function unfold(data::SpectralData)
     unfolded, variance = if has_ancillary(data)

src/model-data-io.jl

@@ -81,8 +81,8 @@ consequently model data is only downloaded when needed.
 
 !!! note
     It is good practice to use this method immediately after defining a new
-    model with [`@xspecmodel`](@ref) to register any required datafiles from
-    the HEASoft source code, and therefore keep relevant information together.
+    model with [`XSPECModels.@xspecmodel`](@ref) to register any required datafiles
+    from the HEASoft source code, and therefore keep relevant information together.
 
 # Example
 

src/statistics.jl

@@ -1,3 +1,8 @@
+"""
+$(TYPEDEF)
+
+Abstract supertype for all statistic measures.
+"""
 abstract type AbstractStatistic end
 statistic_symbol(s::AbstractStatistic) = Base.typename(typeof(s)).name
 reduced_statistic_symbol(s::AbstractStatistic) = statistic_symbol(s) * "_reduced"