From 9255256f1524fd7cc9cf43639aae65d397ac9cf6 Mon Sep 17 00:00:00 2001
From: Saeed Haghtalab <saeed.haghtalab@esss.se>
Date: Fri, 6 Sep 2019 15:48:46 +0200
Subject: [PATCH] Added POD to permissive record with a note that it is
 deprecated.

---
 src/std/rec/permissiveRecord.dbd.pod | 150 +++++++++++++++++++++++++--
 1 file changed, 139 insertions(+), 11 deletions(-)

diff --git a/src/std/rec/permissiveRecord.dbd.pod b/src/std/rec/permissiveRecord.dbd.pod
index 7eb04bf95..8e0747fe9 100644
--- a/src/std/rec/permissiveRecord.dbd.pod
+++ b/src/std/rec/permissiveRecord.dbd.pod
@@ -6,8 +6,114 @@
 # EPICS BASE is distributed subject to a Software License Agreement found
 # in file LICENSE that is included with this distribution.
 #*************************************************************************
+
+=head1 Permissive Record (permissive)
+
+The permissive record is for communication between a server and a client. An
+example would be a sequence program server and an operator interface client.  By
+using multiple permissive records a sequence program can communicate its current
+state to the client.
+
+B<Note that this record is deprecated and will probably be removed from future EPICS base releases.>
+
+=head2 Contents
+
+=over
+
+=item * L<Parameter Fields>
+
+=over
+
+=item * L<Scan Parameters>
+
+=item * L<Client-server Parameters>
+
+=item * L<Operator Display Parameters>
+
+=item * L<Alarm Parameters>
+
+=item * L<Run-time Parameters>
+
+=back
+
+=item * L<Record Support>
+
+=over
+
+=item * L<Record Support Routines (permissiveRecord.c)>
+
+=back
+
+=back
+
+=begin html
+
+<br>
+<hr>
+<br>
+
+=end html
+
+=recordtype permissive
+
+=cut
+
 recordtype(permissive) {
 	include "dbCommon.dbd" 
+
+=head2 Parameter Fields
+
+=head3 Scan Parameters
+
+The permissive record has the standard fields for specifying under what
+circumstances the record will be processed. These fields are listed in 
+L<Scan Fields|https://wiki-ext.aps.anl.gov/epics/index.php/RRM_3-14_dbCommon#Scan_Fields>. 
+In addition, 
+L<Scanning Specification|https://wiki-ext.aps.anl.gov/epics/index.php/RRM_3-14_Concepts#Scanning_Specification>
+ explains how these fields are used. Since the permissive record supports 
+ no direct interfaces to hardware, its SCAN field cannot be C<<< I/O Intr >>>.
+
+=head3 Client-server Parameters
+
+The client and server communicate through the VAL and watchdog flag (WFLG)
+fields. At initialization, both fields are set equal to 0, which means OFF. The
+server sets WFLG equal to ON when it is ready to accept a request. The client
+monitors WFLG and when WFLG equals 1, the client-server action is performed (a
+private matter between server and client).
+
+When WFLG is off--when the server is busy--the client program may turn the VAL
+field from OFF to ON. After the server finishes its task, it will notice that
+VAL is ON and will turn both WFLG and VAL OFF and performs the requested
+service.
+
+Note that when WFLG is ON, the client program ''must not'' turn VAL to on.
+
+=fields VAL, WFLG
+
+=cut
+
+	field(VAL,DBF_USHORT) {
+		prompt("Status")
+		promptgroup("40 - Input")
+		asl(ASL0)
+		pp(TRUE)
+	}
+	field(WFLG,DBF_USHORT) {
+		prompt("Wait Flag")
+		pp(TRUE)
+	}
+
+=head3 Operator Display Parameters
+
+The label field (LABL) contains a string given to it that should describe the
+record in further detail. In  addition to the DESC field. See 
+L<Fields Common to All Record Types|https://wiki-ext.aps.anl.gov/epics/index.php/RRM_3-14_dbCommon#Fields_Common_to_All_Record_Types> 
+for more on the record name (NAME) and description (DESC) fields.
+
+=fields LABL, NAME, DESC
+
+=cut
+
 	field(LABL,DBF_STRING) {
 		prompt("Button Label")
 		promptgroup("80 - Display")
@@ -15,24 +121,46 @@ recordtype(permissive) {
 		interest(1)
 		size(20)
 	}
-	field(VAL,DBF_USHORT) {
-		prompt("Status")
-		promptgroup("40 - Input")
-		asl(ASL0)
-		pp(TRUE)
-	}
+
+=head3 Alarm Parameters
+
+The Permissive record has the alarm parameters common to all record types. 
+L<Alarm Fields|https://wiki-ext.aps.anl.gov/epics/index.php/RRM_3-14_dbCommon#Alarm_Fields> 
+lists other fields related to a alarms that are common to all record types.
+
+=head3 Run-time Parameters
+
+These fields are used to trigger monitors for each field. Monitors for the VAL
+field are triggered when OVAL, the old value field, does not equal VAL.
+Likewise, OFLG causes monitors to be invoked for WFLG when WFLG does not equal
+OLFG.
+
+=fields OVAL, OFLG
+
+=cut
+
 	field(OVAL,DBF_USHORT) {
 		prompt("Old Status")
 		special(SPC_NOMOD)
 		interest(3)
 	}
-	field(WFLG,DBF_USHORT) {
-		prompt("Wait Flag")
-		pp(TRUE)
-	}
 	field(OFLG,DBF_USHORT) {
 		prompt("Old Flag")
 		special(SPC_NOMOD)
 		interest(3)
 	}
-}
+
+=head2 Record Support
+
+=head3 Record Support Routines (permissiveRecord.c)
+
+=head4 process
+
+  long (*process)(struct dbCommon *precord)
+
+process sets UDF to FALSE, triggers monitors on VAL and WFLG when they change,
+and scans the forward link if necessary.
+
+=cut
+
+}
\ No newline at end of file