update doc

documentation/mainpage.dox

@@ -23,33 +23,32 @@ See pv/pvData.h header.
 Define a structure type and create a container with default values.
 
 @code
-epics::pvData::StructureConstPtr stype; // aka std::tr1::shared_ptr<const epics::pvData::Structure>
-stype = epics::pvData::getFieldCreate()->createFieldBuilder()
-                        ->add("fld1", epics::pvData::pvInt)
+namespace pvd = epics::pvData;
+pvd::StructureConstPtr stype(pvd::FieldBuilder::begin()
+                        ->add("fld1", pvd::pvInt)
                         ->addNestedStructure("sub")
-                            ->add("fld2", epics::pvData::pvString)
+                            ->add("fld2", pvd::pvString)
                         ->endNested()
-                        ->createStructure();
+                        ->createStructure());
 
-epics::pvData::PVStructuretPtr value; // aka std::tr1::shared_ptr<epics::pvData::PVStructure>
-value = epics::pvData::getPVDataCreate()->createPVStructure(stype);
+pvd::PVStructuretPtr value(stype->build());
 
-value->getSubField<epics::pvData::PVInt>("fld1")->put(4); // store integer 4
-value->getSubField<epics::pvData::PVScalar>("sub.fld2")->putFrom(4.2); // convert and store string "4.2"
+value->getSubFieldT<pvd::PVInt>("fld1")->put(4); // store integer 4.  would throw if not pvInt
+value->getSubFieldT<pvd::PVScalar>("sub.fld2")->putFrom(4.2); // convert and store string "4.2"
 @endcode
 
 is equivalent to the following pseudo-code.
 
 @code
 struct stype {
-    epics::pvData::int32 fld1;
+    pvd::int32 fld1;
     struct {
         std::string fld2;
     } sub;
 };
 stype value;
 value.fld1 = 4;
-value.fld2 = epics::pvData::castUnsafe<std::string>(4.2);
+value.fld2 = pvd::castUnsafe<std::string>(4.2);
 @endcode
 
 */

documentation/release_notes.dox

@@ -7,6 +7,7 @@ Release 7.1.0 (UNRELEASED)
 
 - Deprecations
  - pv/localStaticLock.h
+ - pv/pvCopy.h (see epics::pvData::PVRequestMapper)
 - Removals
  - Remove previously deprecated executor.h, queue.h and timerFunction.h
  - Remove *HashFunction functors to "hash" Field sub-classes which were never fully implemented.
@@ -14,14 +15,19 @@ Release 7.1.0 (UNRELEASED)
  - Make thread safe getFieldCreate() and getPVDataCreate()
  - Workaround for MSVC pickyness that iterators be non-NULL, even when not de-referenced.
  - Fix alignment fault during (de)serialization on RTEMS/vxWorks.
- - Fix shared_vector::swap() for void specialization.
- - Changes in several Field sub-classes to return const ref. instead of a copy.
+ - Fix epics::pvData::shared_vector::swap() for void specialization.
+ - Changes in several epics::pvData::Field sub-classes to return const ref. instead of a copy.
 - Additions
- - shared_vector add c++11 move and construct for initializer list.
- - Add AnyScalar::clear()
- - Add ctor AnyScalar(ScalarType, const void*) to allow construction from an untyped buffer.
- - Add Timer::close()
- - Allow castUnsafe() from const char* without first allocating a std::string.
+ - epics::pvData::shared_vector add c++11 move and construct for initializer list.
+ - Add epics::pvData::AnyScalar::clear()
+ - Add ctor epics::pvData::AnyScalar(ScalarType, const void*) to allow construction from an untyped buffer.
+ - Add epics::pvData::Timer::close()
+ - Allow epics::pvData::castUnsafe() from const char* without first allocating a std::string.
+ - De-duplication of epics::pvData::Field instances is performed using a global hash table.
+   Identical definitions will share a single instance.  Allows O(0) comparision.
+ - Add epics::pvData::PVRequestMapper to facilitate (partial) copying between PVStructure instances
+   modified by a pvRequest.
+ - Add shorthand notations epics::pvData::FieldBuilder::begin() and epics::pvData::Field::build()
 
 Release 7.0.0 (Dec 2017)
 ========================
@@ -42,6 +48,9 @@ Release 7.0.0 (Dec 2017)
   - Can also be constructed using an existing PVStructure to allow "editing".
  - Add debugPtr.h wrapper with reference tracking to assist in troubleshooting shared_ptr related ref. loops.
  - Add @ref pvjson utilities
+ - Add reftrack @ref pvd_reftrack
+ - Add header typemap.h to facilitate boilerplate switch() over ScalarType
+ - Add epics::auto_ptr typedef in help writing code supporting both c++98 and c++11 w/o copious deprecation warnings.
 
 
 Release 6.0.1

src/json/pv/json.h

@@ -52,6 +52,7 @@ struct epicsShareClass JSONPrintOptions
 /** Print PVStructure as JSON
  *
  * 'mask' selects those fields which will be printed.
+ * @version Overload added after 7.0.0
  */
 epicsShareFunc
 void printJSON(std::ostream& strm,
@@ -60,6 +61,7 @@ void printJSON(std::ostream& strm,
                const JSONPrintOptions& opts = JSONPrintOptions());
 
 /** Print PVField as JSON
+ * @version Overload added after 7.0.0
  */
 epicsShareFunc
 void printJSON(std::ostream& strm,
@@ -97,6 +99,7 @@ PVStructure::shared_pointer parseJSON(std::istream& strm);
  * @param dest Store in fields of this structure
  * @param assigned Which fields of _dest_ were assigned. (Optional)
  * @throws std::runtime_error on failure.  dest and assigned may be modified.
+ * @version Overload added after 7.0.0
  */
 epicsShareFunc
 void parseJSON(std::istream& strm,

src/misc/pv/anyscalar.h

@@ -117,6 +117,7 @@ public:
 
     //! Construct from un-typed pointer.
     //! Caller is responsible to ensure that buf actually points to the provided type
+    //! @version Added after 7.0.0
     AnyScalar(ScalarType type, const void *buf);
 
     AnyScalar(const AnyScalar& o);
@@ -147,7 +148,7 @@ public:
 #endif
 
     //! Reset internal state.
-    //! Added after 7.0.0
+    //! @version Added after 7.0.0
     //! @post empty()==true
     void clear();
 
@@ -174,6 +175,7 @@ public:
 
     //! Provide read-only access to underlying buffer.
     //! For a string this is std::string::c_str().
+    //! @version Added after 7.0.0
     const void* bufferUnsafe() const;
 
     /** Return typed reference to wrapped value.  Non-const reference allows value modification

src/misc/pv/bitSet.h

@@ -50,6 +50,8 @@ namespace epics { namespace pvData {
      * synchronization.
      *
      * Based on Java implementation.
+     *
+     * @since 7.0.0 Many methods return BitSet& to facilite method chaining.
      */
     class epicsShareClass BitSet : public Serializable {
     public:

src/misc/pv/reftrack.h

@@ -5,6 +5,38 @@
 #ifndef REFTRACK_H
 #define REFTRACK_H
 
+/** @page pvd_reftrack RefTrack
+ *
+ * reftrack.h is a utility for listing, finding, and reading global atomic counters.
+ * By convention used to expose object instance counters as a way of detecting (slow)
+ * reference/resource leaks before they cause problems.
+ *
+ * cf. the IOC shell commands "refshow", "refsave", and "refdiff".
+ *
+ * Example usage:
+ *
+ * @code
+ *   // my header.h
+ *   struct MyClass {
+ *      MyClass();
+ *      ~MyClass();
+ *      static size_t num_instances;
+ *      ...
+ *   };
+ *   ...
+ *   // my src.cpp
+ *   size_t MyClass::num_instances;
+ *   MyClass::MyClass() {
+ *      REFTRACE_INCREMENT(num_instances);
+ *   }
+ *   MyClass::~MyClass() {
+ *      REFTRACE_DECREMENT(num_instances);
+ *   }
+ *   // in some IOC registrar or global ctor
+ *   registerRefCounter("MyClass", &MyClass::num_instances);
+ * @endcode
+ */
+
 #ifdef __cplusplus
 
 #include <map>

src/misc/pv/sharedPtr.h

@@ -201,7 +201,8 @@ inline std::ostream& operator<<(std::ostream& strm, const ::detail::ref_shower<T
     typedef std::tr1::weak_ptr<clazz> weak_pointer; \
     typedef std::tr1::weak_ptr<const clazz> const_weak_pointer
 
-/* A semi-hack to help with migration from std::auto_ptr to std::unique_ptr,
+namespace epics{
+/** A semi-hack to help with migration from std::auto_ptr to std::unique_ptr,
  * and avoid copious deprecation warning spam
  * which may be hiding legitimate issues.
  *
@@ -214,7 +215,6 @@ inline std::ostream& operator<<(std::ostream& strm, const ::detail::ref_shower<T
  * copy/assignment/return are not supported
  * (use auto_ptr or unique_ptr explicitly).
  */
-namespace epics{
 #if __cplusplus>=201103L
 template<typename T>
 using auto_ptr = std::unique_ptr<T>;

src/pv/pvData.h

@@ -1659,9 +1659,3 @@ namespace std{
 }
 
 #endif  /* PVDATA_H */
-
-/** @page Overview Documentation
- *
- * <a href = "pvDataCPP.html">pvData.html</a>
- *
- */

src/pv/pvIntrospect.h

@@ -349,6 +349,7 @@ public:
     virtual std::ostream& dump(std::ostream& o) const = 0;
 
    //! Allocate a new instance
+   //! @version Added after 7.0.0
     std::tr1::shared_ptr<PVField> build() const;
 
 protected:
@@ -399,6 +400,7 @@ public:
     virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control) OVERRIDE FINAL;
 
     //! Allocate a new instance
+    //! @version Added after 7.0.0
     std::tr1::shared_ptr<PVScalar> build() const;
     
 protected:
@@ -507,6 +509,7 @@ public:
     virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control) OVERRIDE FINAL;
 
     //! Allocate a new instance
+    //! @version Added after 7.0.0
      std::tr1::shared_ptr<PVScalarArray> build() const;
     
     virtual ~ScalarArray();
@@ -611,6 +614,7 @@ public:
     virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control) OVERRIDE FINAL;
 
     //! Allocate a new instance
+    //! @version Added after 7.0.0
      std::tr1::shared_ptr<PVValueArray<std::tr1::shared_ptr<PVStructure> > > build() const;
 
 protected:
@@ -655,6 +659,7 @@ public:
     virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control) OVERRIDE FINAL;
 
     //! Allocate a new instance
+    //! @version Added after 7.0.0
      std::tr1::shared_ptr<PVValueArray<std::tr1::shared_ptr<PVUnion> > > build() const;
 
 protected:
@@ -766,6 +771,7 @@ public:
     virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control) OVERRIDE FINAL;
 
     //! Allocate a new instance
+    //! @version Added after 7.0.0
     std::tr1::shared_ptr<PVStructure> build() const;
 
 protected:
@@ -904,6 +910,7 @@ public:
     virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control) OVERRIDE FINAL;
 
     //! Allocate a new instance
+    //! @version Added after 7.0.0
     std::tr1::shared_ptr<PVUnion> build() const;
     
 protected:
@@ -939,6 +946,7 @@ class epicsShareClass FieldBuilder :
 {
 public:
     //! Create a new instance of in-line @c Field builder.
+    //! @version Added after 7.0.0
     static FieldBuilderPtr begin();
     //! Create a new instance of in-line @c Field builder pre-initialized with and existing Structure
     static FieldBuilderPtr begin(StructureConstPtr S);