doc pvaTestClient

documentation/Doxyfile

@@ -768,6 +768,7 @@ WARN_LOGFILE           =
 INPUT                  = ../src/client/pv \
                          ../src/utils/pv \
                          ../src/pva/pv \
+                         ../src/testing/pv \
                          .
 
 # This tag can be used to specify the character encoding of the source files

src/testing/pv/pvaTestClient.h

@@ -17,6 +17,7 @@ class Monitor;
 class Configuration;
 }}//namespace epics::pvAccess
 
+//! Information on get/put/rpc completion
 struct epicsShareClass TestOperation
 {
     struct Impl
@@ -36,22 +37,26 @@ protected:
     std::tr1::shared_ptr<Impl> impl;
 };
 
+//! Information on put completion
 struct epicsShareClass TestPutEvent
 {
     enum event_t {
-        Fail,
-        Cancel,
-        Success,
+        Fail,    //!< request ends in failure.  Check message
+        Cancel,  //!< request cancelled before completion
+        Success, //!< It worked!
     } event;
     std::string message;
     void *priv;
 };
 
+//! Information on get/rpc completion
 struct epicsShareClass TestGetEvent : public TestPutEvent
 {
+    //! New data. NULL unless event==Success
     epics::pvData::PVStructure::const_shared_pointer value;
 };
 
+//! Handle for monitor subscription
 struct epicsShareClass TestMonitor
 {
     struct Impl;
@@ -74,23 +79,26 @@ protected:
     std::tr1::shared_ptr<Impl> impl;
 };
 
+//! Information on monitor subscription/queue change
 struct epicsShareClass TestMonitorEvent
 {
     enum event_t {
-        Fail=1,      // subscription ends in an error
-        Cancel=2,    // subscription ends in cancellation
-        Disconnect=4,// subscription interrupted to do lose of communication
-        Data=8,      // Data queue not empty
+        Fail=1,      //!< subscription ends in an error
+        Cancel=2,    //!< subscription ends in cancellation
+        Disconnect=4,//!< subscription interrupted to do lose of communication
+        Data=8,      //!< Data queue not empty.  Call TestMonitor::poll()
     } event;
     std::string message; // set for event=Fail
     void *priv;
 };
 
+//! informaiton on connect/disconnect
 struct epicsShareClass TestConnectEvent
 {
     bool connected;
 };
 
+//! Represents a single channel
 class epicsShareClass TestClientChannel
 {
     struct Impl;
@@ -108,24 +116,31 @@ public:
                       const Options& opt = Options());
     ~TestClientChannel();
 
+    //! callback for get() and rpc()
     struct epicsShareClass GetCallback {
         virtual ~GetCallback() {}
         virtual void getDone(const TestGetEvent& evt)=0;
     };
 
+    //! Issue request to retrieve current PV value
     TestOperation get(GetCallback* cb,
                       epics::pvData::PVStructure::const_shared_pointer pvRequest = epics::pvData::PVStructure::const_shared_pointer());
 
+    //! Start an RPC call
     TestOperation rpc(GetCallback* cb,
                       const epics::pvData::PVStructure::const_shared_pointer& arguments,
                       epics::pvData::PVStructure::const_shared_pointer pvRequest = epics::pvData::PVStructure::const_shared_pointer());
 
+    //! callbacks for put()
     struct epicsShareClass PutCallback {
         virtual ~PutCallback() {}
+        //! Called to build the value to be sent once the type info is known
         virtual epics::pvData::PVStructure::const_shared_pointer putBuild(const epics::pvData::StructureConstPtr& build) =0;
         virtual void putDone(const TestPutEvent& evt)=0;
     };
 
+    //! Initiate request to change PV
+    //! TODO: produce bitset to mask fields being set
     TestOperation put(PutCallback* cb,
                       epics::pvData::PVStructure::const_shared_pointer pvRequest = epics::pvData::PVStructure::const_shared_pointer());
 
@@ -134,20 +149,25 @@ public:
         virtual void monitorEvent(const TestMonitorEvent& evt)=0;
     };
 
+    //! Begin subscription
     TestMonitor monitor(MonitorCallback *cb,
                           epics::pvData::PVStructure::const_shared_pointer pvRequest = epics::pvData::PVStructure::const_shared_pointer());
 
+    //! Connection state change CB
     struct epicsShareClass ConnectCallback {
         virtual ~ConnectCallback() {}
         virtual void connectEvent(const TestConnectEvent& evt)=0;
     };
+    //! Append to list of listeners
     void addConnectListener(ConnectCallback*);
+    //! Remove from list of listeners
     void removeConnectListener(ConnectCallback*);
 
 private:
     std::tr1::shared_ptr<epics::pvAccess::Channel> getChannel();
 };
 
+//! Central client context.
 class epicsShareClass TestClientProvider
 {
     std::tr1::shared_ptr<epics::pvAccess::ChannelProvider> provider;
@@ -157,6 +177,8 @@ public:
                        const std::tr1::shared_ptr<epics::pvAccess::Configuration>& conf = std::tr1::shared_ptr<epics::pvAccess::Configuration>());
     ~TestClientProvider();
 
+    //! Get a new Channel
+    //! Does not block.
     TestClientChannel connect(const std::string& name,
                               const TestClientChannel::Options& conf = TestClientChannel::Options());
 };