From 6bebc936e4da06a313ff7c44b4a8b6fc1bae8a78 Mon Sep 17 00:00:00 2001
From: Tamas Gal <himself@tamasgal.com>
Date: Fri, 8 Nov 2024 09:14:11 +0100
Subject: [PATCH] Update docs

---
 docs/make.jl                |  1 +
 docs/src/api.md             |  2 ++
 docs/src/manual/auxfiles.md | 39 +++++++++++++++++++++++++++++++++++++
 src/exports.jl              |  1 +
 src/hardware.jl             | 21 +++++++++++++++++++-
 5 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/manual/auxfiles.md

diff --git a/docs/make.jl b/docs/make.jl
index aebbbd8a..af53b792 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -18,6 +18,7 @@ makedocs(;
             "manual/rootfiles.md",
             "manual/detector.md",
             "manual/calibration.md",
+            "manual/auxfiles.md",
             "manual/tools.md",
         ],
         "Examples" => Any[
diff --git a/docs/src/api.md b/docs/src/api.md
index 6d85e871..2066fa70 100644
--- a/docs/src/api.md
+++ b/docs/src/api.md
@@ -53,6 +53,8 @@ flush
 PMT
 DetectorModule
 Detector
+PMTFile
+PMTData
 modules
 getmodule
 getpmt
diff --git a/docs/src/manual/auxfiles.md b/docs/src/manual/auxfiles.md
new file mode 100644
index 00000000..82903c1a
--- /dev/null
+++ b/docs/src/manual/auxfiles.md
@@ -0,0 +1,39 @@
+# Auxiliary Files
+
+There are a bunch of auxiliary file formats in KM3NeT which are used in
+different stages of processing and calibration procedures. `KM3io.jl`
+supports many of them by defining a container type and extending the
+`Base.read` function so that the general pattern is:
+
+```
+f = read("path/to/the.file", FileContainerType)
+```
+
+
+## PMT File
+
+The container type [`PMTFile`](@ref) is used to load PMT files which are produced
+by the K40 calibration procedure in Jpp.
+
+Below is an example, using a PMT file from the
+[`KM3NeTTestData.jl`](https://git.km3net.de/km3py/km3net-testdata) package.
+
+```@example 1
+using KM3io
+using KM3NeTTestData
+
+pmtfile = read(datapath("pmt", "calibration_00000117_H_1.0.0_00013757_00013826_1.txt"), PMTFile)
+```
+
+Data for individual PMTs can be accessed by indexing using the module ID and the DAQ channel ID of the PMT:
+
+```@example 1
+pmtdata = pmtfile[806451572, 4]
+pmtdata.gain
+```
+
+The returned type is [`PMTData`](@ref) with following fields:
+
+```@example 1
+fieldnames(typeof(pmtdata))
+```
diff --git a/src/exports.jl b/src/exports.jl
index 07cfd71b..c039ca30 100644
--- a/src/exports.jl
+++ b/src/exports.jl
@@ -23,6 +23,7 @@ StringMechanics,
 StringMechanicsParameters,
 Tripod,
 PMTFile,
+PMTData,
 center,
 getmodule,
 getpmt,
diff --git a/src/hardware.jl b/src/hardware.jl
index 970f9715..d7f63b99 100644
--- a/src/hardware.jl
+++ b/src/hardware.jl
@@ -758,6 +758,11 @@ struct PMTParameters
 end
 Base.isvalid(p::PMTParameters) = !(p.QE < 0 || p.gain < 0 || p.gainSpread < 0 || p.threshold < 0 || p.thresholdBand < 0)
 
+"""
+
+PMT parameters as stored in [`PMTFile`](@ref)s.
+
+"""
 struct PMTData
     QE::Float64
     gain::Float64
@@ -767,6 +772,20 @@ struct PMTData
     threshold::Float64
 end
 
+"""
+
+A container type to hold PMT data which are stored in "PMT files", created by
+K40 calibrations. This type can be passe to `Base.read` to load the contents
+of such a file.
+
+# Example
+
+```
+julia> f = read("path/to/pmt.txt", PMTFile)
+PMTFile containing parameters of 7254 PMTs
+```
+
+"""
 struct PMTFile
     QE::Float64  # relative quantum efficiency
     mu::Float64
@@ -784,7 +803,7 @@ Base.getindex(p::PMTFile, dom_id::Integer, channel_id::Integer) = p.pmt_data[dom
 Read PMT parameters from a K40 calibration output file.
 
 """
-function read(filename::AbstractString, T::Type{PMTFile})
+function read(filename::AbstractString, ::Type{PMTFile})
     pmt_data = Dict{Tuple{Int, Int}, PMTData}()
     fobj = open(filename, "r")
     comments, content = _split_comments(readlines(fobj), "#")
-- 
GitLab