From 272b4fb9cb862fd0e58a73fe4e76f6c74bf5e02c Mon Sep 17 00:00:00 2001
From: Michael Davidsaver <mdavidsaver@gmail.com>
Date: Tue, 6 Mar 2018 01:02:08 -0500
Subject: [PATCH] update docs

---
 README.md                | 12 +++----
 documentation/Doxyfile   |  2 +-
 documentation/mainpage.h |  4 ++-
 documentation/qsrvpage.h | 69 +++++++++++++++++++++++++++++++++++++++-
 4 files changed, 78 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 8f03afd..5b3eb63 100644
--- a/README.md
+++ b/README.md
@@ -86,15 +86,15 @@ A full list of `info(Q:group` options.
 record(...) {
     info(Q:group, {
         "<group_name>":{
-            +id:"some/NT:1.0",  // top level ID
-            +meta:"FLD",        // map top level alarm/timeStamp
-            +atomic:true,       // whether monitors default to multi-locking atomicity
+            +id:"some/NT:1.0",  # top level ID
+            +meta:"FLD",        # map top level alarm/timeStamp
+            +atomic:true,       # whether monitors default to multi-locking atomicity
             "<field.name>":{
-                +type:"scalar", // controls how map VAL mapped onto <field.name>
+                +type:"scalar", # controls how map VAL mapped onto <field.name>
                 +channel:"VAL",
                 +id:"some/NT:1.0",
-                +trigger:"*",   // "*" or comma seperated list of <field.name>s
-                +putorder:0,    // set for fields where put is allowed, processing done in increasing order
+                +trigger:"*",   # "*" or comma seperated list of <field.name>s
+                +putorder:0,    # set for fields where put is allowed, processing done in increasing order
             }
         }
     })
diff --git a/documentation/Doxyfile b/documentation/Doxyfile
index bb3d147..c96c4ba 100644
--- a/documentation/Doxyfile
+++ b/documentation/Doxyfile
@@ -38,7 +38,7 @@ PROJECT_NAME           = pva2pva
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 0
+PROJECT_NUMBER         = 1.0.1-DEV
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
diff --git a/documentation/mainpage.h b/documentation/mainpage.h
index fd1f679..f72c683 100644
--- a/documentation/mainpage.h
+++ b/documentation/mainpage.h
@@ -5,11 +5,13 @@
 
 @section qsrv QSRV
 
-QSRV is a network server using the PVAccess protocol which
+@ref qsrv_page is a network server using the PVAccess protocol which
 runs inside an EPICS IOC process and allows clients
 to make requests to access the Process Variables (PVs)
 within.
 
+Configuration of @ref qsrv_group_def.
+
 @subsection qsrv_build Building
 
 To build the latest from version control
diff --git a/documentation/qsrvpage.h b/documentation/qsrvpage.h
index b2d65c8..721d1fa 100644
--- a/documentation/qsrvpage.h
+++ b/documentation/qsrvpage.h
@@ -45,6 +45,73 @@ record(ai, "rec:Y") {
 
 This group, named "grp:name", has two fields "X" and "Y".
 
-@subsection qsrv_group_sym Group PV semantics
+@code
+$ pvget grp:name
+grp:name
+structure 
+    epics:nt/NTScalar:1.0 X
+        double value 0
+        alarm_t alarm INVALID DRIVER UDF
+        time_t timeStamp <undefined> 0
+...
+    epics:nt/NTScalar:1.0 Y
+        double value 0
+        alarm_t alarm INVALID DRIVER UDF
+        time_t timeStamp <undefined> 0
+...
+@endcode
+
+@subsection qsrv_group_ref Group PV reference
+
+@code
+record(...) {
+    info(Q:group, {
+        "<group_name>":{
+            +id:"some/NT:1.0",  # top level ID
+            +meta:"FLD",        # map top level alarm/timeStamp
+            +atomic:true,       # whether monitors default to multi-locking atomicity
+            "<field.name>":{
+                +type:"scalar", # controls how map VAL mapped onto <field.name>
+                +channel:"VAL",
+                +id:"some/NT:1.0",
+                +trigger:"*",   # "*" or comma seperated list of <field.name>s
+                +putorder:0,    # set for fields where put is allowed, processing done in increasing order
+            }
+        }
+    })
+}
+@endcode
+
+@subsubsection qsrv_group_map_types Field mapping types
+
+@li "scalar" or ""
+@li "plain"
+@li "any"
+@li "meta"
+
+The "scalar" mapping places an NTScalar or NTScalarArray as a sub-structure.
+
+The "plain" mapping ignores all meta-data and places only the "value" as a field.
+The "value" is equivalent to '.value' of the equivalent NTScalar/NTScalarArray as a field.
+
+The "any" mapping places a variant union into which the "value" is placed.
+
+The "meta" mapping ignores the "value" and places only the alarm and time
+meta-data as sub-fields.
+The special group level tag 'meta:""' allows these meta-data fields to be
+placed in the top-level structure.
+
+@subsubsection qsrv_group_map_trig Field Update Triggers
+
+The field triggers define how changes to the consitutent field
+are translated into a subscription update to the group.
+
+The most use of these are "" which means that changes to the field
+are ignored, and do not result group update.
+And "*" which results in a group update containing the most recent
+values/meta-data of all fields.
+
+It may be useful to specify a comma seperated list of field names
+so that changes may partially update the group.
 
 */