Add preliminary documentation to the VISION paper model

The paper does not seem to clearly say which distribution it is assuming - it only says it doesn't assume Gaussian. The model code is also not complete, so when that is updated, the documentation will have to be updated.

src/resolution_functions/models/vision_paper.py

@@ -1,3 +1,12 @@
+"""
+Model for TOSCA-like instruments from the [VISION paper]_.
+
+All classes here are exposed for reference only and should not be instantiated directly. For
+obtaining the resolution function of an instrument, please use the
+`Instrument.get_resolution_function` method.
+
+.. [VISION paper] https://doi.org/10.1016/j.nima.2009.03.204
+"""
 from __future__ import annotations
 
 from dataclasses import dataclass
@@ -11,10 +20,67 @@
     from jaxtyping import Float
 
 
-
-
 @dataclass(init=True, repr=True, frozen=True, slots=True, kw_only=True)
 class VisionPaperModelData(ModelData):
+    """
+    Data for the `VisionPaperModel` model.
+
+    Parameters
+    ----------
+    function
+        The name of the function, i.e. the alias for `PantherAbINSModel`.
+    citation
+        The citation for a particular model.
+    primary_flight_path
+        Distance between the moderator and the sample in meters (m).
+    primary_flight_path_uncertainty
+        The uncertainty associated with the `primary_flight_path`, in meters (m).
+    sample_thickness
+        Thickness of the sample in meters (m).
+    detector_thickness
+        Thickness of the detector in meters (m).
+    crystal_plane_spacing
+        Distance between the layers of atoms making up the detector, in meters (m).
+    d_r
+        Uncertainty associated with the detector offset, in meters (m).
+    d_t
+        Uncertainty associated with the source pulse shape, in ? (?).
+    angles
+        Angle between the sample and the analyser, in degrees.
+    distance_sample_analyzer
+        Distance between the sample and the analyser, in meters (m).
+    average_bragg_angle_graphite
+        Average Bragg angle of the graphite analyser, in degrees.
+
+    Attributes
+    ----------
+    function
+        The name of the function, i.e. the alias for `PantherAbINSModel`.
+    citation
+        The citation for the model. Please use this to look up more details and cite the model.
+    primary_flight_path
+        Distance between the moderator and the sample in meters (m).
+    primary_flight_path_uncertainty
+        The uncertainty associated with the `primary_flight_path`, in meters (m).
+    sample_thickness
+        Thickness of the sample in meters (m).
+    detector_thickness
+        Thickness of the detector in meters (m).
+    crystal_plane_spacing
+        Distance between the layers of atoms making up the detector, in meters (m).
+    d_r
+        Uncertainty associated with the detector offset, in meters (m).
+    d_t
+        Uncertainty associated with the source pulse shape, in ? (?).
+    angles
+        Angle between the sample and the analyser, in degrees.
+    distance_sample_analyzer
+        Distance between the sample and the analyser, in meters (m).
+    average_bragg_angle_graphite
+        Average Bragg angle of the graphite analyser, in degrees.
+    restrictions
+    defaults
+    """
     primary_flight_path: float
     primary_flight_path_uncertainty: float
     sample_thickness: float
@@ -28,7 +94,28 @@ class VisionPaperModelData(ModelData):
 
 
 class VisionPaperModel(InstrumentModel):
-    """https://doi.org/10.1016/j.nima.2009.03.204"""
+    """
+    Model for TOSCA-like instruments from the [VISION paper]_.
+
+    Models the resolution as a function of energy transfer (frequencies) only, with the output model
+    being an Ikeda-Carpenter distribution. This is done by taking into account the contributions
+    from the various parts of the instrument (for more information, please see the reference).
+
+    Parameters
+    ----------
+    model_data
+        The data associated with the model for a given version of a given instrument.
+
+    Attributes
+    ----------
+    input
+        The input that the ``__call__`` method expects.
+    output
+        The output of the ``__call__`` method.
+    data_class
+        Reference to the `VisionPaperModelData` type.
+    citation
+    """
     input = 1
     output = 1
 
@@ -63,6 +150,20 @@ def __init__(self, model_data: VisionPaperModelData, **_):
         self.final_term = self.e0 / np.tan(self.theta) / self.z2 * model_data.d_r
 
     def __call__(self, frequencies: Float[np.ndarray, 'frequencies']) -> Float[np.ndarray, 'sigma']:
+        """
+        Evaluates the model at given energy transfer values (`frequencies`), returning the
+        corresponding Ikeda-Carpenter widths (FWHM).
+
+        Parameters
+        ----------
+        frequencies
+            Energy transfer in meV. The frequencies at which to return widths.
+
+        Returns
+        -------
+        fwhm
+            The Ikeda-Carpenter widths at `frequencies` as predicted by this model.
+        """
         e1 = frequencies * self.REDUCED_PLANCK + self.e0 * (1 / np.sin(self.theta))
         z0 = self.l1 * (self.e0 / e1) ** 0.5
         one_over_z0 = 1 / z0