From 6267202fd4fda3f3b37cb246f15a18662ec3ffc7 Mon Sep 17 00:00:00 2001
From: Michael Davidsaver <mdavidsaver@gmail.com>
Date: Tue, 11 May 2021 13:08:10 -0700
Subject: [PATCH] doc

---
 documentation/example.rst | 22 ++++++++++++++++++----
 documentation/index.rst   |  2 +-
 example/Makefile          |  6 ++++++
 example/simpleget.cpp     | 31 +++++++++++++++++++++++++++++++
 example/simplesrv.cpp     | 36 ++++++++++++++++++++++++++++++++++++
 src/pvxs/data.h           | 13 +++++++++++++
 6 files changed, 105 insertions(+), 5 deletions(-)
 create mode 100644 example/simpleget.cpp
 create mode 100644 example/simplesrv.cpp

diff --git a/documentation/example.rst b/documentation/example.rst
index 0278397..4190c36 100644
--- a/documentation/example.rst
+++ b/documentation/example.rst
@@ -6,12 +6,19 @@ They can be found under example/O.\*
 
 Latest versions https://github.com/mdavidsaver/pvxs/blob/master/example/
 
-Mailbox Server
---------------
+Shortest Client Get
+-------------------
 
-.. literalinclude:: ../example/mailbox.cpp
+.. literalinclude:: ../example/simpleget.cpp
     :language: c++
-    :name: mailbox.cpp
+    :name: simpleget.cpp
+
+Shortest Server
+---------------
+
+.. literalinclude:: ../example/simplesrv.cpp
+    :language: c++
+    :name: simplesrv.cpp
 
 Client Demo
 -----------
@@ -19,3 +26,10 @@ Client Demo
 .. literalinclude:: ../example/client.cpp
     :language: c++
     :name: client.cpp
+
+Mailbox Server
+--------------
+
+.. literalinclude:: ../example/mailbox.cpp
+    :language: c++
+    :name: mailbox.cpp
diff --git a/documentation/index.rst b/documentation/index.rst
index 06b8fc4..4c1d7ce 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -40,13 +40,13 @@ See :ref:`relpolicy` for details.
    :caption: Contents:
 
    overview
+   example
    building
    cli
    value
    client
    server
    util
-   example
    details
    releasenotes
 
diff --git a/example/Makefile b/example/Makefile
index 0b418f1..ee93585 100644
--- a/example/Makefile
+++ b/example/Makefile
@@ -11,6 +11,9 @@ include $(TOP)/configure/CONFIG_PVXS_VERSION
 
 PROD_LIBS += pvxs Com
 
+TESTPROD_HOST += simplesrv
+simplesrv_SRCS += simplesrv.cpp
+
 TESTPROD_HOST += mailbox
 mailbox_SRCS += mailbox.cpp
 
@@ -20,6 +23,9 @@ spam_SRCS += spam.cpp
 TESTPROD_HOST += ticker
 ticker_SRCS += ticker.cpp
 
+TESTPROD_HOST += simpleget
+simpleget_SRCS += simpleget.cpp
+
 TESTPROD_HOST += client
 client_SRCS += client.cpp
 
diff --git a/example/simpleget.cpp b/example/simpleget.cpp
new file mode 100644
index 0000000..29c2654
--- /dev/null
+++ b/example/simpleget.cpp
@@ -0,0 +1,31 @@
+/**
+ * Copyright - See the COPYRIGHT that is included with this distribution.
+ * pvxs is distributed subject to a Software License Agreement found
+ * in file LICENSE that is included with this distribution.
+ */
+/** The short example of a client GET operation.
+ */
+
+#include <iostream>
+
+#include <pvxs/client.h>
+#include <pvxs/log.h>
+
+int main(int argc, char* argv[]) {
+    using namespace pvxs;
+
+    // (Optional) configuring logging using $PVXS_LOG
+    logger_config_env();
+
+    // Configure client using $EPICS_PVA_*
+    client::Context ctxt(client::Config::fromEnv().build());
+
+    // fetch PV "some:pv:name" and wait up to 5 seconds for a reply.
+    // (throws an exception on error, including timeout)
+    Value reply = ctxt.get("some:pv:name").exec()->wait(5.0);
+
+    // Reply is printed to stdout.
+    std::cout<<reply;
+
+    return 0;
+}
diff --git a/example/simplesrv.cpp b/example/simplesrv.cpp
new file mode 100644
index 0000000..0b17b95
--- /dev/null
+++ b/example/simplesrv.cpp
@@ -0,0 +1,36 @@
+/**
+ * Copyright - See the COPYRIGHT that is included with this distribution.
+ * pvxs is distributed subject to a Software License Agreement found
+ * in file LICENSE that is included with this distribution.
+ */
+/** The short example of a server.
+ */
+
+#include <iostream>
+
+#include <pvxs/server.h>
+#include <pvxs/sharedpv.h>
+#include <pvxs/nt.h>
+#include <pvxs/log.h>
+
+int main(int argc, char* argv[]) {
+    using namespace pvxs;
+
+    // (Optional) configuring logging using $PVXS_LOG
+    logger_config_env();
+
+    // Use pre-defined NTScalar structure w/ double for primary value field.
+    Value initial = nt::NTScalar{TypeCode::Float64}.create();
+    initial["value"] = 42.0;
+
+    // Storage and access for network visible Process Variable
+    server::SharedPV pv(server::SharedPV::buildMailbox());
+    pv.open(initial);
+
+    server::Config::fromEnv()        // Configure a server using $EPICS_PVAS_* or $EPICS_PVA_*
+            .build()
+            .addPV("my:pv:name", pv) // add (and name) one local PV
+            .run();                  // run until SIGINT
+
+    return 0;
+}
diff --git a/src/pvxs/data.h b/src/pvxs/data.h
index 2553ee7..83a692d 100644
--- a/src/pvxs/data.h
+++ b/src/pvxs/data.h
@@ -741,6 +741,7 @@ public:
     inline
     IMarked imarked() const noexcept;
 
+    //! Provides options to control printing of a Value via std::ostream.
     struct Fmt {
         const Value* top = nullptr;
         size_t _limit=0u;
@@ -751,12 +752,24 @@ public:
         bool _showValue = true;
 
         Fmt(const Value* top) :top(top) {}
+        //! Show Value in tree/struct format
         Fmt& tree() { _format = Tree; return *this; }
+        //! Show Value in delta format
         Fmt& delta()  { _format = Delta ; return *this; }
+        //! Explicitly select format_t
         Fmt& format(format_t f) { _format = f ; return *this; }
+        //! Whether to show field values, or only type information
         Fmt& showValue(bool v) { _showValue = v; return *this; }
+        //! When non-zero, arrays output will be truncated with "..." after cnt elements.
         Fmt& arrayLimit(size_t cnt) { _limit = cnt; return *this; }
     };
+    /** Configurable printing via std::ostream
+     *
+     * @code
+     * Value val;
+     * std::cout<<val.format().arrayLimit(10);
+     * @endcode
+     */
     inline Fmt format() const { return Fmt(this); }
 };