From f54602deadb6217b29a32115df98bb823ab4d06d Mon Sep 17 00:00:00 2001 From: Michael Davidsaver Date: Thu, 18 Oct 2018 16:43:40 -0700 Subject: [PATCH] update doc --- documentation/mainpage.dox | 21 ++++++++++----------- documentation/release_notes.dox | 23 ++++++++++++++++------- src/json/pv/json.h | 3 +++ src/misc/pv/anyscalar.h | 4 +++- src/misc/pv/bitSet.h | 2 ++ src/misc/pv/reftrack.h | 32 ++++++++++++++++++++++++++++++++ src/misc/pv/sharedPtr.h | 4 ++-- src/pv/pvData.h | 6 ------ src/pv/pvIntrospect.h | 8 ++++++++ 9 files changed, 76 insertions(+), 27 deletions(-) diff --git a/documentation/mainpage.dox b/documentation/mainpage.dox index 2d60153..cd06260 100644 --- a/documentation/mainpage.dox +++ b/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 -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 -value = epics::pvData::getPVDataCreate()->createPVStructure(stype); +pvd::PVStructuretPtr value(stype->build()); -value->getSubField("fld1")->put(4); // store integer 4 -value->getSubField("sub.fld2")->putFrom(4.2); // convert and store string "4.2" +value->getSubFieldT("fld1")->put(4); // store integer 4. would throw if not pvInt +value->getSubFieldT("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(4.2); +value.fld2 = pvd::castUnsafe(4.2); @endcode */ diff --git a/documentation/release_notes.dox b/documentation/release_notes.dox index b1f35f8..71ba1f6 100644 --- a/documentation/release_notes.dox +++ b/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 diff --git a/src/json/pv/json.h b/src/json/pv/json.h index eb500ca..66d09c5 100644 --- a/src/json/pv/json.h +++ b/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, diff --git a/src/misc/pv/anyscalar.h b/src/misc/pv/anyscalar.h index d9637d5..0410b24 100644 --- a/src/misc/pv/anyscalar.h +++ b/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 diff --git a/src/misc/pv/bitSet.h b/src/misc/pv/bitSet.h index aac6ea9..4b59bb6 100644 --- a/src/misc/pv/bitSet.h +++ b/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: diff --git a/src/misc/pv/reftrack.h b/src/misc/pv/reftrack.h index 9257354..f5dc558 100644 --- a/src/misc/pv/reftrack.h +++ b/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 diff --git a/src/misc/pv/sharedPtr.h b/src/misc/pv/sharedPtr.h index d6d1378..8f3a513 100644 --- a/src/misc/pv/sharedPtr.h +++ b/src/misc/pv/sharedPtr.h @@ -201,7 +201,8 @@ inline std::ostream& operator<<(std::ostream& strm, const ::detail::ref_shower weak_pointer; \ typedef std::tr1::weak_ptr 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=201103L template using auto_ptr = std::unique_ptr; diff --git a/src/pv/pvData.h b/src/pv/pvData.h index ccfb6b4..6f9dfba 100644 --- a/src/pv/pvData.h +++ b/src/pv/pvData.h @@ -1659,9 +1659,3 @@ namespace std{ } #endif /* PVDATA_H */ - -/** @page Overview Documentation - * - * pvData.html - * - */ diff --git a/src/pv/pvIntrospect.h b/src/pv/pvIntrospect.h index 8e177b4..9ce2302 100644 --- a/src/pv/pvIntrospect.h +++ b/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 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 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 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 > > 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 > > 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 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 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);