From ecf823c6f699b7aa69cf23ca4537c3cc426308fe Mon Sep 17 00:00:00 2001
From: smathis <stefan.mathis@psi.ch>
Date: Wed, 1 Oct 2025 16:06:01 +0200
Subject: [PATCH] Added documentation to some of the records

---
 db/protoncurrent.db | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/db/protoncurrent.db b/db/protoncurrent.db
index a0014ea..6274b18 100644
--- a/db/protoncurrent.db
+++ b/db/protoncurrent.db
@@ -1,8 +1,18 @@
+# A collection of records which can be used to integrate the proton
+# signal coming from HIPA. Please see ../README.md for examples on how to use
+# them.
+# The individual records are described below.
+#
 # Macros
 # P - Prefix
 # AI - HIPA Beam Current PV
 # GATE - (optional) second gating PV
 
+# Switch to activate / deactivate the following records:
+# - $(P)BEAMINT: Used to integrate the proton count over time
+# - $(P)COUNTTIME: Used to compute the count time. 
+# Setting this record to 1 starts integration of the proton signal, setting it
+# to zero stops it.
 record(bi, "$(P)SWITCH")
 {
   field(DESC, "Gates signal intensity measurement")
@@ -30,6 +40,8 @@ record(ai, "$(P)BEAMCPY")
   field(SCAN, "Passive")
 }
 
+# This record reports the time since the start of the proton count integration.
+# This record is populated from $(P)COUNTTIME and only meant to be read.
 record(ai, "$(P)ACCTIME")
 {
   field(DESC, "Beam time accumulator")
@@ -51,6 +63,8 @@ record(calcout, "$(P)COUNTTIME")
   field(DOPT, "Use CALC")
 }
 
+# Integral proton count. This record is populated from $(P)BEAMINT and only
+# meant to be read. It is reset once the preset has been reached.
 record(ai, "$(P)ACCINT")
 {
   field(DESC, "Beam intensity accumulator")
@@ -73,6 +87,8 @@ record(calcout, "$(P)BEAMINT")
   field(FLNK, "$(P)PRESET-COUNTER")
 }
 
+# Preset value for the proton count. When the integral proton count stored in
+# $(P)ACCINT reaches this value, the integration is stopped.
 record(ai, "$(P)PRESET")
 {
   field(DESC, "max intensity count preset")