diff --git a/src/nt/ntaggregate.h b/src/nt/ntaggregate.h index 8ff4e0d..88f47e7 100644 --- a/src/nt/ntaggregate.h +++ b/src/nt/ntaggregate.h @@ -42,89 +42,90 @@ namespace detail { POINTER_DEFINITIONS(NTAggregateBuilder); /** - * Add dispersion field to the NTAggregate. + * Adds dispersion field to the NTAggregate. * @return this instance of NTAggregateBuilder. */ shared_pointer addDispersion(); /** - * Add first field to the NTAggregate. + * Adds first field to the NTAggregate. * @return this instance of NTAggregateBuilder. */ shared_pointer addFirst(); /** - * Add firstTimeStamp field to the NTAggregate. + * Adds firstTimeStamp field to the NTAggregate. * @return this instance of NTAggregateBuilder. */ shared_pointer addFirstTimeStamp(); /** - * Add last field to the NTAggregate. + * Adds last field to the NTAggregate. * @return this instance of NTAggregateBuilder. */ shared_pointer addLast(); /** - * Add lastTimeStamp field to the NTAggregate. + * Adds lastTimeStamp field to the NTAggregate. * @return this instance of NTAggregateBuilder. */ shared_pointer addLastTimeStamp(); /** - * Add max field to the NTAggregate. + * Adds max field to the NTAggregate. * @return this instance of NTAggregateBuilder. */ shared_pointer addMax(); /** - * Add min field to the NTAggregate. + * Adds min field to the NTAggregate. * @return this instance of NTAggregateBuilder. */ shared_pointer addMin(); /** - * Add descriptor field to the NTAggregate. + * Adds descriptor field to the NTAggregate. * @return this instance of NTAggregateBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTAggregate. + * Adds alarm field to the NTAggregate. * @return this instance of NTAggregateBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTAggregate. + * Adds timeStamp field to the NTAggregate. * @return this instance of NTAggregateBuilder. */ shared_pointer addTimeStamp(); /** - * Create a Structure that represents NTAggregate. + * Creates a Structure that represents NTAggregate. * This resets this instance state and allows new instance to be created. * @return a new instance of a Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTAggregate. + * Creates a PVStructure that represents NTAggregate. * This resets this instance state and allows new instance to be created. * @return a new instance of a PVStructure. */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTAggregate instance. + * Creates a NTAggregate instance. * This resets this instance state and allows new instance to be created. * @return a new instance of a NTAggregate. */ NTAggregatePtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTAggregateBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -171,65 +172,92 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTAggregate. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTAggregate. - * @return NTAggregate instance on success, nullptr otherwise. + * Creates an NTAggregate wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTAggregate + * and if so returns an NTAggregate which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return the NTAggregate instance on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTAggregate without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTAggregate. - * @return NTAggregate instance. + * Creates an NTAggregate wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTAggregate or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return the NTAggregate instance */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTAggregate. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTAggregate. + * Returns whether the specified Structure reports to be a compatible NTAggregate. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTAggregate through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTAggregate */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTAggregate. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTAggregate. + * Returns whether the specified PVStructure reports to be a compatible NTAggregate. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTAggregate through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test. + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTAggregate. */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTAggregate. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTAggregate. + * Returns whether the specified Structure is compatible with NTAggregate. + *

+ * Checks if the specified Structure is compatible with this version + * of NTAggregate through introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTAggregate */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTAggregate. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTAggregate. + * Returns whether the specified PVStructure is compatible with NTAggregate. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTAggregate through introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTAggregate */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTAggregate. + * Returns whether the wrapped PVStructure is valid with respect to this + * version of NTAggregate. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value data as + * well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTAggregate - * @return (false,true) if (is not, is) a valid NTAggregate. + * @return (false,true) if wrapped PVStructure a valid NTAggregate */ bool isValid(); /** - * Create a NTAggregate builder instance. + * Creates an NTAggregate builder instance. * @return builder instance. */ static NTAggregateBuilderPtr createBuilder(); @@ -240,96 +268,96 @@ public: ~NTAggregate() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no such field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no such field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no such field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the value field. - * @return The PVDouble for the value. + * Returns the value field. + * @return the value field. */ epics::pvData::PVDoublePtr getValue() const; /** - * Get the N field. - * @return The PVLong for the N field. + * Returns the N field. + * @return the N field. */ epics::pvData::PVLongPtr getN() const; /** - * Get the dispersion field. - * @return The PVDouble for the dispersion which may be null + * Returns the dispersion field. + * @return the dispersion or null if no such field. */ epics::pvData::PVDoublePtr getDispersion() const; /** - * Get the first field. - * @return The PVDouble for the first field which may be null + * Returns the first field. + * @return the first field or null if no such field. */ epics::pvData::PVDoublePtr getFirst() const; /** - * Get the firstTimeStamp field. - * @return PVStructurePtr which may be null. + * Returns the firstTimeStamp field. + * @return the firstTimeStamp field or null if no such field. */ epics::pvData::PVStructurePtr getFirstTimeStamp() const; /** - * Get the last field. - * @return The PVDouble for the last field which may be null + * Returns the last field. + * @return the last field or null if no such field. */ epics::pvData::PVDoublePtr getLast() const; /** - * Get the lastTimeStamp field. - * @return PVStructurePtr which may be null. + * Returns the lastTimeStamp field. + * @return the lastTimeStamp field or null if no such field. */ epics::pvData::PVStructurePtr getLastTimeStamp() const; /** - * Get the max field. - * @return The PVDouble for the max field which may be null + * Returns the max field. + * @return the max field or null if no such field. */ epics::pvData::PVDoublePtr getMax() const; /** - * Get the min field. - * @return The PVDouble for the max field which may be null + * Returns the min field. + * @return the min field or null if no such field. */ epics::pvData::PVDoublePtr getMin() const; diff --git a/src/nt/ntattribute.h b/src/nt/ntattribute.h index 9f1cc35..b9a293d 100644 --- a/src/nt/ntattribute.h +++ b/src/nt/ntattribute.h @@ -42,53 +42,54 @@ namespace detail { POINTER_DEFINITIONS(NTAttributeBuilder); /** - * Add tags field to the NTAttribute. + * Adds tags field to the NTAttribute. * @return this instance of NTAttributeBuilder. */ virtual shared_pointer addTags(); /** - * Add descriptor field to the NTAttribute. + * Adds descriptor field to the NTAttribute. * @return this instance of NTAttributeBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTAttribute. + * Adds alarm field to the NTAttribute. * @return this instance of NTAttributeBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTAttribute. + * Adds timeStamp field to the NTAttribute. * @return this instance of NTAttributeBuilder. */ shared_pointer addTimeStamp(); /** - * Create a Structure that represents NTAttribute. + * Creates a Structure that represents NTAttribute. * This resets this instance state and allows new instance to be created. * @return a new instance of a Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTAttribute. + * Creates a PVStructure that represents NTAttribute. * This resets this instance state and allows new instance to be created. * @return a new instance of a PVStructure. */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTAttribute instance. + * Creates a NTAttribute instance. * This resets this instance state and allows new instance to be created. * @return a new instance of a NTAttribute. */ NTAttributePtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTAttributeBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -129,65 +130,92 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTAttribute. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTAttribute. - * @return NTAttribute instance on success, nullptr otherwise. + * Creates an NTAttribute wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTAttribute + * and if so returns an NTAttribute which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTAttribute instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTAttribute without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTAttribute. - * @return NTAttribute instance. + * Creates an NTAttribute wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTAttribute or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTAttribute instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTAttribute. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTAttribute. + * Returns whether the specified Structure reports to be a compatible NTAttribute. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTAttribute through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTAttribute */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTAttribute. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTAttribute. + * Returns whether the specified PVStructure reports to be a compatible NTAttribute. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTAttribute through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTAttribute */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTAttribute. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTAttribute. + * Returns whether the specified Structure is compatible with NTAttribute. + *

+ * Checks if the specified Structure is compatible with this version + * of NTAttribute through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTAttribute */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTAttribute. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTAttribute. + * Returns whether the specified PVStructure is compatible with NTAttribute. + *

+ * Checks if the specified tructure is compatible with this version + * of NTAttribute through the introspection interface. + + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTAttribute */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTAttribute. + * Returns whether the wrapped PVStructure is valid with respect to this + * version of NTAttribute. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTAttribute - * @return (false,true) if (is not, is) a valid NTAttribute. + * @return (false,true) if the wrapped PVStructure (is not, is) a valid NTAttribute */ bool isValid(); /** - * Create a NTAttribute builder instance. + * Creates an NTAttribute builder instance. * @return builder instance. */ static NTAttributeBuilderPtr createBuilder(); @@ -198,60 +226,60 @@ public: ~NTAttribute() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no such field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no such field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no such field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the name field. - * @return The PVString for the name. + * Returns the name field. + * @return the name field. */ epics::pvData::PVStringPtr getName() const; /** - * Get the value field. - * @return The PVUnion for the values. + * Returns the value field. + * @return the value field. */ epics::pvData::PVUnionPtr getValue() const; /** - * Get the tags field. - * @return The PVStringArray for the tags, which may be null. + * Returns the tags field. + * @return the tags field or null if no such field. */ epics::pvData::PVStringArrayPtr getTags() const; diff --git a/src/nt/ntcontinuum.h b/src/nt/ntcontinuum.h index e1dced1..88e6313 100644 --- a/src/nt/ntcontinuum.h +++ b/src/nt/ntcontinuum.h @@ -43,47 +43,48 @@ namespace detail { POINTER_DEFINITIONS(NTContinuumBuilder); /** - * Add descriptor field to the NTContinuum. + * Adds descriptor field to the NTContinuum. * @return this instance of NTContinuumBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTContinuum. + * Adds alarm field to the NTContinuum. * @return this instance of NTContinuumBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTContinuum. + * Adds timeStamp field to the NTContinuum. * @return this instance of NTContinuumBuilder. */ shared_pointer addTimeStamp(); /** - * Create a Structure that represents NTContinuum. + * Creates a Structure that represents NTContinuum. * This resets this instance state and allows new instance to be created. * @return a new instance of Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTContinuum. + * Creates a PVStructure that represents NTContinuum. * This resets this instance state and allows new instance to be created. * @return a new instance of PVStructure. */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTContinuum instance. + * Creates a NTContinuum instance. * This resets this instance state and allows new instance to be created. * @return a new instance of NTContinuum. */ NTContinuumPtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTContinuumBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -124,65 +125,92 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTContinuum. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTContinuum. - * @return NTContinuum instance on success, nullptr otherwise. + * Creates an NTContinuum wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied structure is compatible with NTContinuum + * and if so returns an NTContinuum which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTContinuum instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTContinuum without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTContinuum. - * @return NTContinuum instance. + * Creates an NTContinuum wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTContinuum or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTContinuum instance wrapping pvStructure. */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTContinuum. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTContinuum. + * Returns whether the specified Structure reports to be a compatible NTContinuum. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTContinuum through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTContinuum */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTContinuum. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTContinuum. + * Returns whether the specified PVStructure reports to be a compatible NTContinuum. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTContinuum through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type + * + * @param pvStructure The PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTContinuum */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTContinuum. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTContinuum. + * Returns whether the specified Structure is compatible with NTContinuum. + *

+ * Checks if the specified Structure is compatible with this version + * of NTContinuum through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTContinuum */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTContinuum. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTContinuum. + * Returns whether the specified PVStructure is compatible with NTContinuum. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTContinuum through the introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTContinuum */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTContinuum. + * Returns whether the wrapped structure is valid with respect to this + * version of NTContinuum. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTContinuum - * @return (false,true) if (is not, is) a valid NTContinuum. + * @return (false,true) if the wrapped PVStructure (is not, is) a valid NTContinuum */ bool isValid(); /** - * Create a NTContinuum builder instance. + * Creates an NTContinuum builder instance. * @return builder instance. */ static NTContinuumBuilderPtr createBuilder(); @@ -193,60 +221,60 @@ public: ~NTContinuum() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no such field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no such field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no such field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the base field. - * @return The PVDoubleArray for the base. + * Returns the base field. + * @return the base field. */ epics::pvData::PVDoubleArrayPtr getBase() const; /** - * Get the value field. - * @return The PVDoubleArray for the values. + * Returns the value field. + * @return the value field. */ epics::pvData::PVDoubleArrayPtr getValue() const; /** - * Get the units field. - * @return The PVStringArray for the units. + * Returns the units field. + * @return the units field. */ epics::pvData::PVStringArrayPtr getUnits() const; diff --git a/src/nt/ntenum.h b/src/nt/ntenum.h index f3fad60..960c55f 100644 --- a/src/nt/ntenum.h +++ b/src/nt/ntenum.h @@ -42,47 +42,48 @@ namespace detail { POINTER_DEFINITIONS(NTEnumBuilder); /** - * Add descriptor field to the NTEnum. + * Adds descriptor field to the NTEnum. * @return this instance of NTEnumBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTEnum. + * Adds alarm field to the NTEnum. * @return this instance of NTEnumBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTEnum. + * Adds timeStamp field to the NTEnum. * @return this instance of NTEnumBuilder. */ shared_pointer addTimeStamp(); /** - * Create a Structure that represents NTEnum. + * Creates a Structure that represents NTEnum. * This resets this instance state and allows new instance to be created. * @return a new instance of a Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTEnum. + * Creates a PVStructure that represents NTEnum. * This resets this instance state and allows new instance to be created. * @return a new instance of a PVStructure. */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTEnum instance. + * Creates a NTEnum instance. * This resets this instance state and allows new instance to be created. * @return a new instance of a NTEnum. */ NTEnumPtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTEnumBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -122,65 +123,90 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTEnum. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTEnum. - * @return NTEnum instance on success, nullptr otherwise. + * Creates an NTEnum wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTEnum or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTEnum instance wrapping pvStructure */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTEnum without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTEnum. - * @return NTEnum instance. + * Creates an NTEnum wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTEnum or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTEnum instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTEnum. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTEnum. + * Returns whether the specified Structure reports to be a compatible NTEnum. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTEnum through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test. + * @return (false,true) if the specified Structure (is not, is) a compatible NTEnum. */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTEnum. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTEnum. + * Returns whether the specified PVStructure reports to be a compatible NTEnum. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTEnum through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTEnum */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTEnum. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTEnum. + * Returns whether the specified Structure is compatible with NTEnum. + *

+ * Checks if the specified Structure is compatible with this version + * of NTEnum through the introspection interface. + * + * @param structure The Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTEnum */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTEnum. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTEnum. + * Returns whether the specified PVStructure is compatible with NTEnum. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTEnum through the introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTEnum */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTEnum. + * Returns whether the wrapped PVStructure is valid with respect to this + * version of NTEnum. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTEnum - * @return (false,true) if (is not, is) a valid NTEnum. + * @return (false,true) if the wrapped PVStructure (is not, is) a valid NTEnum */ bool isValid(); /** - * Create a NTEnum builder instance. + * Creates an NTEnum builder instance. * @return builder instance. */ static NTEnumBuilderPtr createBuilder(); @@ -191,48 +217,48 @@ public: ~NTEnum() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no such field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or or null if no such field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or or null if no such field. */ epics::pvData::PVStructurePtr getAlarm() const; /** * Get the value field. - * @return The PVStructure for the values. + * @return the value field. */ epics::pvData::PVStructurePtr getValue() const; diff --git a/src/nt/ntfield.h b/src/nt/ntfield.h index 644130f..d2a56f2 100644 --- a/src/nt/ntfield.h +++ b/src/nt/ntfield.h @@ -47,7 +47,7 @@ class epicsShareClass NTField { public: POINTER_DEFINITIONS(NTField); /** - * get the single implementation of this class. + * Gets the single implementation of this class. * @return the implementation */ static NTFieldPtr get(); @@ -55,84 +55,97 @@ public: * destructor */ ~NTField() {} + /** * Is field an enumerated structure. - * @param field The field to test. + * @param field the field to test. * @return (false,true) if field (is not,is) an enumerated structure. */ bool isEnumerated(epics::pvData::FieldConstPtr const & field); + /** * Is field a timeStamp structure. - * @param field The field to test. + * @param field the field to test. * @return (false,true) if field (is not,is) a timeStamp structure. */ bool isTimeStamp(epics::pvData::FieldConstPtr const & field); + /** * Is field an alarm structure. - * @param field The field to test. + * @param field the field to test. * @return (false,true) if field (is not,is) an alarm structure. */ bool isAlarm(epics::pvData::FieldConstPtr const & field); + /** * Is field a display structure. - * @param field The field to test. + * @param field the field to test. * @return (false,true) if field (is not,is) a display structure. */ bool isDisplay(epics::pvData::FieldConstPtr const & field); + /** * Is field an alarmLimit structure. - * @param field The field to test. + * @param field the field to test. * @return (false,true) if field (is not,is) an alarmLimit structure. */ bool isAlarmLimit(epics::pvData::FieldConstPtr const & field); + /** * Is field a control structure. - * @param field The field to test. + * @param field the field to test. * @return (false,true) if field (is not,is) a control structure. */ bool isControl(epics::pvData::FieldConstPtr const & field); /** - * Create an enumerated structure. + * Creates an enumerated structure. * @return an enumerated structure. */ epics::pvData::StructureConstPtr createEnumerated(); + /** - * Create a timeStamp structure. + * Creates a timeStamp structure. * @return a timeStamp structure. */ epics::pvData::StructureConstPtr createTimeStamp(); + /** - * Create an alarm structure. + * Creates an alarm structure. * @return an alarm structure. */ epics::pvData::StructureConstPtr createAlarm(); + /** - * Create a display structure. + * Creates a display structure. * @return a displayalarm structure. */ epics::pvData::StructureConstPtr createDisplay(); + /** - * Create a control structure. + * Creates a control structure. * @return a control structure. */ epics::pvData::StructureConstPtr createControl(); /** - * Create an array of enumerated structures. + * Creates an array of enumerated structures. * @return an array of enumerated structures. */ epics::pvData::StructureArrayConstPtr createEnumeratedArray(); + /** - * Create an array of timeStamp structures. + * Creates an array of timeStamp structures. * @return an array of timeStamp structures. */ epics::pvData::StructureArrayConstPtr createTimeStampArray(); + /** - * Create an array of alarm structures. + * Creates an array of alarm structures. * @return an array of alarm structures. */ epics::pvData::StructureArrayConstPtr createAlarmArray(); + private: NTField(); epics::pvData::FieldCreatePtr fieldCreate; @@ -149,62 +162,72 @@ class epicsShareClass PVNTField { public: POINTER_DEFINITIONS(PVNTField); /** - * get the single implementation of this class. + * Returns the single implementation of this class. * @return the implementation */ static PVNTFieldPtr get(); + /** * destructor */ ~PVNTField() {} + /** - * Create an enumerated PVStructure. + * Creates an enumerated PVStructure. * @param choices The array of choices. - * @return an enumerated PVStructure.. + * @return an enumerated PVStructure. */ epics::pvData::PVStructurePtr createEnumerated( epics::pvData::StringArray const & choices); + /** - * Create a timeStamp PVStructure. - * @return a timeStamp PVStructure.. + * Creates a timeStamp PVStructure. + * @return a timeStamp PVStructure. */ epics::pvData::PVStructurePtr createTimeStamp(); + /** - * Create an alarm PVStructure. - * @return an alarm PVStructure.. + * Creates an alarm PVStructure. + * @return an alarm PVStructure. */ epics::pvData::PVStructurePtr createAlarm(); + /** - * Create a display PVStructure. - * @return a display PVStructure.. + * Creates a display PVStructure. + * @return a display PVStructure. */ epics::pvData::PVStructurePtr createDisplay(); + /** - * Create an alarmLimit PVStructure. - * @return an alarmLimit PVStructure.. + * Creates an alarmLimit PVStructure. + * @return an alarmLimit PVStructure. */ epics::pvData::PVStructurePtr createAlarmLimit(); + /** - * Create a control PVStructure. - * @return a control PVStructure.. + * Creates a control PVStructure. + * @return a control PVStructure. */ epics::pvData::PVStructurePtr createControl(); /** - * Create an enumerated PVStructureArray. - * @return an enumerated PVStructureArray.. + * Creates an enumerated PVStructureArray. + * @return an enumerated PVStructureArray. */ epics::pvData::PVStructureArrayPtr createEnumeratedArray(); + /** - * Create a timeStamp PVStructureArray. - * @return a timeStamp PVStructureArray + * Creates a timeStamp PVStructureArray. + * @return a timeStamp PVStructureArray. */ epics::pvData::PVStructureArrayPtr createTimeStampArray(); + /** - * Create an alarm PVStructureArray. - * @return an alarm PVStructureArray.. + * Creates an alarm PVStructureArray. + * @return an alarm PVStructureArray. */ epics::pvData::PVStructureArrayPtr createAlarmArray(); + private: PVNTField(); epics::pvData::PVDataCreatePtr pvDataCreate; diff --git a/src/nt/nthistogram.h b/src/nt/nthistogram.h index 87ab65e..18e496d 100644 --- a/src/nt/nthistogram.h +++ b/src/nt/nthistogram.h @@ -43,54 +43,55 @@ namespace detail { POINTER_DEFINITIONS(NTHistogramBuilder); /** - * Set a scalar type of value field array. - * @param scalarType the value type. + * Sets the scalar type of the value field array. + * @param scalarType the scalar type of the value field array. * @return this instance of NTHistogramBuilder. */ shared_pointer value(epics::pvData::ScalarType scalarType); /** - * Add descriptor field to the NTHistogram. + * Adds descriptor field to the NTHistogram. * @return this instance of NTHistogramBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTHistogram. + * Adds alarm field to the NTHistogram. * @return this instance of NTHistogramBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTHistogram. + * Adds timeStamp field to the NTHistogram. * @return this instance of NTHistogramBuilder. */ shared_pointer addTimeStamp(); /** - * Create a Structure that represents NTHistogram. + * Creates a Structure that represents NTHistogram. * This resets this instance state and allows new instance to be created. * @return a new instance of Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTHistogram. + * Creates a PVStructure that represents NTHistogram. * This resets this instance state and allows new instance to be created. * @return a new instance of PVStructure. */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTHistogram instance. + * Creates a NTHistogram instance. * This resets this instance state and allows new instance to be created. * @return a new instance of NTHistogram. */ NTHistogramPtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTHistogramBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -134,65 +135,92 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTHistogram. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTHistogram. - * @return NTHistogram instance on success, nullptr otherwise. + * Creates an NTHistogram wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTHistogram + * and if so returns an NTHistogram which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTHistogram instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTHistogram without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTHistogram. - * @return NTHistogram instance. + * Creates an NTHistogram wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTHistogram or is non-null. + * + * @param pvStructure the PVStructure to be wrapped. + * @return NTHistogram instance wrapping pvStructure. */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTHistogram. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTHistogram. + * Returns whether the specified Structure reports to be a compatible NTHistogram. + *

+ * Checks whether the specified Structure reports compatibility with this + * version of NTHistogram through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test. + * @return (false,true) if the specified Structure (is not, is) a compatible NTHistogram */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTHistogram. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTHistogram. + * Returns whether the specified PVStructure reports to be a compatible NTHistogram. + *

+ * Checks whether the specified PVStructure reports compatibility with this + * version of NTHistogram through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTHistogram */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTHistogram. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTHistogram. + * Returns whether the specified Structure is compatible with NTHistogram. + *

+ * Checks whether the specified Structure is compatible with this version + * of NTHistogram through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTHistogram */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTHistogram. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTHistogram. + * Returns whether the specified PVStructure is compatible with NTHistogram. + *

+ * Checks whether the specified PVStructure is compatible with this version + * of NTHistogram through the introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTHistogram */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTHistogram. + * Returns whether the wrapped structure is valid with respect to this + * version of NTHistogram. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTHistogram - * @return (false,true) if (is not, is) a valid NTHistogram. + * @return (false,true) if the wrapped PVStructure (is not, is) a valid NTHistogram */ bool isValid(); /** - * Create a NTHistogram builder instance. + * Creates an NTHistogram builder instance. * @return builder instance. */ static NTHistogramBuilderPtr createBuilder(); @@ -203,60 +231,62 @@ public: ~NTHistogram() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Get the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no such field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no such field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no such field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the base field. - * @return The PVDoubleArray for the base. + * Get the ranges field. + * @return the ranges field. */ epics::pvData::PVDoubleArrayPtr getRanges() const; /** * Get the value field. - * @return The PVScalarArray for the values. + * @return the value field. */ epics::pvData::PVScalarArrayPtr getValue() const; /** * Get the value field of a specified type (e.g. PVIntArray). - * @return The field for the values. + * @tparam PVT the expected type of the value field which should be + * be PVShortArray, PVIntArray pr PVLongArray. + * @return the value field or null if it is not of the expected type.. */ template std::tr1::shared_ptr getValue() const diff --git a/src/nt/ntid.h b/src/nt/ntid.h index 842ce5c..599acee 100644 --- a/src/nt/ntid.h +++ b/src/nt/ntid.h @@ -13,104 +13,110 @@ namespace epics { namespace nt { /** - * Utility class for parsing an ID following the NT type ID conventions + * @brief Utility class for parsing a type ID that follows the NT type ID conventions * - * An NT type ID will be of the from epics:nt/:., - * e.g. epics:nt/NTNDArray:1.2 + * An NT type ID will be of the from +@code + epics:nt/:. +@endcode + * e.g. +@code + epics:nt/NTNDArray:1.2 +@endcode * @author dgh */ class NTID { public: /** - * Creates an NTID from the specified type ID + * Creates an NTID from the specified type ID. * - * @param id The the id to be parsed. + * @param id the the ID to be parsed. * @return NTNDArray instance on success, null otherwise. */ NTID(const std::string &id); /** - * Get the full name of the id, i.e. the original ID - * - * For example above returns "epics:nt/NTNDArray:1.2" + * Returns the full name of the id, i.e. the original ID + *

+ * For example above returns "epics:nt/NTNDArray:1.2". * @return the full name */ std::string getFullName(); /** - * Get the fully qualified name including namespaces, but excluding version numbers - * + * Returns the fully qualified name including namespaces, but excluding version numbers. + *

* For example above return "epics:nt/NTNDArray" * @return the fully qualified name */ std::string getQualifiedName(); /** - * Get the namespace - * - * For example above return "epics:nt" + * Returns the namespace + *

+ * For example above return "epics:nt". * @return the namespace */ std::string getNamespace(); /** - * Get the unqualified name, without namespace or version - * - * For example above return "NTNDArray" + * Returns the unqualified name, without namespace or version. + *

+ * For example above return "NTNDArray". * @return the unqualified name */ std::string getName(); /** - * Get the unqualified name, without namespace or version - * - * For example above return "NTNDArray" - * @return the unqualified name + * Returns the version as a string. + *

+ * For example above return "NTNDArray". + * @return the the version string */ std::string getVersion(); /** - * Get the Major version as a string - * - * For example above return "1" + * Returns the Major version as a string. + *

+ * For example above return "1". * @return the Major string */ std::string getMajorVersionString(); /** - * Does the ID contain a major version and is it a number - * + * Does the ID contain a major version and is it a number. + *

* @return true if it contains a major version number */ bool hasMajorVersion(); /** - * Get the Major version as an integer - * - * For example above return 1 + * Returns the Major version as an integer. + *

+ * For example above return 1. * @return the Major string */ int getMajorVersion(); /** - * Get the Major version as a string - * - * For example above return "1" + * Returns the Major version as a string. + *

+ * For example above return "1". * @return the Major string */ std::string getMinorVersionString(); /** - * Does the ID contain a minor version and is it a number - * + * Does the ID contain a minor version and is it a number. + *

* @return true if it contains a minor version number */ bool hasMinorVersion(); /** - * Get the Minor version as an integer - * - * For example above return 1 + * Returns the Minor version as an integer. + *

+ * For example above return 1. * @return the Minor string */ int getMinorVersion(); diff --git a/src/nt/ntmatrix.h b/src/nt/ntmatrix.h index c6c12c9..3991f2b 100644 --- a/src/nt/ntmatrix.h +++ b/src/nt/ntmatrix.h @@ -45,59 +45,60 @@ namespace detail { POINTER_DEFINITIONS(NTMatrixBuilder); /** - * Add dimensionfield to the NTMatrix. + * Adds dimension field to the NTMatrix. * @return this instance of NTMatrixBuilder. */ shared_pointer addDim(); /** - * Add descriptor field to the NTMatrix. + * Adds descriptor field to the NTMatrix. * @return this instance of NTMatrixBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTMatrix. + * Adds alarm field to the NTMatrix. * @return this instance of NTMatrixBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTMatrix. + * Adds timeStamp field to the NTMatrix. * @return this instance of NTMatrixBuilder. */ shared_pointer addTimeStamp(); /** - * Add display structure to the NTMatrix. + * Adds display field to the NTMatrix. * @return this instance of NTMatrixBuilder. */ shared_pointer addDisplay(); /** - * Create a Structure that represents NTMatrix. + * Creates a Structure that represents NTMatrix. * This resets this instance state and allows new instance to be created. * @return a new instance of Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTMatrix. + * Creates a PVStructure that represents NTMatrix. * This resets this instance state and allows new instance to be created. * @return a new instance of PVStructure. */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTMatrix instance. + * Creates a NTMatrix instance. * This resets this instance state and allows new instance to be created. * @return a new instance of NTMatrix. */ NTMatrixPtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTMatrixBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -139,65 +140,92 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTMatrix. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTMatrix. - * @return NTMatrix instance on success, nullptr otherwise. + * Creates an NTMatrix wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTMatrix + * and if so returns an NTMatrix which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTMatrix instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTMatrix without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTMatrix. - * @return NTMatrix instance. + * Creates an NTMatrix wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTMatrix or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTMatrix instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTMatrix. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTMatrix. + * Returns whether the specified Structure reports to be a compatible NTMatrix. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTMatrix through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTMatrix */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTMatrix. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTMatrix. + * Returns whether the specified PVStructure reports to be a compatible NTMatrix. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTMatrix through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTMatrix */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTMatrix. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTMatrix. + * Returns whether the specified Structure is compatible with NTMatrix. + *

+ * Checks if the specified Structure is compatible with this version + * of NTMatrix through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTMatrix */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTMatrix. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTMatrix. + * Returns whether the specified PVStructure is compatible with NTMatrix. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTMatrix through the introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTMatrix */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTMatrix. + * Returns whether the wrapped PVStructure is valid with respect to this + * version of NTMatrix. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTMatrix - * @return (false,true) if (is not, is) a valid NTMatrix. + * @return (false,true) if the wrapped PVStructure (is not, is) a valid NTMatrix */ bool isValid(); /** - * Create a NTMatrix builder instance. + * Creates an NTMatrix builder instance. * @return builder instance. */ static NTMatrixBuilderPtr createBuilder(); @@ -208,68 +236,68 @@ public: ~NTMatrix() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Attach an pvDisplay. - * @param pvDisplay The pvDisplay that will be attached. + * Attaches a PVDisplay to the wrapped PVStructure. * Does nothing if no display. - * @return true if the operation was successfull (i.e. this instance has a display field), otherwise false. + * @param pvDisplay the PVDisplay that will be attached. + * @return true if the operation was successfull (i.e. this instance has a display field), otherwise false. */ bool attachDisplay(epics::pvData::PVDisplay &pvDisplay) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Get the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no such field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no such field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no such field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the display. - * @return PVStructurePtr which may be null. + * Returns the display field. + * @return the display field or null if no such field. */ epics::pvData::PVStructurePtr getDisplay() const; /** * Get the value field. - * @return The PVDoubleArray for the values. + * @return the value field. */ epics::pvData::PVDoubleArrayPtr getValue() const; /** * Get the dim field. - * @return The PVIntArray for the dim which may be null. + * @return the dim field or or null if no such field. */ epics::pvData::PVIntArrayPtr getDim() const; diff --git a/src/nt/ntmultiChannel.h b/src/nt/ntmultiChannel.h index a7a8dbc..7d0d540 100644 --- a/src/nt/ntmultiChannel.h +++ b/src/nt/ntmultiChannel.h @@ -54,81 +54,96 @@ namespace detail { * @return this instance of NTMultiChannelBuilder. */ shared_pointer value(epics::pvData::UnionConstPtr valuePtr); + /** - * Add descriptor field to the NTMultiChannel. + * Adds descriptor field to the NTMultiChannel. * @return this instance of NTMultiChannelBuilder. */ shared_pointer addDescriptor(); + /** - * Add alarm structure to the NTMultiChannel. + * Adds alarm field to the NTMultiChannel. * @return this instance of NTMultiChannelBuilder. */ shared_pointer addAlarm(); + /** - * Add timeStamp structure to the NTMultiChannel. + * Adds timeStamp field to the NTMultiChannel. * @return this instance of NTMultiChannelBuilder. */ shared_pointer addTimeStamp(); + /** - * Add severity array to the NTMultiChannel. + * Adds severity array to the NTMultiChannel. * @return this instance of NTMultiChannelBuilder. */ shared_pointer addSeverity(); + /** - * Add status array to the NTMultiChannel. + * Adds status array to the NTMultiChannel. * @return this instance of NTMultiChannelBuilder. */ shared_pointer addStatus(); + /** - * Add message array to the NTMultiChannel. + * Adds message array to the NTMultiChannel. * @return this instance of NTMultiChannelBuilder. */ shared_pointer addMessage(); + /** - * Add secondsPastEpoch array to the NTMultiChannel. + * Adds secondsPastEpoch array to the NTMultiChannel. * @return this instance of NTMultiChannelBuilder. */ shared_pointer addSecondsPastEpoch(); + /** - * Add nanoseconds array to the NTMultiChannel. + * Adds nanoseconds array to the NTMultiChannel. * @return this instance of NTMultiChannelBuilder. */ shared_pointer addNanoseconds(); + /** - * Add userTag array to the NTMultiChannel. + * Adds userTag array to the NTMultiChannel. * @return this instance of NTMultiChannelBuilder. */ shared_pointer addUserTag(); + /** - * Add isConnected array to the NTMultiChannel. + * Adds isConnected array to the NTMultiChannel. * @return this instance of NTMultiChannelBuilder. */ shared_pointer addIsConnected(); + /** - * Create a Structure that represents NTMultiChannel. + * Creates a Structure that represents NTMultiChannel. * This resets this instance state and allows new instance to be created. * @return a new instance of a Structure. */ epics::pvData::StructureConstPtr createStructure(); + /** - * Create a PVStructure that represents NTMultiChannel. - * This resets this instance state and allows new {@code instance to be created.} + * Creates a PVStructure that represents NTMultiChannel. + * This resets this instance state and allows new instance to be created. * @return a new instance of a PVStructure */ epics::pvData::PVStructurePtr createPVStructure(); + /** - * Create a NTMultiChannel instance. - * This resets this instance state and allows new {@code instance to be created.} + * Creates a NTMultiChannel instance. + * This resets this instance state and allows new instance to be created. * @return a new instance of a NTMultiChannel */ NTMultiChannelPtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of a NTMultiChannelBuilder */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); + private: NTMultiChannelBuilder(); @@ -172,64 +187,92 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTMultiChannel. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTMultiChannel. - * @return NTMultiChannel instance on success, nullptr otherwise. + * Creates an NTMultiChannel wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTMultiChannel + * and if so returns an NTMultiChannel which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTMultiChannel instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTMultiChannel without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTMultiChannel. - * @return NTMultiChannel instance. + * Creates an NTMultiChannel wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTMultiChannel or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTMultiChannel instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTMultiChannel. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTMultiChannel. + * Returns whether the specified Structure reports to be a compatible NTMultiChannel. + *

+ * Checks whether the specified Structure reports compatibility with this + * version of NTMultiChannel through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTMultiChannel */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTMultiChannel. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTMultiChannel. + * Returns whether the specified PVStructure reports to be a compatible NTMultiChannel. + *

+ * Checks whether the specified PVStructure reports compatibility with this + * version of NTMultiChannel through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTMultiChannel */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTMultiChannel. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTMultiChannel. + * Returns whether the specified Structure is compatible with NTMultiChannel. + *

+ * Checks whether the specified Structure is compatible with this version + * of NTMultiChannel through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTMultiChannel */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTMultiChannel. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTMultiChannel. + * Returns whether the specified PVStructure is compatible with NTMultiChannel. + *

+ * Checks whether the specified PVStructure is compatible with this version + * of NTMultiChannel through the introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTMultiChannel */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTMultiChannel. + * Checks whether the wrapped PVStructure is valid with respect to this + * version of NTMultiChannel. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTMultiChannel - * @return (false,true) if (is not, is) a valid NTMultiChannel. + * @return (false,true) if the wrapped PVStructure (is not, is) a valid NTMultiChannel */ bool isValid(); /** - * Create a NTMultiChannelBuilder instance + * Creates an NTMultiChannelBuilder instance * @return builder instance. */ static NTMultiChannelBuilderPtr createBuilder(); @@ -238,99 +281,113 @@ public: * Destructor */ ~NTMultiChannel() {} - /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. - * @return true if the operation was successfull (i.e. this instance -has a timeStamp field), otherwise false. - */ + /** + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. + * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; + /** - * Attach a pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; + /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const {return pvNTMultiChannel;} + /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. - */ - epics::pvData::PVStructurePtr getTimeStamp() const - {return pvTimeStamp;} - /** - * Get the alarm. - * @return PVStructurePtr which may be null. - */ - epics::pvData::PVStructurePtr getAlarm() const - {return pvAlarm;} - /** - * Get the value of each channel. - * @return PVUnionArrayPtr - */ - epics::pvData::PVUnionArrayPtr getValue() const - {return pvValue;} - /** - * Get the channelName of each channel. - * @return PVStringArrayPtr - */ - epics::pvData::PVStringArrayPtr getChannelName() const - { return pvChannelName;}; - /** - * Get the connection state of each channel. - * @return PVBooleanArrayPtr - */ - epics::pvData::PVBooleanArrayPtr getIsConnected() const - { return pvIsConnected;}; - /** - * Get the severity of each channel. - * @return PVIntArrayPtr which may be null. - */ - epics::pvData::PVIntArrayPtr getSeverity() const - {return pvSeverity;} - /** - * Get the status of each channel. - * @return PVIntArrayPtr which may be null. - */ - epics::pvData::PVIntArrayPtr getStatus() const - {return pvStatus;} - /** - * Get the message of each chnnel. - * @return PVStringArrayPtr which may be null. - */ - epics::pvData::PVStringArrayPtr getMessage() const - {return pvMessage;} - /** - * Get the secondsPastEpoch of each channel. - * @return PVLongArrayPtr which may be null. - */ - epics::pvData::PVLongArrayPtr getSecondsPastEpoch() const - {return pvSecondsPastEpoch;} - /** - * Get the nanoseconds of each channel. - * @return PVIntArrayPtr which may be null. - */ - epics::pvData::PVIntArrayPtr getNanoseconds() const - {return pvNanoseconds;} - /** - * Get the userTag of each channel. - * @return PVIntArrayPtr which may be null. - */ - epics::pvData::PVIntArrayPtr getUserTag() const - {return pvUserTag;} - /** - * Get the descriptor. - * @return PVStringPtr which may be null. + * Return the descriptor field. + * @return the descriptor field or null if no descriptor field. */ epics::pvData::PVStringPtr getDescriptor() const {return pvDescriptor;} + + /** + * Returns the timeStamp field. + * @return the timeStamp field or null if no such field. + */ + epics::pvData::PVStructurePtr getTimeStamp() const + {return pvTimeStamp;} + + /** + * Returns the alarm field. + * @return the alarm field or null if no such field. + */ + epics::pvData::PVStructurePtr getAlarm() const + {return pvAlarm;} + + /** + * Returns the field with the value of each channel. + * @return the value field. + */ + epics::pvData::PVUnionArrayPtr getValue() const + {return pvValue;} + + /** + * Returns the field with the channelName of each channel. + * @return the channelName field + */ + epics::pvData::PVStringArrayPtr getChannelName() const + { return pvChannelName;}; + + /** + * Returns the field with the connection state of each channel. + * @return the isConnected field or null if no such field + */ + epics::pvData::PVBooleanArrayPtr getIsConnected() const + { return pvIsConnected;}; + + /** + * Returns the field with the severity of each channel. + * @return the severity field or null if no such field + */ + epics::pvData::PVIntArrayPtr getSeverity() const + {return pvSeverity;} + + /** + * Returns the field with the status of each channel. + * @return the status field or null if no such field + */ + epics::pvData::PVIntArrayPtr getStatus() const + {return pvStatus;} + + /** + * Returns the field with the message of each channel. + * @return message field or null if no such field. + */ + epics::pvData::PVStringArrayPtr getMessage() const + {return pvMessage;} + + /** + * Returns the field with the secondsPastEpoch of each channel. + * @return the secondsPastEpoch field or null if no such field. + */ + epics::pvData::PVLongArrayPtr getSecondsPastEpoch() const + {return pvSecondsPastEpoch;} + + /** + * Returns the field with the nanoseconds of each channel. + * @return nanoseconds field or null if no such field. + */ + epics::pvData::PVIntArrayPtr getNanoseconds() const + {return pvNanoseconds;} + + /** + * Returns the field with the userTag of each channel. + * @return the userTag field or null if no such field. + */ + epics::pvData::PVIntArrayPtr getUserTag() const + {return pvUserTag;} + private: NTMultiChannel(epics::pvData::PVStructurePtr const & pvStructure); epics::pvData::PVStructurePtr pvNTMultiChannel; diff --git a/src/nt/ntnameValue.h b/src/nt/ntnameValue.h index 43bcc6c..d909365 100644 --- a/src/nt/ntnameValue.h +++ b/src/nt/ntnameValue.h @@ -45,55 +45,55 @@ namespace detail { POINTER_DEFINITIONS(NTNameValueBuilder); /** - * Set a value array Scalar type. - * @param scalarType value array scalar array. + * Sets the value array Scalar type. + * @param scalarType the value field element ScalarType * @return this instance of NTTableBuilder. */ shared_pointer value(epics::pvData::ScalarType scalarType); /** - * Add descriptor field to the NTNameValue. + * Adds descriptor field to the NTNameValue. * @return this instance of NTTableBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTNameValue. + * Adds alarm field to the NTNameValue. * @return this instance of NTTableBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTNameValue. + * Adds timeStamp field to the NTNameValue. * @return this instance of NTTableBuilder. */ shared_pointer addTimeStamp(); /** - * Create a Structure that represents NTNameValue. + * Creates a Structure that represents NTNameValue. * This resets this instance state and allows new instance to be created. * @return a new instance of Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTNameValue. + * Creates a PVStructure that represents NTNameValue. * This resets this instance state and allows new instance to be created. * @return a new instance of PVStructure */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTNameValue instance. + * Creates a NTNameValue instance. * This resets this instance state and allows new instance to be created. * @return a new instance of NTNameValue */ NTNameValuePtr create(); /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTTableBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -134,65 +134,90 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTNameValue. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTNameValue. - * @return NTNameValue instance on success, nullptr otherwise. + * Creates an NTNameValue wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTNameValue + * and if so returns an NTNameValue which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped. + * @return NTNameValue instance wrapping pvStructure on success, null otherwise. */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTNameValue without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTNameValue. - * @return NTNameValue instance. + * Creates an NTNameValue wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTNameValue or is non-null. + * + * @param pvStructure the PVStructure to be wrapped. + * @return NTNameValue instance wrapping pvStructure. */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTNameValue. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTNameValue. + * Returns whether the specified Structure reports to be a compatible NTNameValue. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTNameValue through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test. + * @return (false,true) if the specified Structure (is not, is) a compatible NTNameValue. */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTNameValue. + * Returns whether the specified PVStructure reports to be a compatible NTNameValue. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTNameValue through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTNameValue. + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTNameValue. */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTNameValue. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTNameValue. + * Returns whether the specified Structure is compatible with NTNameValue. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTNameValue through the introspection interface. + * @param structure the Structure to test. + * @return (false,true) if the specified Structure (is not, is) a compatible NTNameValue. */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTNameValue. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTNameValue. + * Returns whether the specified PVStructure is compatible with NTNameValue. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTNameValue through the introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTNameValue */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTNameValue. + * Returns whether the wrapped PVStructure is valid with respect to this + * version of NTNameValue. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTNameValue - * @return (false,true) if (is not, is) a valid NTNameValue. + * @return (false,true) if the wrapped PVStructure (is not, is) a valid NTNameValue */ bool isValid(); /** - * Create a NTNameValue builder instance. + * Creates an NTNameValue builder instance. * @return builder instance. */ static NTNameValueBuilderPtr createBuilder(); @@ -203,60 +228,63 @@ public: ~NTNameValue() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no descriptor field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no timeStamp field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no alarm field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the name array field. + * Returns the name array field. * @return The PVStringArray for the name. */ epics::pvData::PVStringArrayPtr getName() const; /** - * Get the value array field. + * Returns the value array field. * @return The PVField for the value. */ epics::pvData::PVFieldPtr getValue() const; /** - * Get the value array field of a specified type (e.g. PVDoubleArray). - * @return The array for the value. + * Returns the value array field of a specified expected type (e.g. PVDoubleArray). + * + * @tparam PVT The expected type of the value field which should be + * be PVScalarArray or a derived class. + * @return The PVT array for the value. */ template std::tr1::shared_ptr getValue() const diff --git a/src/nt/ntndarray.h b/src/nt/ntndarray.h index 67c9e05..4c1a816 100644 --- a/src/nt/ntndarray.h +++ b/src/nt/ntndarray.h @@ -48,53 +48,54 @@ namespace detail { POINTER_DEFINITIONS(NTNDArrayBuilder); /** - * Add descriptor field to the NTNDArray. + * Adds descriptor field to the NTNDArray. * @return this instance of NTNDArrayBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTNDArray. + * Adds alarm field to the NTNDArray. * @return this instance of NTNDArrayBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTNDArray. + * Adds timeStamp field to the NTNDArray. * @return this instance of NTNDArrayBuilder. */ shared_pointer addTimeStamp(); /** - * Add display structure to the NTNDArray. + * Adds display field to the NTNDArray. * @return this instance of NTNDArrayBuilder. */ shared_pointer addDisplay(); /** - * Create a Structure that represents NTNDArray. + * Creates a Structure that represents NTNDArray. * This resets this instance state and allows new instance to be created. * @return a new instance of a Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTNDArray. + * Creates a PVStructure that represents NTNDArray. * This resets this instance state and allows new instance to be created. * @return a new instance of a PVStructure */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTNDArray instance. + * Creates a NTNDArray instance. * This resets this instance state and allows new instance to be created. * @return a new instance of a NTNDArray */ NTNDArrayPtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of a NTArrayBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -133,65 +134,91 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTNDArray. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTNDArray. - * @return NTNDArray instance on success, nullptr otherwise. + * Creates an NTScalarArray wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTScalarArray + * and if so returns an NTScalarArray which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTScalarArray instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTNDArray without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTNDArray. - * @return NTNDArray instance. + * Creates an NTNDArray wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTNDArray or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTNDArray instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTNDArray. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTNDArray. + * Returns whether the specified Structure reports to be a compatible NTNDArray. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTNDArray through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the pvStructure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTNDArray */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTNDArray. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTNDArray. + * Returns whether the specified PVStructure reports to be a compatible NTNDArray. + * + * Checks if the specified PVStructure reports compatibility with this + * version of NTNDArray through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTNDArray */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTNDArray. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTNDArray. + * Returns whether the specified Structure is compatible with NTNDArray. + *

+ * Checks if the specified Structure is compatible with this version + * of NTNDArray through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTNDArray */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTNDArray. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTNDArray. + * Returns whether the specified PVStructure is compatible with NTNDArray. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTNDArray through the introspection interface. + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTNDArray */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTNDArray. + * Returns whether the wrapped PVStructure is valid with respect to this + * version of NTNDArray. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTNDArray - * @return (false,true) if (is not, is) a valid NTNDArray. + * @return (false,true) if the wrapped PVStructure (is not, is) a valid NTNDArray */ bool isValid(); /** - * Create a NTNDArrayBuilder instance + * Creates an NTNDArrayBuilder instance * @return builder instance. */ static NTNDArrayBuilderPtr createBuilder(); @@ -202,15 +229,15 @@ public: ~NTNDArray() {} /** - * Attach a pvTimeStamp to timeStamp field. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach a pvTimeStamp to dataTimeStamp field. + * Attaches a pvTimeStamp to dataTimeStamp field. * @param pvTimeStamp The pvTimeStamp that will be attached. * Does nothing if no timeStamp. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. @@ -218,88 +245,96 @@ public: bool attachDataTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the value field. + * Returns the value field. * @return The PVField for the values. */ epics::pvData::PVUnionPtr getValue() const; /** - * Get the codec field. + * Returns the codec field. * @return the PVStructurePtr. */ epics::pvData::PVStructurePtr getCodec() const; /** - * Get the compressedDataSize field. + * Returns the compressedDataSize field. * @return PVStructurePtr. */ epics::pvData::PVLongPtr getCompressedDataSize() const; /** - * Get the uncompressedDataSize field. + * Returns the uncompressedDataSize field. * @return PVStructurePtr. */ epics::pvData::PVLongPtr getUncompressedDataSize() const; /** - * Get the dimension field. + * Returns the dimension field. * @return the PVStructurePtr. */ epics::pvData::PVStructureArrayPtr getDimension() const; /** - * Get the uniqueId field. + * Returns the uniqueId field. * @return PVStructurePtr. */ epics::pvData::PVIntPtr getUniqueId() const; /** - * Get the data timeStamp field. + * Returns the data timeStamp field. * @return PVStructurePtr. */ epics::pvData::PVStructurePtr getDataTimeStamp() const; /** - * Get the attribute field. + * Returns the attribute field. * @return the PVStructurePtr. */ epics::pvData::PVStructureArrayPtr getAttribute() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no descriptor field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp field. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no timeStamp field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm field. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no alarm field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the display field. - * @return PVStructurePtr which may be null. + * Attaches a PVDisplay to the wrapped PVStructure. + * Does nothing if no display. + * @param pvDisplay the PVDisplay that will be attached. + * @return true if the operation was successfull (i.e. this instance has a display field), otherwise false. + */ + bool attachDisplay(epics::pvData::PVDisplay &pvDisplay) const; + + /** + * Returns the display field. + * @return PVStructurePtr or null if no alarm field. */ epics::pvData::PVStructurePtr getDisplay() const; diff --git a/src/nt/ntndarrayAttribute.h b/src/nt/ntndarrayAttribute.h index 3160869..4fe8489 100644 --- a/src/nt/ntndarrayAttribute.h +++ b/src/nt/ntndarrayAttribute.h @@ -42,53 +42,54 @@ namespace detail { POINTER_DEFINITIONS(NTNDArrayAttributeBuilder); /** - * Add tags field to the NTNDArrayAttribute. + * Adds tags field to the NTNDArrayAttribute. * @return this instance of NTNDArrayAttributeBuilder. */ virtual shared_pointer addTags(); /** - * Add descriptor field to the NTNDArrayAttribute. + * Adds descriptor field to the NTNDArrayAttribute. * @return this instance of NTNDArrayAttributeBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTNDArrayAttribute. + * Adds alarm field to the NTNDArrayAttribute. * @return this instance of NTNDArrayAttributeBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTNDArrayAttribute. + * Adds timeStamp field to the NTNDArrayAttribute. * @return this instance of NTNDArrayAttributeBuilder. */ shared_pointer addTimeStamp(); /** - * Create a Structure that represents NTNDArrayAttribute. + * Creates a Structure that represents NTNDArrayAttribute. * This resets this instance state and allows new instance to be created. * @return a new instance of a Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTNDArrayAttribute. + * Creates a PVStructure that represents NTNDArrayAttribute. * This resets this instance state and allows new instance to be created. * @return a new instance of a PVStructure. */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTNDArrayAttribute instance. + * Creates a NTNDArrayAttribute instance. * This resets this instance state and allows new instance to be created. * @return a new instance of a NTNDArrayAttribute. */ NTNDArrayAttributePtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTNDArrayAttributeBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -129,65 +130,98 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTNDArrayAttribute. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTNDArrayAttribute. - * @return NTNDArrayAttribute instance on success, nullptr otherwise. + * Creates an NTNDArrayAttribute wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTAttribute + * extended as required by NTNDArray and if so returns an + * NTNDArrayAttribute which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTAttribute instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTNDArrayAttribute without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTNDArrayAttribute. - * @return NTNDArrayAttribute instance. + * Creates an NTNDArrayAttribute wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTAttribute extended as required by NTNDArray + * or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTAttribute instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTNDArrayAttribute. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTNDArrayAttribute. + * Returns whether the specified Structure reports to be a compatible NTAttribute. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTAttribute through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTAttribute */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTNDArrayAttribute. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTNDArrayAttribute. + * Returns whether the specified PVStructure reports to be a compatible NTAttribute. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTAttribute through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTAttribute */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTNDArrayAttribute. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTNDArrayAttribute. + * Returns whether the specified Structure is compatible with NTAttribute + * extended as required by NTNDArray. + *

+ * Checks if the specified Structure is compatible with this version + * of NTAttribute extended as required by this version of NTNDArray + * through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTAttribute */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTNDArrayAttribute. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTNDArrayAttribute. + * Returns whether the specified PVStructure is compatible with NTAttribute + * extended as required by NTNDArray. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTAttribute extended as required by this version of NTNDArray + * through the introspection interface. + + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTAttribute */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTNDArrayAttribute. + * Returns whether the wrapped PVStructure is valid with respect to this + * version of NTAttribute extended as per this version of NTNDArray. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTNDArrayAttribute - * @return (false,true) if (is not, is) a valid NTNDArrayAttribute. + * @return (false,true) if the wrapped PVStructure (is not, is) a valid NTNDArrayAttribute */ bool isValid(); /** - * Create a NTNDArrayAttribute builder instance. + * Creates an NTNDArrayAttribute builder instance. * @return builder instance. */ static NTNDArrayAttributeBuilderPtr createBuilder(); @@ -198,72 +232,72 @@ public: ~NTNDArrayAttribute() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString + * Returns the descriptor field. + * @return the descriptor field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no such field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no alarm field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the name field. - * @return The PVString for the name. + * Returns the name field. + * @return the name field. */ epics::pvData::PVStringPtr getName() const; /** - * Get the value field. - * @return The PVUnion for the values. + * Returns the value field. + * @return the value field. */ epics::pvData::PVUnionPtr getValue() const; /** - * Get the tags field. - * @return The PVStringArray for the tags, which may be null. + * Returns the tags field. + * @return the tags field or null if no such field. */ epics::pvData::PVStringArrayPtr getTags() const; /** - * Get the sourceType field. - * @return The PVInt for the sourceType field. + * Returns the sourceType field. + * @return the sourceType field. */ epics::pvData::PVIntPtr getSourceType() const; /** - * Get the source field. - * @return The PVString for the source field, which may be null. + * Returns the source field. + * @return the source field. */ epics::pvData::PVStringPtr getSource() const; diff --git a/src/nt/ntscalar.h b/src/nt/ntscalar.h index 0126474..001d648 100644 --- a/src/nt/ntscalar.h +++ b/src/nt/ntscalar.h @@ -45,66 +45,67 @@ namespace detail { POINTER_DEFINITIONS(NTScalarBuilder); /** - * Set a value type of a NTScalar. + * Sets the value type of an NTScalar. * @param scalarType the value type. * @return this instance of NTScalarBuilder. */ shared_pointer value(epics::pvData::ScalarType scalarType); /** - * Add descriptor field to the NTScalar. + * Adds descriptor field to the NTScalar. * @return this instance of NTScalarBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTScalar. + * Adds alarm field to the NTScalar. * @return this instance of NTScalarBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTScalar. + * Adds timeStamp field to the NTScalar. * @return this instance of NTScalarBuilder. */ shared_pointer addTimeStamp(); /** - * Add display structure to the NTScalar. + * Adds display field to the NTScalar. * @return this instance of NTScalarBuilder. */ shared_pointer addDisplay(); /** - * Add control structure to the NTScalar. + * Adds control field to the NTScalar. * @return this instance of NTScalarBuilder. */ shared_pointer addControl(); /** - * Create a Structure that represents NTScalar. + * Creates a Structure that represents NTScalar. * This resets this instance state and allows new instance to be created. * @return a new instance of a Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTScalar. + * Creates a PVStructure that represents NTScalar. * This resets this instance state and allows new instance to be created. * @return a new instance of a PVStructure. */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTScalar instance. + * Creates a NTScalar instance. * This resets this instance state and allows new instance to be created. * @return a new instance of a NTScalar. */ NTScalarPtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTScalarBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -149,65 +150,92 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTScalar. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTScalar. - * @return NTScalar instance on success, nullptr otherwise. + * Creates an NTScalar wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTScalar + * and if so returns an NTScalar which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTScalar instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTMultiChannel without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTScalar. - * @return NTScalar instance. + * Creates an NTScalar wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTScalar or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTScalar instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTScalar. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTScalar. + * Returns whether the specified Structure reports to be a compatible NTScalar. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTScalar through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTScalar */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTScalar. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTScalar. + * Returns whether the specified PVStructure reports to be a compatible NTScalar. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTScalar through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTScalar */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTScalar. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTScalar. + * Returns whether the specified Structure is compatible with NTScalar. + *

+ * Checks if the specified Structure is compatible with this version + * of NTScalar through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTScalar */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTScalar. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTScalar. + * Returns whether the specified PVStructure is compatible with NTScalar. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTScalar through the introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTScalar */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTScalar. + * Returns whether the wrapped PVStructure is valid with respect to this + * version of NTScalar. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTScalar - * @return (false,true) if (is not, is) a valid NTScalar. + * @return (false,true) if wrapped PVStructure (is not, is) a valid NTScalar */ bool isValid(); /** - * Create a NTScalar builder instance. + * Creates an NTScalar builder instance. * @return builder instance. */ static NTScalarBuilderPtr createBuilder(); @@ -218,82 +246,84 @@ public: ~NTScalar() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Attach an pvDisplay. - * @param pvDisplay The pvDisplay that will be attached. - * Does nothing if no display. - * @return true if the operation was successfull (i.e. this instance has a display field), otherwise false. + * Attaches a PVDisplay to the wrapped PVStructure. + * Does nothing if no display field. + * @param pvDisplay the PVDisplay that will be attached. + * @return true if the operation was successfull (i.e. this instance has a display field), otherwise false. */ bool attachDisplay(epics::pvData::PVDisplay &pvDisplay) const; /** - * Attach an pvControl. - * @param pvControl The pvControl that will be attached. - * Does nothing if no control. - * @return true if the operation was successfull (i.e. this instance has a control field), otherwise false. + * Attaches an PVControl to the wrapped PVStructure. + * Does nothing if no control field. + * @param pvControl The PVControl that will be attached. + * @return true if the operation was successfull (i.e. this instance has a control field), otherwise false. */ bool attachControl(epics::pvData::PVControl &pvControl) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no descriptor field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no timeStamp field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no alarm field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the display. + * Returns the display. * @return PVStructurePtr which may be null. */ epics::pvData::PVStructurePtr getDisplay() const; /** - * Get the control. + * Returns the control. * @return PVStructurePtr which may be null. */ epics::pvData::PVStructurePtr getControl() const; /** - * Get the value field. + * Returns the value field. * @return The PVField for the values. */ epics::pvData::PVFieldPtr getValue() const; /** - * Get the value field of a specified type (e.g. PVDouble). - * @return The field for the values. + * Returns the value field of a specified type (for example, PVDouble). + * @tparam PVT the expected type of the value field which should be + * be PVScalar or a derived class. + * @return the value field or null if it is not of the expected type. */ template std::tr1::shared_ptr getValue() const diff --git a/src/nt/ntscalarArray.h b/src/nt/ntscalarArray.h index cbff885..5165d2e 100644 --- a/src/nt/ntscalarArray.h +++ b/src/nt/ntscalarArray.h @@ -46,66 +46,75 @@ namespace detail { POINTER_DEFINITIONS(NTScalarArrayBuilder); /** - * Set a value type of a NTScalarArray. + * Sets the value type of the NTScalarArray. + * @param elementType the value field element ScalarType. + * @return this instance of NTScalarArrayBuilder. + */ + shared_pointer value(epics::pvData::ScalarType elementType); + + /** + * Sets the value type of the NTScalarArray. * @param elementType the value array element type. * @return this instance of NTScalarArrayBuilder. + * @deprecated use value instead. */ shared_pointer arrayValue(epics::pvData::ScalarType elementType); /** - * Add descriptor field to the NTScalarArray. + * Adds descriptor field to the NTScalarArray. * @return this instance of NTScalarArrayBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTScalarArray. + * Adds alarm field to the NTScalarArray. * @return this instance of NTScalarArrayBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTScalarArray. + * Adds timeStamp field to the NTScalarArray. * @return this instance of NTScalarArrayBuilder. */ shared_pointer addTimeStamp(); /** - * Add display structure to the NTScalarArray. + * Adds display field to the NTScalarArray. * @return this instance of NTScalarArrayBuilder. */ shared_pointer addDisplay(); /** - * Add control structure to the NTScalarArray. + * Adds control field to the NTScalarArray. * @return this instance of NTScalarArrayBuilder. */ shared_pointer addControl(); /** - * Create a Structure that represents NTScalarArray. + * Creates a Structure that represents NTScalarArray. * This resets this instance state and allows new instance to be created. * @return a new instance of Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTScalarArray. + * Creates a PVStructure that represents NTScalarArray. * This resets this instance state and allows new instance to be created. * @return a new instance of PVStructure. */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTScalarArray instance. + * Creates a NTScalarArray instance. * This resets this instance state and allows new instance to be created. * @return a new instance of NTScalarArray. */ NTScalarArrayPtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTScalarArrayBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -150,65 +159,91 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTScalarArray. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTScalarArray. - * @return NTScalarArray instance on success, nullptr otherwise. + * Creates an NTScalarArray wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTScalarArray + * and if so returns an NTScalarArray which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTScalarArray instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTMatrix without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTScalarArray. - * @return NTScalarArray instance. + * Creates an NTScalarArray wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTScalarArray or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTScalarArray instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTScalarArray. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTScalarArray. + * Returns whether the specified Structure reports to be a compatible NTScalarArray. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTScalarArray through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTScalarArray */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTScalarArray. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTScalarArray. + * Returns whether the specified PVStructure reports to be a compatible NTScalarArray. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTScalarArray through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTScalarArray */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTScalarArray. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTScalarArray. + * Returns whether the specified Structure is compatible with NTScalarArray. + *

+ * Checks if the specified Structure is compatible with this version + * of NTScalarArray through the introspection interface. + * + * @param structure the Structure to test. + * @return (false,true) if the specified Structure (is not, is) a compatible NTScalarArray */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTScalarArray. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTScalarArray. + * Returns whether the specified PVStructure is compatible with NTScalarArray. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTScalarArray through the introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTScalarArray */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTScalarArray. + * Returns whether the wrapped PVStructure is a valid NTScalarArray. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTScalarArray - * @return (false,true) if (is not, is) a valid NTScalarArray. + * @return (false,true) if the wrapped PVStructure (is not, is) a valid NTScalarArray. */ bool isValid(); /** - * Create a NTScalarArray builder instance. + * Creates an NTScalarArray builder instance. * @return builder instance. */ static NTScalarArrayBuilderPtr createBuilder(); @@ -219,82 +254,84 @@ public: ~NTScalarArray() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Attach an pvDisplay. - * @param pvDisplay The pvDisplay that will be attached. - * Does nothing if no display. - * @return true if the operation was successfull (i.e. this instance has a display field), otherwise false. + * Attaches a PVDisplay to the wrapped PVStructure. + * Does nothing if no display field. + * @param pvDisplay the PVDisplay that will be attached. + * @return true if the operation was successfull (i.e. this instance has a display field), otherwise false. */ bool attachDisplay(epics::pvData::PVDisplay &pvDisplay) const; /** - * Attach an pvControl. + * Attaches an pvControl. * @param pvControl The pvControl that will be attached. - * Does nothing if no control. + * Does nothing if no control field. * @return true if the operation was successfull (i.e. this instance has a control field), otherwise false. */ bool attachControl(epics::pvData::PVControl &pvControl) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no descriptor field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no timeStamp field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no alarm field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the display. + * Returns the display. * @return PVStructurePtr which may be null. */ epics::pvData::PVStructurePtr getDisplay() const; /** - * Get the control. + * Returns the control. * @return PVStructurePtr which may be null. */ epics::pvData::PVStructurePtr getControl() const; /** - * Get the value field. + * Returns the value field. * @return The PVField for the values. */ epics::pvData::PVFieldPtr getValue() const; /** - * Get the value field of a specified type (e.g. PVDoubleArray). - * @return The field for the values. + * Returns the value field of a specified type (e.g. PVDoubleArray). + * @tparam PVT the expected type of the value field which should be + * be PVScalarArray or a derived class. + * @return the value field or null if it is not of the expected type. */ template std::tr1::shared_ptr getValue() const diff --git a/src/nt/ntscalarMultiChannel.h b/src/nt/ntscalarMultiChannel.h index d0f6f67..0cc79bd 100644 --- a/src/nt/ntscalarMultiChannel.h +++ b/src/nt/ntscalarMultiChannel.h @@ -49,87 +49,104 @@ namespace detail { { public: POINTER_DEFINITIONS(NTScalarMultiChannelBuilder); + /** - * specify the scalar type for the value field. + * Sets the scalar type for the value field. * If this is not called then pvDouble is the default. + * @param scalarType the value field element ScalarType. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer value(epics::pvData::ScalarType scalarType); + /** - * Add descriptor field to the NTScalarMultiChannel. + * Adds descriptor field to the NTScalarMultiChannel. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer addDescriptor(); + /** - * Add alarm structure to the NTScalarMultiChannel. + * Adds alarm field to the NTScalarMultiChannel. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer addAlarm(); + /** - * Add timeStamp structure to the NTScalarMultiChannel. + * Adds timeStamp field to the NTScalarMultiChannel. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer addTimeStamp(); + /** - * Add severity array to the NTScalarMultiChannel. + * Adds severity array to the NTScalarMultiChannel. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer addSeverity(); + /** - * Add status array to the NTScalarMultiChannel. + * Adds status array to the NTScalarMultiChannel. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer addStatus(); + /** - * Add message array to the NTScalarMultiChannel. + * Adds message array to the NTScalarMultiChannel. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer addMessage(); + /** - * Add secondsPastEpoch array to the NTScalarMultiChannel. + * Adds secondsPastEpoch array to the NTScalarMultiChannel. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer addSecondsPastEpoch(); + /** - * Add nanoseconds array to the NTScalarMultiChannel. + * Adds nanoseconds array to the NTScalarMultiChannel. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer addNanoseconds(); + /** - * Add userTag array to the NTScalarMultiChannel. + * Adds userTag array to the NTScalarMultiChannel. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer addUserTag(); + /** - * Add isConnected array to the NTScalarMultiChannel. + * Adds isConnected array to the NTScalarMultiChannel. * @return this instance of NTScalarMultiChannelBuilder. */ shared_pointer addIsConnected(); + /** - * Create a Structure that represents NTScalarMultiChannel. + * Creates a Structure that represents NTScalarMultiChannel. * This resets this instance state and allows new instance to be created. * @return a new instance of a Structure. */ epics::pvData::StructureConstPtr createStructure(); + /** - * Create a PVStructure that represents NTScalarMultiChannel. - * This resets this instance state and allows new {@code instance to be created.} + * Creates a PVStructure that represents NTScalarMultiChannel. + * This resets this instance state and allows new instance to be created. * @return a new instance of a PVStructure */ epics::pvData::PVStructurePtr createPVStructure(); + /** - * Create a NTScalarMultiChannel instance. - * This resets this instance state and allows new {@code instance to be created.} + * Creates a NTScalarMultiChannel instance. + * This resets this instance state and allows new instance to be created. * @return a new instance of a NTScalarMultiChannel */ NTScalarMultiChannelPtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of a NTScalarMultiChannelBuilder */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); + private: NTScalarMultiChannelBuilder(); @@ -173,64 +190,90 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTScalarMultiChannel. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTScalarMultiChannel. - * @return NTScalarMultiChannel instance on success, nullptr otherwise. + * Creates an NTScalarMultiChannel wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTScalarMultiChannel + * and if so returns an NTScalarMultiChannel which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTScalarMultiChannel instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTScalarMultiChannel without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTScalarMultiChannel. - * @return NTScalarMultiChannel instance. + * Creates an NTScalarMultiChannel wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTScalarMultiChannel or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTScalarMultiChannel instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTScalarMultiChannel. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTScalarMultiChannel. + * Returns whether the specified Structure reports to be a compatible NTScalarMultiChannel. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTScalarMultiChannel through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTScalarMultiChannel */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTScalarMultiChannel. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTScalarMultiChannel. + * Returns whether the specified PVStructure reports to be a compatible NTScalarMultiChannel. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTScalarMultiChannel through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTScalarMultiChannel */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTScalarMultiChannel. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTScalarMultiChannel. + * Returns whether the specified Structure is compatible with NTScalarMultiChannel. + *

+ * Checks if the specified Structure is compatible with this version + * of NTScalarMultiChannel through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTScalarMultiChannel */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTScalarMultiChannel. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTScalarMultiChannel. + * Returns whether the wrapped PVStructure is a valid NTScalarMultiChannel. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. + * + * @return (false,true) if wrapped PVStructure (is not, is) a valid NTScalarMultiChannel */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTScalarMultiChannel. + * Returns whether the specified PVStructure is a valid NTScalarMultiChannel. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTScalarMultiChannel - * @return (false,true) if (is not, is) a valid NTScalarMultiChannel. + * @return (false,true) if wrapped PVStructure (is not, is) a valid NTScalarMultiChannel. */ bool isValid(); /** - * Create a NTScalarMultiChannelBuilder instance + * Creates an NTScalarMultiChannelBuilder instance * @return builder instance. */ static NTScalarMultiChannelBuilderPtr createBuilder(); @@ -239,107 +282,126 @@ public: * Destructor */ ~NTScalarMultiChannel() {} - /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. - */ + /** + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. + * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; + /** - * Attach a pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; + /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const {return pvNTScalarMultiChannel;} + /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Return the descriptor field. + * @return the descriptor field or null if no descriptor field. + */ + epics::pvData::PVStringPtr getDescriptor() const + {return pvDescriptor;} + + /** + * Returns the timeStamp field. + * @return the timeStamp field or null if no such field. */ epics::pvData::PVStructurePtr getTimeStamp() const {return pvTimeStamp;} + /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no such field. */ epics::pvData::PVStructurePtr getAlarm() const {return pvAlarm;} + /** - * Get the value of each channel. - * @return PVScalarArrayPtr + * Returns the field with the value of each channel. + * @return the value field. */ epics::pvData::PVScalarArrayPtr getValue() const {return pvValue;} + /** - * Get the value field of a specified type (e.g. PVDoubleArray). - * @return The field for the values. + * Returns the value of each channel of a specified expected type + * (for example, PVDoubleArray). + * @tparam PVT the expected type of the value field which should be + * be PVScalarArray or a derived class. + * @return the value field or null if it is not of the expected type. */ template std::tr1::shared_ptr getValue() const { return std::tr1::dynamic_pointer_cast(pvValue); } + /** - * Get the channelName of each channel. - * @return PVStringArrayPtr + * Returns the field with the channelName of each channel. + * @return the channelName field */ epics::pvData::PVStringArrayPtr getChannelName() const { return pvChannelName;}; + /** - * Get the connection state of each channel. - * @return PVBooleanArrayPtr + * Returns the field with the connection state of each channel. + * @return the isConnected field or null if no such field */ epics::pvData::PVBooleanArrayPtr getIsConnected() const { return pvIsConnected;}; + /** - * Get the severity of each channel. - * @return PVIntArrayPtr which may be null. + * Returns the field with the severity of each channel. + * @return the severity field or null if no such field */ epics::pvData::PVIntArrayPtr getSeverity() const {return pvSeverity;} + /** - * Get the status of each channel. - * @return PVIntArrayPtr which may be null. + * Returns the field with the status of each channel. + * @return the status field or null if no such field */ epics::pvData::PVIntArrayPtr getStatus() const {return pvStatus;} + /** - * Get the message of each chnnel. - * @return PVStringArrayPtr which may be null. + * Returns the field with the message of each channel. + * @return message field or null if no such field. */ epics::pvData::PVStringArrayPtr getMessage() const {return pvMessage;} + /** - * Get the secondsPastEpoch of each channel. - * @return PVLongArrayPtr which may be null. + * Returns the field with the secondsPastEpoch of each channel. + * @return the secondsPastEpoch field or null if no such field. */ epics::pvData::PVLongArrayPtr getSecondsPastEpoch() const {return pvSecondsPastEpoch;} + /** - * Get the nanoseconds of each channel. - * @return PVIntArrayPtr which may be null. + * Returns the field with the nanoseconds of each channel. + * @return nanoseconds field or null if no such field. */ epics::pvData::PVIntArrayPtr getNanoseconds() const {return pvNanoseconds;} + /** - * Get the userTag of each channel. - * @return PVIntArrayPtr which may be null. + * Returns the field with the userTag of each channel. + * @return the userTag field or null if no such field. */ epics::pvData::PVIntArrayPtr getUserTag() const {return pvUserTag;} - /** - * Get the descriptor. - * @return PVStringPtr which may be null. - */ - epics::pvData::PVStringPtr getDescriptor() const - {return pvDescriptor;} + private: NTScalarMultiChannel(epics::pvData::PVStructurePtr const & pvStructure); epics::pvData::PVStructurePtr pvNTScalarMultiChannel; diff --git a/src/nt/nttable.h b/src/nt/nttable.h index 5adb5d0..28fd8f4 100644 --- a/src/nt/nttable.h +++ b/src/nt/nttable.h @@ -48,7 +48,7 @@ namespace detail { POINTER_DEFINITIONS(NTTableBuilder); /** - * Add a column of given Scalar type. + * Adds a column of given Scalar type. * @param name name of the column. * @param elementType column type, a scalar array. * @return this instance of NTTableBuilder. @@ -56,32 +56,32 @@ namespace detail { shared_pointer addColumn(std::string const & name, epics::pvData::ScalarType elementType); /** - * Add descriptor field to the NTTable. + * Adds descriptor field to the NTTable. * @return this instance of NTTableBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTTable. + * Adds alarm field to the NTTable. * @return this instance of NTTableBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTTable. + * Adds timeStamp field to the NTTable. * @return this instance of NTTableBuilder. */ shared_pointer addTimeStamp(); /** - * Create a Structure that represents NTTable. + * Creates a Structure that represents NTTable. * This resets this instance state and allows new instance to be created. * @return a new instance of Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTTable. + * Creates a PVStructure that represents NTTable. * The returned PVStructure will have labels equal to the column names. * This resets this instance state and allows new instance to be created. * @return a new instance of PVStructure. @@ -89,17 +89,18 @@ namespace detail { epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTTable instance. + * Creates a NTTable instance. * The returned NTTable will wrap a PVStructure which will have * labels equal to the column names. * This resets this instance state and allows new instance to be created. * @return a new instance of NTTable. */ NTTablePtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTTableBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -142,65 +143,91 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTTable. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTTable. - * @return NTTable instance on success, nullptr otherwise. + * Creates an NTTable wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTTable + * and if so returns an NTTable which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTTable instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTMultiChannel without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTTable. - * @return NTTable instance. + * Creates an NTTable wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTTable or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTTable instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTTable. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTTable. + * Returns whether the specified Structure reports to be a compatible NTTable. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTTable through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTTable */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTTable. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTTable. + * Returns whether the specified PVStructure reports to be a compatible NTTable. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTTable through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTTable */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTTable. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTTable. + * Returns whether the specified Structure is compatible with NTTable. + *

+ * Checks if the specified Structure is compatible with this version + * of NTTable through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTTable */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTTable. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTTable. + * Returns whether the specified PVStructure is compatible with NTTable. + * + * Checks if the specified PVStructure is compatible with this version + * of NTTable through the introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTTable */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTTable. + * Returns whether the specified structure is a valid NTTable. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTTable - * @return (false,true) if (is not, is) a valid NTTable. + * @return (false,true) if wrapped PVStructure (is not, is) a valid NTTable */ bool isValid(); /** - * Create a NTTable builder instance. + * Creates an NTTable builder instance. * @return builder instance. */ static NTTableBuilderPtr createBuilder(); @@ -211,69 +238,73 @@ public: ~NTTable() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no descriptor field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no such field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no such field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the labels field. - * @return The pvStringArray for the labels. + * Returns the labels field. + * @return the labels field. */ epics::pvData::PVStringArrayPtr getLabels() const; /** - * Get the column names for the table. + * Returns the column names for the table. * For each name, calling getColumn should return the column, which should not be null. - * @return The column names. + * @return the column names. */ epics::pvData::StringArray const & getColumnNames() const; /** - * Get the PVField (column) for a field that follows the label field. - * @param columnName The name of the column. - * @return The PVFieldPtr for the field. + * Returns the PVField for the column with the specified colum name. + * @param columnName the name of the column. + * @return the field for the column or null if column does not exist. */ epics::pvData::PVFieldPtr getColumn(std::string const & columnName) const; /** - * Get the PVField (column) for a field that follows the label field of a specified type (e.g. PVDoubleArray). - * @param columnName The name of the column. - * @return The field. + * Returns the column with the specified column name and of a specified + * expected type (for example, PVDoubleArray). + * @tparam PVT the expected type of the column which should be + * be PVScalarArray or a derived class. + * @param columnName the name of the column. + * @return the field for the column or null if column does not exist + * or is not of the specified type. */ template std::tr1::shared_ptr getColumn(std::string const & columnName) const diff --git a/src/nt/ntunion.h b/src/nt/ntunion.h index 3234bfc..5896980 100644 --- a/src/nt/ntunion.h +++ b/src/nt/ntunion.h @@ -42,47 +42,47 @@ namespace detail { POINTER_DEFINITIONS(NTUnionBuilder); /** - * Add descriptor field to the NTUnion. + * Adds descriptor field to the NTUnion. * @return this instance of NTUnionBuilder. */ shared_pointer addDescriptor(); /** - * Add alarm structure to the NTUnion. + * Adds alarm field to the NTUnion. * @return this instance of NTUnionBuilder. */ shared_pointer addAlarm(); /** - * Add timeStamp structure to the NTUnion. + * Adds timeStamp field to the NTUnion. * @return this instance of NTUnionBuilder. */ shared_pointer addTimeStamp(); /** - * Create a Structure that represents NTUnion. + * Creates a Structure that represents NTUnion. * This resets this instance state and allows new instance to be created. * @return a new instance of a Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTUnion. + * Creates a PVStructure that represents NTUnion. * This resets this instance state and allows new instance to be created. * @return a new instance of a PVStructure. */ epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTUnion instance. + * Creates a NTUnion instance. * This resets this instance state and allows new instance to be created. * @return a new instance of a NTUnion. */ NTUnionPtr create(); /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTUnionBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -124,65 +124,88 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTUnion. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTUnion. - * @return NTUnion instance on success, nullptr otherwise. + * Creates an NTUnion wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTUnion + * and if so returns an NTUnion which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTUnion instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTUnion without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTUnion. - * @return NTUnion instance. + * Creates an NTUnion wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTUnion or is non-null. + * @param pvStructure the PVStructure to be wrapped + * @return NTUnion instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTUnion. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTUnion. + * Returns whether the specified Structure reports to be a compatible NTUnion. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTUnion through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTUnion */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTUnion. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTUnion. + * Returns whether the specified PVStructure reports to be a compatible NTUnion. + * + * Checks if the specified PVStructure reports compatibility with this + * version of NTUnion through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTUnion */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTUnion. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTUnion. + * Returns whether the specified Structure is compatible with NTUnion. + *

+ * Checks if the specified Structure is compatible with this version + * of NTUnion through the introspection interface. + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTUnion */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTUnion. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTUnion. + * Returns whether the specified PVStructure is compatible with NTUnion. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTUnion through the introspection interface + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTUnion */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTUnion. + * Returns whether the wrapped PVStructure is a valid NTUnion. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTUnion - * @return (false,true) if (is not, is) a valid NTUnion. + * @return (false,true) if wrapped PVStructure (is not, is) a valid NTUnion */ bool isValid(); /** - * Create a NTUnion builder instance. + * Creates an NTUnion builder instance. * @return builder instance. */ static NTUnionBuilderPtr createBuilder(); @@ -193,48 +216,48 @@ public: ~NTUnion() {} /** - * Attach a pvTimeStamp. - * @param pvTimeStamp The pvTimeStamp that will be attached. - * Does nothing if no timeStamp. + * Attaches a PVTimeStamp to the wrapped PVStructure. + * Does nothing if no timeStamp field. + * @param pvTimeStamp the PVTimeStamp that will be attached. * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. */ bool attachTimeStamp(epics::pvData::PVTimeStamp &pvTimeStamp) const; /** - * Attach an pvAlarm. - * @param pvAlarm The pvAlarm that will be attached. - * Does nothing if no alarm. - * @return true if the operation was successfull (i.e. this instance has a timeStamp field), otherwise false. + * Attaches a PVAlarm to the wrapped PVStructure. + * Does nothing if no alarm field. + * @param pvAlarm the PVAlarm that will be attached. + * @return true if the operation was successfull (i.e. this instance has an alarm field), otherwise false. */ bool attachAlarm(epics::pvData::PVAlarm &pvAlarm) const; /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the descriptor field. - * @return The pvString or null if no function field. + * Returns the descriptor field. + * @return the descriptor field or null if no descriptor field. */ epics::pvData::PVStringPtr getDescriptor() const; /** - * Get the timeStamp. - * @return PVStructurePtr which may be null. + * Returns the timeStamp field. + * @return the timStamp field or null if no timeStamp field. */ epics::pvData::PVStructurePtr getTimeStamp() const; /** - * Get the alarm. - * @return PVStructurePtr which may be null. + * Returns the alarm field. + * @return the alarm field or null if no alarm field. */ epics::pvData::PVStructurePtr getAlarm() const; /** - * Get the value field. - * @return The PVUnion for the values. + * Returns the value field. + * @return the value field. */ epics::pvData::PVUnionPtr getValue() const; diff --git a/src/nt/nturi.h b/src/nt/nturi.h index 90356c4..038fca9 100644 --- a/src/nt/nturi.h +++ b/src/nt/nturi.h @@ -45,13 +45,13 @@ namespace detail { POINTER_DEFINITIONS(NTURIBuilder); /** - * Add authority field to the NTURI. + * Adds authority field to the NTURI. * @return this instance of NTURIBuilder. */ shared_pointer addAuthority(); /** - * Add extra Scalar of ScalarType pvString + * Adds extra Scalar of ScalarType pvString * to the query field of the type. * @param name name of the field. * @return this instance of NTURIBuilder. @@ -59,7 +59,7 @@ namespace detail { shared_pointer addQueryString(std::string const & name); /** - * Add extra Scalar of ScalarType pvDouble + * Adds extra Scalar of ScalarType pvDouble * to the query field of the type. * @param name name of the field. * @return this instance of NTURIBuilder. @@ -67,7 +67,7 @@ namespace detail { shared_pointer addQueryDouble(std::string const & name); /** - * Add extra Scalar of ScalarType pvInt + * Adds extra Scalar of ScalarType pvInt * to the query field of the type. * @param name name of the field. * @return this instance of NTURIBuilder. @@ -75,14 +75,14 @@ namespace detail { shared_pointer addQueryInt(std::string const & name); /** - * Create a Structure that represents NTURI. + * Creates a Structure that represents NTURI. * This resets this instance state and allows new instance to be created. * @return a new instance of Structure. */ epics::pvData::StructureConstPtr createStructure(); /** - * Create a PVStructure that represents NTURI. + * Creates a PVStructure that represents NTURI. * The returned PVStructure will have labels equal to the column names. * This resets this instance state and allows new instance to be created. * @return a new instance of PVStructure. @@ -90,17 +90,18 @@ namespace detail { epics::pvData::PVStructurePtr createPVStructure(); /** - * Create a NTURI instance. + * Creates a NTURI instance. * The returned NTURI will wrap a PVStructure which will have * labels equal to the column names. * This resets this instance state and allows new instance to be created. * @return a new instance of NTURI. */ NTURIPtr create(); + /** - * Add extra Field to the type. - * @param name name of the field. - * @param field a field to add. + * Adds extra Field to the type. + * @param name the name of the field. + * @param field the field to be added. * @return this instance of NTURIBuilder. */ shared_pointer add(std::string const & name, epics::pvData::FieldConstPtr const & field); @@ -141,65 +142,91 @@ public: static const std::string URI; /** - * Wrap (aka dynamic cast, or wrap) the structure to NTURI. - * First isCompatible is called. - * This method will nullptr if the structure is is not compatible. - * This method will nullptr if the structure is nullptr. - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTURI. - * @return NTURI instance on success, nullptr otherwise. + * Creates an NTURI wrapping the specified PVStructure if the latter is compatible. + *

+ * Checks the supplied PVStructure is compatible with NTURI + * and if so returns an NTURI which wraps it. + * This method will return null if the structure is is not compatible + * or is null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTURI instance wrapping pvStructure on success, null otherwise */ - static shared_pointer wrap(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrap(epics::pvData::PVStructurePtr const & pvStructure); /** - * Wrap (aka dynamic cast, or wrap) the structure to NTMultiChannel without checking for isCompatible - * @param structure The structure to wrap-ed (dynamic cast, wrapped) to NTURI. - * @return NTURI instance. + * Creates an NTScalar wrapping the specified PVStructure, regardless of the latter's compatibility. + *

+ * No checks are made as to whether the specified PVStructure + * is compatible with NTScalar or is non-null. + * + * @param pvStructure the PVStructure to be wrapped + * @return NTScalar instance wrapping pvStructure */ - static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & structure); + static shared_pointer wrapUnsafe(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the structure an NTURI. - * @param structure The structure to test. - * @return (false,true) if (is not, is) an NTURI. + * Returns whether the specified Structure reports to be a compatible NTScalar. + *

+ * Checks if the specified Structure reports compatibility with this + * version of NTScalar through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param structure the Structure to test + * @return (false,true) if (is not, is) a compatible NTScalar */ static bool is_a(epics::pvData::StructureConstPtr const & structure); /** - * Is the structure an NTURI. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTURI. + * Returns whether the specified PVStructure reports to be a compatible NTURI. + *

+ * Checks if the specified PVStructure reports compatibility with this + * version of NTURI through its type ID, including checking version numbers. + * The return value does not depend on whether the structure is actually + * compatible in terms of its introspection type. + * + * @param pvStructure the PVStructure to test. + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTURI. */ static bool is_a(epics::pvData::PVStructurePtr const & pvStructure); /** - * Is the Structure compatible with NTURI. - * This method introspects the fields to see if they are compatible. - * @param structure The Structure to test. - * @return (false,true) if (is not, is) an NTURI. + * Returns whether the specified Structure is compatible with NTURI. + *

+ * Checks if the specified Structure is compatible with this version + * of NTURI through the introspection interface. + * + * @param structure the Structure to test + * @return (false,true) if the specified Structure (is not, is) a compatible NTURI */ static bool isCompatible( epics::pvData::StructureConstPtr const &structure); /** - * Is the PVStructure compatible with NTURI. - * This method introspects the fields to see if they are compatible. - * @param pvStructure The PVStructure to test. - * @return (false,true) if (is not, is) an NTURI. + * Returns whether the specified PVStructure is compatible with NTURI. + *

+ * Checks if the specified PVStructure is compatible with this version + * of NTURI through the introspection interface. + * + * @param pvStructure the PVStructure to test + * @return (false,true) if the specified PVStructure (is not, is) a compatible NTURI */ static bool isCompatible( epics::pvData::PVStructurePtr const &pvStructure); /** - * Checks if the specified structure is a valid NTURI. + * Returns whether the wrapped PVStructure is a valid NTURI. + *

+ * Unlike isCompatible(), isValid() may perform checks on the value + * data as well as the introspection data. * - * Checks whether the wrapped structure is valid with respect to this - * version of NTURI - * @return (false,true) if (is not, is) a valid NTURI. + * @return (false,true) if wrapped PVStructure (is not, is) a valid NTURI. */ bool isValid(); /** - * Create a NTURI builder instance. + * Creates an NTURI builder instance. * @return builder instance. */ static NTURIBuilderPtr createBuilder(); @@ -210,37 +237,37 @@ public: ~NTURI() {} /** - * Get the pvStructure. - * @return PVStructurePtr. + * Returns the PVStructure wrapped by this instance. + * @return the PVStructure wrapped by this instance. */ epics::pvData::PVStructurePtr getPVStructure() const; /** - * Get the scheme field. - * @return The PVString for the scheme. + * Returns the scheme field. + * @return the scheme field. */ epics::pvData::PVStringPtr getScheme() const; /** - * Get the authority field. - * @return The PVString for the authority. + * Returns the authority field. + * @return the authority field if no such field. */ epics::pvData::PVStringPtr getAuthority() const; /** - * Get the path field. - * @return The PVString for the path. + * Returns the path field. + * @return the path field. */ epics::pvData::PVStringPtr getPath() const; /** - * Get the query field. - * @return The PVStructure for the query. + * Returns the query field. + * @return the query field if no such field. */ epics::pvData::PVStructurePtr getQuery() const; /** - * Get the names of the query fields for the URI. + * Returns the names of the query fields for the URI. * For each name, calling getQueryField should return * the query field, which should not be null. * @return The query field names. @@ -248,21 +275,25 @@ public: epics::pvData::StringArray const & getQueryNames() const; /** - * Get the PVField (column) for a field that follows the label field. - * @param columnName The name of the column. - * @return The PVFieldPtr for the field. + * Returns the subfield of the query field with the specified name. + * @param name the name of the subfield. + * @return the the subfield of the query field or null if the field does not exist. */ - epics::pvData::PVFieldPtr getQueryField(std::string const & columnName) const; + epics::pvData::PVFieldPtr getQueryField(std::string const & name) const; /** - * Get the PVField (column) for a field that follows the label field of a specified type (e.g. PVDoubleArray). - * @param columnName The name of the column. - * @return The field. + * Returns the subfield of the query field (parameter) with the specified + * name and of a specified expected type (for example, PVString). + * @tparam PVT the expected type of the subfield which should be + * be PVStringArray, PVIntArray pr PVDoubleArray. + * @param name the subfield of the query field or null if the field does + * not exist or is not of the expected type. + * @return The PVT field. */ template - std::tr1::shared_ptr getQueryField(std::string const & columnName) const + std::tr1::shared_ptr getQueryField(std::string const & name) const { - epics::pvData::PVFieldPtr pvField = getQueryField(columnName); + epics::pvData::PVFieldPtr pvField = getQueryField(name); if (pvField.get()) return std::tr1::dynamic_pointer_cast(pvField); else diff --git a/src/nt/ntutils.h b/src/nt/ntutils.h index 1f28c91..34dc275 100644 --- a/src/nt/ntutils.h +++ b/src/nt/ntutils.h @@ -23,9 +23,9 @@ public: /** * Checks whether NT types are compatible by checking their IDs, * i.e. their names and major version must match. - * @param u1 the first uri. - * @param u2 the second uri. - * @return true of URIs are compatible, false otherwise. + * @param u1 the first URI. + * @param u2 the second URI. + * @return true if URIs are compatible, false otherwise. */ static bool is_a(const std::string &u1, const std::string &u2);