Merge pull request #10 from hanak/add-documentation-on-specifiers

Add documentation to CA and CPP

docs/api.rst

@@ -209,14 +209,28 @@ Helper Functions and Classes
 ----------------------------
 
 ..  function::
+    CA(record)
     CP(record)
-    MS(record)
+    CPP(record)
     NP(record)
     PP(record)
+    MS(record)
+    MSS(record)
+    MSI(record)
+    NMS(record)
 
     Used for record links to add the appropriate processing annotation to the
     link.
 
+    Example (Python source)::
+
+        other_record = records.ai('other')
+        my_record.INP = PP(MS(other_record))
+
+    Example (Generated DB)::
+
+        field(INP, "other PP MS")
+
 ..  class::
     ConstArray(iterator)
 

epicsdbbuilder/recordbase.py

@@ -8,7 +8,10 @@
 from .recordset import recordset
 
 
-__all__ = ['PP', 'CA', 'CP', 'CPP', 'MS', 'NP', 'ImportRecord']
+__all__ = [
+    'PP', 'CA', 'CP', 'CPP', 'NP',
+    'MS', 'MSS', 'MSI', 'NMS',
+    'ImportRecord']
 
 
 
@@ -304,34 +307,140 @@ def Value(self):
 
 # Some helper routines for building links
 
-# "Process Passive": any record update through a PP output link will be
-# processed if its scan is Passive.
 def PP(record):
+    """ "Process Passive": any record update through a PP output link will be
+    processed if its scan is Passive.
+
+    Example (Python source)
+    -----------------------
+    `my_record.INP = PP(other_record)`
+
+    Example (Generated DB)
+    ----------------------
+    `field(INP, "other PP")`
+    """
     return record('PP')
 
-# "Channel Access": a CA (input or output) link will be treated as a channel access link
-# regardless whether it is a DB link or not.
+
 def CA(record):
+    """ "Channel Access": a CA (input or output) link will be treated as
+    a channel access link regardless whether it is a DB link or not.
+
+    Example (Python source)
+    -----------------------
+    `my_record.INP = CA(other_record)`
+
+    Example (Generated DB)
+    ----------------------
+    `field(INP, "other CA")`
+    """
     return record('CA')
 
-# "Channel Process": a CP input link will cause the linking record to process
-# any time the linked record is updated.
+
 def CP(record):
+    """ "Channel Process": a CP input link will cause the linking record
+    to process any time the linked record is updated.
+
+    Example (Python source)
+    -----------------------
+    `my_record.INP = CP(other_record)`
+
+    Example (Generated DB)
+    ----------------------
+    `field(INP, "other CP")`
+    """
     return record('CP')
 
-# "Channel Process if Passive": a CP input link will be treated as a channel access link
-# and if the linking record is passive, the linking passive record will be processed
-# any time the linked record is updated.
+
 def CPP(record):
+    """ "Channel Process if Passive": a CP input link will be treated as
+    a channel access link and if the linking record is passive,
+    the linking passive record will be processed any time the linked record
+    is updated.
+
+    Example (Python source)
+    -----------------------
+    `my_record.INP = CPP(other_record)`
+
+    Example (Generated DB)
+    ----------------------
+    `field(INP, "other CPP")`
+    """
     return record('CPP')
 
-# "Maximise Severity": any alarm state on the linked record is propogated to
-# the linking record.
+
 def MS(record):
+    """ "Maximise Severity": any alarm state on the linked record is propagated
+    to the linking record. When propagated, the alarm status will become
+    `LINK_ALARM`.
+
+    Example (Python source)
+    -----------------------
+    `my_record.INP = MS(other_record)`
+
+    Example (Generated DB)
+    ----------------------
+    `field(INP, "other MS")`
+    """
     return record('MS')
 
-# "No Process": the linked record is not processed.
+
+def MSS(record):
+    """ "Maximise Status and Severity": both alarm status and alarm severity
+    on the linked record are propagated to the linking record.
+
+    Example (Python source)
+    -----------------------
+    `my_record.INP = MSS(other_record)`
+
+    Example (Generated DB)
+    ----------------------
+    `field(INP, "other MSS")`
+    """
+    return record('MSS')
+
+
+def MSI(record):
+    """ "Maximise Severity if Invalid": propagate an alarm state on the linked
+    record only if the alarm severity is `INVALID_ALARM`.
+    When propagated, the alarm status will become `LINK_ALARM`.
+
+    Example (Python source)
+    -----------------------
+    `my_record.INP = MSI(other_record)`
+
+    Example (Generated DB)
+    ----------------------
+    `field(INP, "other MSI")`
+    """
+    return record('MSI')
+
+
+def NMS(record):
+    """ "Non-Maximise Severity": no alarm is propagated.
+    This is the default behavior of EPICS links.
+
+    Example (Python source)
+    -----------------------
+    `my_record.INP = NMS(other_record)`
+
+    Example (Generated DB)
+    ----------------------
+    `field(INP, "other NMS")`
+    """
+    return record('NMS')
+
+
 def NP(record):
-    return record('NPP')
+    """ "No Process": the linked record is not processed.
+    This is the default behavior of EPICS links.
+
+    Example (Python source)
+    -----------------------
+    `my_record.INP = NP(other_record)`
 
-# ... put the rest in some time
+    Example (Generated DB)
+    ----------------------
+    `field(INP, "other NPP")`
+    """
+    return record('NPP')

examples/test.py

@@ -42,6 +42,10 @@
 records.ai('OPTIONS:CA', INP = CA(t))
 records.ai('OPTIONS:CP', INP = CP(t))
 records.ai('OPTIONS:CPP', INP = CPP(t))
+records.ai('OPTIONS:NP', INP = NP(t))
+records.ai('OPTIONS:MSS', INP = MSS(t))
+records.ai('OPTIONS:MSI', INP = MSI(t))
+records.ai('OPTIONS:NMS', INP = NMS(t))
 
 # Test multiple link options
 records.ai('OPTIONS:PP:MS', INP = PP(MS(t)))