From 036186fc12486d5ace1a6c0d89a1deea2ea6ad89 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Mon, 14 Sep 2015 16:48:15 +0200 Subject: [PATCH 1/8] jenkins: adapt doc script to new CloudBees jenkins job --- jenkins/cloudbees_doc | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/jenkins/cloudbees_doc b/jenkins/cloudbees_doc index 7c4cfcc..7b77608 100644 --- a/jenkins/cloudbees_doc +++ b/jenkins/cloudbees_doc @@ -10,11 +10,10 @@ # All rights reserved. Use is subject to license terms. ########################################### -# Determine EPICS Base version +# Set EPICS Base version and upload target -DEFAULT_BASE=3.14.12.5 - -BASE=${1:-${DEFAULT_BASE}} +BASE=3.15.2 +PUBLISH=${1:-DONT} ########################################### # Fetch and unpack dependencies @@ -43,4 +42,10 @@ doxygen ########################################### # Publish -rsync -aqP --delete -e ssh documentation epics-jenkins@web.sourceforge.net:/home/project-web/epics-pvdata/htdocs/docbuild/pvDataCPP/tip +if [ "${PUBLISH}" != "DONT" ]; then + # Upload explicit dummy to ensure target directory exists + echo "Created by CloudBees Jenkins upload job. Should be deleted as part of the job." > DUMMY + rsync -q -e ssh DUMMY epics-jenkins@web.sourceforge.net:/home/project-web/epics-pvdata/htdocs/docbuild/pvDataCPP/${PUBLISH}/DUMMY + + rsync -aqP --delete -e ssh documentation epics-jenkins@web.sourceforge.net:/home/project-web/epics-pvdata/htdocs/docbuild/pvDataCPP/${PUBLISH}/ +fi From 8c5f535b790a88f560e968aafeac4f2970612503 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Mon, 28 Sep 2015 15:29:17 +0200 Subject: [PATCH 2/8] jenkins: fix CloudBees doc job --- jenkins/cloudbees_doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jenkins/cloudbees_doc b/jenkins/cloudbees_doc index 7b77608..2ade4bf 100644 --- a/jenkins/cloudbees_doc +++ b/jenkins/cloudbees_doc @@ -45,7 +45,7 @@ doxygen if [ "${PUBLISH}" != "DONT" ]; then # Upload explicit dummy to ensure target directory exists echo "Created by CloudBees Jenkins upload job. Should be deleted as part of the job." > DUMMY - rsync -q -e ssh DUMMY epics-jenkins@web.sourceforge.net:/home/project-web/epics-pvdata/htdocs/docbuild/pvDataCPP/${PUBLISH}/DUMMY + rsync -q -e ssh DUMMY epics-jenkins@web.sourceforge.net:/home/project-web/epics-pvdata/htdocs/docbuild/pvDataCPP/${PUBLISH}/ rsync -aqP --delete -e ssh documentation epics-jenkins@web.sourceforge.net:/home/project-web/epics-pvdata/htdocs/docbuild/pvDataCPP/${PUBLISH}/ fi From 6515de4bc0f930497b6d5fe63f14c0829b537186 Mon Sep 17 00:00:00 2001 From: Dave Hickin Date: Thu, 8 Oct 2015 15:24:14 +0100 Subject: [PATCH 3/8] Add release notes for 5.0 --- documentation/RELEASE_NOTES.html | 153 +++++++++++++++++++++++++------ documentation/RELEASE_NOTES.md | 107 ++++++++++++++++----- 2 files changed, 210 insertions(+), 50 deletions(-) diff --git a/documentation/RELEASE_NOTES.html b/documentation/RELEASE_NOTES.html index b1a8edb..192dee6 100644 --- a/documentation/RELEASE_NOTES.html +++ b/documentation/RELEASE_NOTES.html @@ -1,66 +1,142 @@ -

Release 4.1 IN DEVELOPMENT

+

Release 5.0

+

The main changes since release 4.0 are:

+
    +
  • Deprecated getXXXField() methods have been removed from PVStructure
  • Convert copy methods and equals operators (re)moved
  • Convert::copyUnion now always copies between subfields.
    • -
  • CreateRequest prevents a possible SEGFAULT.
    • -
  • New stream operators for Field and PVField are provided.
    • -
  • New method getAs that is like getSubField except that it throws exception
    • +
  • New method getSubFieldT, like getSubField except it throws an exception
    • +
  • findSubField method removed from PVStructure
    • +
  • New stream operators for Field and PVField are provided
    • +
  • New template versions of Structure::getField
    • +
  • Fixes for static initialisation order issues
    • +
  • CreateRequest prevents a possible SEGFAULT
+ +

Deprecated getXXXField methods have been removed from PVStructure

+ +

The following methods have been removed from PVStructure

+ +
    +
  • getBooleanField
    • +
  • getByteField, getShortField, getIntField, getLongField
    • +
  • getUByteField, getUShortField, getUIntField, getULongField
    • +
  • getStringField
    • +
  • getStructureField, getUnionField
    • +
  • getScalarArrayField, getStructureArrayField, getUnionArrayField
    • +
+ +

Use template getSubField instead, e.g. use

+ +
getSubField< PVInt >(fieldName)
+
+ +

in place of

+ +
getIntField(fieldName)
+
+

Convert copy methods and equals operators

+

Convert copy methods where moved and replaced with methods on PVField classes, i.e.

+ 
PVField::copy(const PVField& from)
+

Methods

+ 
PVField::copyUnchecked(const PVField& from)
-

where added to allow unchecked copies, to gain performance + +

were added to allow unchecked copies, to gain performance where checked are not needed (anymore).

+

In addition: - isCompatibleXXX methods were removed in favour of Field::operator==. - equals methods were remove in favour of PVField::operator==. - operator== methods where moved to pvIntrospect.h and pvData.h

+

Convert::copyUnion

+

Before this method, depending on types for to and from, -sometimes did a shallow cppy, i. e. just made to shared_ptr for to +sometimes did a shallow copy, i.e. just made to shared_ptr for to share the same data as from. Now it always copies between the subfield of to and from.

-

CreateRequest change

-

createRequest could cause a SEGFAULT if passed a bad argument. -This has been changed so the it returns a null pvStructure -and provies an error.

+ +

New method getSubFieldT, like getSubField except it throws an exception

+ +

PVStructure has a new template member

+ +
getSubFieldT(std::string const &fieldName)
+
+ +

that is like getSubField except that it throws a runtime_error +instead of returning null.

+ +

findSubField method removed from PVStructure

+ +

This was mainly used in the implementation of getSubField. With a change to +the latter, findSubField was removed.

+

New stream operators

+

New steam operators are available for Field and PVField. Before to print a Field (or any extension) or a PVField (or any extension) it was necessary to have code like:

-
 void print(StructureConstPtr struct, PVStructurePtr pv)
+
+
 void print(StructureConstPtr struc, PVStructurePtr pv)
  {
-     if(struct) {
-         cout << *struct << endl;
+     if(struc) {
+         cout << *struc << endl;
      } else {
          cout << "nullptr\n"
      }
      if(pv) {
-         cout << *.struct << endl;
+         cout << *.struc << endl;
      } else {
          cout << "nullptr\n"
      }
  }
 

+
 
Now it can be done as follows:

-
 void print(StructureConstPtr struct, PVStructurePtr pv)
+
+
 void print(StructureConstPtr struc, PVStructurePtr pv)
  {
-     cout << struct << endl;
+     cout << struc << endl;
      cout << pv << endl;
  }
 

-
New method getAs that is like getSubField except that it throws exception

-
PVStructure has a new template member getAs(const char *name)
-that is like getSubField except that it throws a runtime_error
-instead of returning null.

+
+
New template version of Structure::getField

+
+
A new template getField method has been added to Structure

+
+
template
+std::tr1::shared_ptr< const FT > getField(std::string const &fieldName) const 

+
+
Can be used, for example, as follows:

+
+
StructurePtr tsStruc = struc->getField<Structure>("timeStamp");
+

+
+
Fixes for static initialisation order issues

+
+
Certain static builds (in particular Windows builds) of applications using
+pvData had issues due to PVStructure::DEFAULT_ID being used before being initialised. This has been fixed.

+
+
CreateRequest change

+
+
createRequest could cause a SEGFAULT if passed a bad argument.
+This has been changed so the it returns a null pvStructure
+and provides an error.

+
 
Release 4.0

+
 
The main changes since release 3.0.2 are:

+
 
    
 
  • array semantics now enforce Copy On Write.
    • 
 
  • String no longer defined.
    • 
@@ -70,21 +146,31 @@ instead of returning null.
    
 
  • copy is new.
    • 
 
  • monitorPlugin is new.
    • 
 

+
 
New Semantics for Arrays

+
 
PVScalarArray, PVStructureArray, and PVUnionArray all enforce COW (Copy On Write) Semantics.
-In order to limit memory usage the storage for raw data is managed via a new shared_vector facility.
+In order to limit memory usage the storage for raw data is managed via a new sharedvector facility.
 This allows multiple instances of array data to use the shared raw data.
-COW is implemented via shared_vectors of const data, i. e. data that can not be modified.

+COW is implemented via sharedvectors of const data, i. e. data that can not be modified.

+
 
String no longer defined

+
 
This is replaced by std::string.

+
 
timeStamp and valueAlarm name changes

+
 
In timeStamp nanoSeconds is changed to nanoseconds.

-
In valueAlarm hystersis is changed to hysteresis

+
+
In valueAlarm hysteresis is changed to hysteresis

+
 
toString replaced by stream I/O

+
 
pvData.h and pvIntrospect no longer defines toString
 Instead they have stream support.
 pvIntrospect uses method dump and pvData uses dumpValue.
 For example:

+
 
  PVDoublePtr pvValue;
   String buffer;
   pvValue->toString(&buffer);
@@ -93,27 +179,40 @@ For example:

   pvValue->getField()->toString(&buffer);
   cout << buffer << evdl;
 

+
 
is replaced by

+
 
  PVDoublePtr pvValue;
   cout << *pvValue << endl
   cout << *pvValue->getField() << endl;
 

+
 
union is a new basic type.

+
 
There are two new basic types: union_t and unionArray.

+
 
A union is like a structure that has a single subfield.
 There are two flavors:

+
 
    
-
  • varient union The field can have any type.
    • 
+
  • variant union The field can have any type.
    • 
 
  • union The field can any of specified set of types.
    • 
 

+
 
The field type can be dynamically changed.

-
copy

+
+
copy 

+
 
This consists of createRequest and pvCopy.
 createRequest was moved from pvAccess to here.
 pvCopy is moved from pvDatabaseCPP and now depends
-only on pvData, i. e. it no longer has any knowledge of PVRecord.

+only on pvData, i.e. it no longer has any knowledge of PVRecord.

+
 
monitorPlugin

+
 
This is for is for use by code that implements pvAccess monitors.
 This is prototype and is subject to debate.

+
 
Release 3.0.2

-
This was the starting point for RELEASE_NOTES

\ No newline at end of file
+
+
This was the starting point for RELEASE_NOTES

diff --git a/documentation/RELEASE_NOTES.md b/documentation/RELEASE_NOTES.md
index 2076f68..17784b7 100644
--- a/documentation/RELEASE_NOTES.md
+++ b/documentation/RELEASE_NOTES.md
@@ -1,13 +1,39 @@
-Release 4.1 IN DEVELOPMENT
+Release 5.0
 ===========
 
 The main changes since release 4.0 are:
 
+* Deprecated getXXXField() methods have been removed from PVStructure
 * Convert copy methods and equals operators (re)moved
 * Convert::copyUnion now always copies between subfields.
-* CreateRequest prevents a possible SEGFAULT.
-* New stream operators for Field and PVField are provided.
-* New method getSubFieldT that is like getSubField except that it throws exception
+* New method getSubFieldT, like getSubField except it throws an exception
+* findSubField method removed from PVStructure
+* New stream operators for Field and PVField are provided
+* New template versions of Structure::getField
+* Fixes for static initialisation order issues
+* CreateRequest prevents a possible SEGFAULT
+
+
+Deprecated getXXXField methods have been removed from PVStructure
+-------------------------------------------------------------------
+
+The following methods have been removed from PVStructure
+
+* getBooleanField
+* getByteField, getShortField, getIntField, getLongField
+* getUByteField, getUShortField, getUIntField, getULongField
+* getStringField
+* getStructureField, getUnionField
+* getScalarArrayField, getStructureArrayField, getUnionArrayField
+
+Use template getSubField instead, e.g. use
+
+    getSubField< PVInt >(fieldName)
+
+in place of
+
+    getIntField(fieldName)
+
 
 Convert copy methods and equals operators
 -----------------------------------------
@@ -21,7 +47,7 @@ Methods
 
     PVField::copyUnchecked(const PVField& from)
 
-where added to allow unchecked copies, to gain performance
+were added to allow unchecked copies, to gain performance
 where checked are not needed (anymore).
 
 In addition:
@@ -29,20 +55,33 @@ In addition:
 - equals methods were remove in favour of PVField::operator==.
 - operator== methods where moved to pvIntrospect.h and pvData.h
 
+
 Convert::copyUnion
 -----------------
 
 Before this method, depending on types for to and from,
-sometimes did a shallow cppy, i. e. just made to shared_ptr for to 
+sometimes did a shallow copy, i.e. just made to shared_ptr for to 
 share the same data as from.
 Now it always copies between the subfield of to and from.
 
-CreateRequest change
+
+New method getSubFieldT, like getSubField except it throws an exception
 --------------------
 
-createRequest could cause a SEGFAULT if passed a bad argument.
-This has been changed so the it returns a null pvStructure
-and provies an error.
+PVStructure has a new template member
+
+    getSubFieldT(std::string const &fieldName)
+
+that is like getSubField except that it throws a runtime_error
+instead of returning null.
+
+
+findSubField method removed from PVStructure
+--------------------------------------------
+
+This was mainly used in the implementation of getSubField. With a change to
+the latter, findSubField was removed.
+
 
 New stream operators
 --------------------
@@ -51,15 +90,15 @@ New steam operators are available for Field and PVField.
 Before to print a Field (or any extension) or a PVField (or any extension)
 it was necessary to have code like:
 
-     void print(StructureConstPtr struct, PVStructurePtr pv)
+     void print(StructureConstPtr struc, PVStructurePtr pv)
      {
-         if(struct) {
-             cout << *struct << endl;
+         if(struc) {
+             cout << *struc << endl;
          } else {
              cout << "nullptr\n"
          }
          if(pv) {
-             cout << *.struct << endl;
+             cout << *.struc << endl;
          } else {
              cout << "nullptr\n"
          }
@@ -67,18 +106,40 @@ it was necessary to have code like:
 
 Now it can be done as follows:
 
-     void print(StructureConstPtr struct, PVStructurePtr pv)
+     void print(StructureConstPtr struc, PVStructurePtr pv)
      {
-         cout << struct << endl;
+         cout << struc << endl;
          cout << pv << endl;
      }
 
-New method getSubFieldT that is like getSubField except that it throws exception
+
+New template version of Structure::getField
+--------------------------------------------
+
+A new template getField method has been added to Structure
+
+template
+std::tr1::shared_ptr< const FT > getField(std::string const &fieldName) const 
+
+Can be used, for example, as follows:
+
+    StructurePtr tsStruc = struc->getField("timeStamp");
+
+
+Fixes for static initialisation order issues
+--------------------------------------------
+
+Certain static builds (in particular Windows builds) of applications using
+pvData had issues due to PVStructure::DEFAULT_ID being used before being initialised. This has been fixed.
+
+
+CreateRequest change
 --------------------
 
-PVStructure has a new template member getSubFieldT(std::string const &fieldName)
-that is like getSubField except that it throws a runtime_error
-instead of returning null.
+createRequest could cause a SEGFAULT if passed a bad argument.
+This has been changed so the it returns a null pvStructure
+and provides an error.
+
 
 Release 4.0
 ===========
@@ -113,7 +174,7 @@ timeStamp and valueAlarm name changes
 
 In timeStamp nanoSeconds is changed to nanoseconds.
 
-In valueAlarm hystersis is changed to hysteresis
+In valueAlarm hysteresis is changed to hysteresis
 
 
 toString replaced by stream I/O
@@ -147,7 +208,7 @@ There are two new basic types: union_t and unionArray.
 A union is like a structure that has a single subfield.
 There are two flavors:
 
-* varient union The field can have any type.
+* variant union The field can have any type.
 * union The field can any of specified set of types.
 
 The field type can be dynamically changed.
@@ -158,7 +219,7 @@ copy
 This consists of createRequest and pvCopy.
 createRequest was moved from pvAccess to here.
 pvCopy is moved from pvDatabaseCPP and now depends
-only on pvData, i. e. it no longer has any knowledge of PVRecord.
+only on pvData, i.e. it no longer has any knowledge of PVRecord.
 
 monitorPlugin
 -------------

From 8008823ea5d3ea28944e1bfe87ed941e5b08f6cf Mon Sep 17 00:00:00 2001
From: Dave Hickin 
Date: Wed, 14 Oct 2015 23:01:28 +0100
Subject: [PATCH 4/8] Fix doxygen warnings

---
 src/copy/createRequest.h    |  1 -
 src/copy/pvCopy.h           |  6 +++---
 src/misc/byteBuffer.h       | 14 +++++++-------
 src/misc/serialize.h        |  3 +--
 src/misc/timer.h            |  2 +-
 src/monitor/monitorPlugin.h |  3 ---
 src/property/timeStamp.h    |  4 ++--
 src/pv/convert.h            |  4 ++--
 src/pv/pvData.h             | 34 ++++++++++++++++------------------
 src/pv/pvIntrospect.h       | 34 ++++++++++++++++------------------
 src/pv/pvSubArrayCopy.h     |  6 +++---
 src/pv/standardField.h      |  8 ++++----
 src/pv/standardPVField.h    |  6 +++---
 13 files changed, 58 insertions(+), 67 deletions(-)

diff --git a/src/copy/createRequest.h b/src/copy/createRequest.h
index 0cab001..bc79de9 100644
--- a/src/copy/createRequest.h
+++ b/src/copy/createRequest.h
@@ -38,7 +38,6 @@ class epicsShareClass CreateRequest {
     * Create a request structure for the create calls in Channel.
     * See the package overview documentation for details.
     * @param request The field request. See the package overview documentation for details.
-    * @param requester The requester;
     * @return The request PVStructure if a valid request was given.
     * If a NULL PVStructure is returned then getMessage will return
     * the reason.
diff --git a/src/copy/pvCopy.h b/src/copy/pvCopy.h
index 6da7945..084bcf9 100644
--- a/src/copy/pvCopy.h
+++ b/src/copy/pvCopy.h
@@ -116,8 +116,8 @@ public:
         PVStructurePtr const  &masterPVStructure,
         PVFieldPtr const  &masterPVField);
     /**
-     * Given a offset in the copy get the corresponding field in pvMaster.
-     * @param offset The offset in the copy.
+     * Given an offset in the copy get the corresponding field in pvMaster.
+     * @param structureOffset The offset in the copy.
      */
     PVFieldPtr getMasterPVField(std::size_t structureOffset);
     /**
@@ -159,7 +159,7 @@ public:
         BitSetPtr const  &bitSet);
     /**
      * Get the options for the field at the specified offset.
-     * @param offset the offset in copy.
+     * @param fieldOffset the offset in copy.
      * @returns A NULL is returned if no options were specified for the field.
      * If options were specified,PVStructurePtr is a structures
      *  with a set of PVString subfields that specify name,value pairs.s
diff --git a/src/misc/byteBuffer.h b/src/misc/byteBuffer.h
index 16d314d..087a8c5 100644
--- a/src/misc/byteBuffer.h
+++ b/src/misc/byteBuffer.h
@@ -399,9 +399,9 @@ public:
      * Put a sub-array of bytes into the byte buffer.
      * The position is increased by the count.
      *
-     * @param  src    The source array.
-     * @param  offset The starting position within src.
-     * @param  count  The number of bytes to put into the byte buffer,
+     * @param  src        The source array.
+     * @param  src_offset The starting position within src.
+     * @param  count      The number of bytes to put into the byte buffer,
      */
     inline void put(const char* src, std::size_t src_offset, std::size_t count) {
         //if(count>getRemaining()) THROW_BASE_EXCEPTION("buffer overflow");
@@ -412,9 +412,9 @@ public:
      * Get a sub-array of bytes from the byte buffer.
      * The position is increased by the count.
      *
-     * @param  dest    The destination array.
-     * @param  offset The starting position within src.
-     * @param  count  The number of bytes to put into the byte buffer,
+     * @param  dest        The destination array.
+     * @param  dest_offset The starting position within src.
+     * @param  count       The number of bytes to put into the byte buffer.
      */
     inline void get(char* dest, std::size_t dest_offset, std::size_t count) {
         //if(count>getRemaining()) THROW_BASE_EXCEPTION("buffer overflow");
@@ -637,7 +637,7 @@ public:
     /**
      * Get a boolean value from the byte buffer at the specified index.
      *
-     * @param  double The offset in the byte buffer.
+     * @param  index The offset in the byte buffer.
      * @return The value.
      */
     inline double getDouble (std::size_t  index) { return get(index); }
diff --git a/src/misc/serialize.h b/src/misc/serialize.h
index 2c45a6e..db70a0d 100644
--- a/src/misc/serialize.h
+++ b/src/misc/serialize.h
@@ -118,7 +118,6 @@ namespace epics { namespace pvData {
             std::size_t elementSize) = 0;
         /**
          * deserialize via cache
-         * @param field instance to be deserialized
          * @param buffer buffer to be deserialized from
          */
         virtual std::tr1::shared_ptr cachedDeserialize(
@@ -196,7 +195,7 @@ namespace epics { namespace pvData {
          * Serialize field into given buffer.
          * @param buffer serialization buffer.
          * @param flusher flush interface.
-         * ¶m offset offset in elements.
+         * @param offset offset in elements.
          * @param count number of elements
          */
         virtual void serialize(
diff --git a/src/misc/timer.h b/src/misc/timer.h
index 9c1fc47..369519c 100644
--- a/src/misc/timer.h
+++ b/src/misc/timer.h
@@ -115,7 +115,7 @@ public:
     bool isScheduled(TimerCallbackPtr const &timerCallback);
     /**
      * show the elements in the timer queue.
-     * @parm o The output stream for the output
+     * @param o The output stream for the output
      */
     void dump(std::ostream& o);
 
diff --git a/src/monitor/monitorPlugin.h b/src/monitor/monitorPlugin.h
index 963767a..544e262 100644
--- a/src/monitor/monitorPlugin.h
+++ b/src/monitor/monitorPlugin.h
@@ -66,9 +66,6 @@ public:
         MonitorElementPtr const &monitorElement) = 0;
     /**
      * A monitor will be sent to the client.
-     * @param pvField The copy of the field being monitored.
-     * The plugin can modify the data.
-     * @param pvTop The top-level structure in which the field resides.
      * @param monitorElement The data for the client.
      * The plugin is allowed to change the data values.
      */
diff --git a/src/property/timeStamp.h b/src/property/timeStamp.h
index 3696229..2f018f9 100644
--- a/src/property/timeStamp.h
+++ b/src/property/timeStamp.h
@@ -107,7 +107,7 @@ public:
     int32 getUserTag() const {return userTag;}
     /**
      * Set userTag.
-     * @param useTag application specific.
+     * @param userTag application specific.
      */
     void setUserTag(int userTag) {this->userTag = userTag;}
     /**
@@ -162,7 +162,7 @@ public:
     /**
      * Return a-b as a  double value with units of seconds.
      * @param a first timeStamp
-     * @param n second timeStamp
+     * @param b second timeStamp
      * @return time difference in seconds.
      */
     static double diff(TimeStamp const & a,TimeStamp const & b);
diff --git a/src/pv/convert.h b/src/pv/convert.h
index b497caa..39a2827 100644
--- a/src/pv/convert.h
+++ b/src/pv/convert.h
@@ -57,7 +57,7 @@ public:
      * @param from The source.
      * @param to The destination
      * @throws std::invalid_argument if the arguments are not compatible.
-     * @DEPRECATED use "to->copy[Unchecked](*from)" instead
+     * @deprecated use "to->copy[Unchecked](*from)" instead
      */
     void copy(PVFieldPtr const & from, PVFieldPtr const & to) {
         to->copy(*from);
@@ -144,7 +144,7 @@ public:
         StringArray & to,
         std::size_t toOffset);
     /**
-     * Convert a PV to a .
+     * Convert a PV to a byte.
      * @param pv a PV
      * @return converted value
      */
diff --git a/src/pv/pvData.h b/src/pv/pvData.h
index 73f0851..1546a07 100644
--- a/src/pv/pvData.h
+++ b/src/pv/pvData.h
@@ -363,7 +363,7 @@ public:
     virtual T get() const = 0;
     /**
      * Put a new value into the PVScalar.
-     * @param The value.
+     * @param value The value.
      */
     virtual void put(T value) = 0;
 
@@ -515,7 +515,7 @@ public:
     virtual std::size_t getLength() const = 0;
     /**
      * Set the array length.
-     * @param The length.
+     * @param length The length.
      */
     virtual void setLength(std::size_t length) = 0;
     /**
@@ -535,7 +535,7 @@ public:
     void setCapacityMutable(bool isMutable);
     /**
      * Set the array capacity.
-     * @param The capacity.
+     * @param capacity The capacity.
      */
     virtual void setCapacity(std::size_t capacity) = 0;
 
@@ -931,7 +931,7 @@ public:
      * Select field (set index) and get the field at the index.
      * @param index index of the field to select.
      * @return corresponding PVField (of undetermined value), {@code null} if {@code index == UNDEFINED_INDEX}.
-     * @throws {@code std::invalid_argument} if index is invalid (out of range).
+     * @throws std::invalid_argument if index is invalid (out of range).
      */
     PVFieldPtr select(int32 index);
 
@@ -944,7 +944,7 @@ public:
      * Select field (set index) and get the field by given name.
      * @param fieldName the name of the field to select.
      * @return corresponding PVField (of undetermined value).
-     * @throws {@code std::invalid_argument} if field does not exist.
+     * @throws std::invalid_argument if field does not exist.
      */
     PVFieldPtr select(std::string const & fieldName);
 
@@ -974,19 +974,19 @@ public:
     /**
      * Set the {@code PVField} (by reference!) as field at given index.
      * If a value is not a valid union field an {@code std::invalid_argument} exception is thrown.
-     * Use {@code select(int)} to put by value.
+     * Use {@code select(int32)} to put by value.
      * @param index index of a field to put.
      * @param value the field to set.
-     * @see #select(int)
+     * @see #select(int32)
      */
     void set(int32 index, PVFieldPtr const & value);
     /**
      * Set the {@code PVField} (by reference!) as field by given name.
      * If a value is not a valid union field an {@code std::invalid_argument} exception is thrown.
-     * Use {@code select(std::string)} to put by value.
+     * Use {@code select(std::string const &)} to put by value.
      * @param fieldName Name of the field to put.
      * @param value the field to set.
-     * @see #select(std::string)
+     * @see #select(std::string const &)
      */
     void set(std::string const & fieldName, PVFieldPtr const & value);
 
@@ -1447,7 +1447,7 @@ public:
     PVScalarPtr createPVScalar(ScalarConstPtr const & scalar);
     /**
      * Create an implementation of a scalar field. A Scalar introspection interface is created.
-     * @param fieldType The field type.
+     * @param scalarType The scalar type.
      * @return The PVScalar implementation.
      */
     PVScalarPtr createPVScalar(ScalarType scalarType);
@@ -1460,7 +1460,7 @@ public:
     PVScalarPtr createPVScalar(PVScalarPtr const & scalarToClone);
     /**
      * template version
-     * @param PVT must be a valid pvType
+     * @tparam PVT must be a valid PVType
      * @return The PVScalar implementation.
      */
     template
@@ -1492,7 +1492,7 @@ public:
 
     /**
      * Create implementation for PVUnion.
-     * @param union The introspection interface.
+     * @param punion The introspection interface.
      * @return The PVUnion implementation
      */
     PVUnionPtr createPVUnion(UnionConstPtr const & punion);
@@ -1510,13 +1510,12 @@ public:
 
     /**
      * Create an implementation of an array field reusing the Array introspection interface.
-     * @param array The introspection interface.
+     * @param scalarArray The introspection interface.
      * @return The PVScalarArray implementation.
      */
     PVScalarArrayPtr createPVScalarArray(ScalarArrayConstPtr const & scalarArray);
     /**
      * Create an implementation for an array field. An Array introspection interface is created.
-     * @param parent The parent interface.
      * @param elementType The element type.
      * @return The PVScalarArray implementation.
      */
@@ -1524,13 +1523,13 @@ public:
     /**
      * Create an implementation of an array field by cloning an existing PVArray.
      * The new PVArray will have the same value and auxInfo as the original.
-     * @param arrayToClone The PVScalarArray to clone.
+     * @param scalarArrayToClone The PVScalarArray to clone.
      * @return The PVScalarArray implementation.
      */
     PVScalarArrayPtr createPVScalarArray(PVScalarArrayPtr const  & scalarArrayToClone);
     /**
      * template version
-     * @param PVT must be a valid pvType
+     * @tparam PVT must be a valid pvType
      * @return The PVScalarArray implementation.
      */
     template
@@ -1587,9 +1586,8 @@ private:
 
 /**
  * Get the single class that implements PVDataCreate
- * @param The PVDataCreate factory.
+ * @return The PVDataCreate factory.
  */
-
 epicsShareExtern PVDataCreatePtr getPVDataCreate();
 
 bool epicsShareExtern operator==(const PVField&, const PVField&);
diff --git a/src/pv/pvIntrospect.h b/src/pv/pvIntrospect.h
index aaa8029..eb12dcc 100644
--- a/src/pv/pvIntrospect.h
+++ b/src/pv/pvIntrospect.h
@@ -318,7 +318,7 @@ public:
 protected:
     /**
      * Constructor
-     * @param  fieldName The field type.
+     * @param  type The field type.
      */
    Field(Type type);
 private:
@@ -433,7 +433,7 @@ public:
 protected:
     /**
      * Constructor
-     * @param  fieldName The field type.
+     * @param type The field type.
      */
    Array(Type type);
 
@@ -626,7 +626,7 @@ public:
 protected:
     /**
      * Constructor.
-     * @param union The introspection interface for the elements.
+     * @param _punion The introspection interface for the elements.
      */
     UnionArray(UnionConstPtr const & _punion);
     /**
@@ -689,7 +689,7 @@ public:
 
     /**
      * Get the field for the specified fieldName.
-     * @param fieldName The index of the field to get;
+     * @param index The index of the field to get;
      * @return The introspection interface.
      * This will hold a null pointer if the field is not in the structure.
      */
@@ -810,7 +810,7 @@ public:
 
     /**
      * Get the field for the specified fieldName.
-     * @param fieldName The index of the field to get;
+     * @param index The index of the field to get;
      * @return The introspection interface.
      * This will hold a null pointer if the field is not in the union.
      */
@@ -952,7 +952,7 @@ public:
     /**
      * Add array of {@code Field} elements.
      * @param name name of the array.
-     * @param field a type of an array element.
+     * @param element a type of an array element.
      * @return this instance of a {@code FieldBuilder}.
      */
     FieldBuilderPtr addArray(std::string const & name, FieldConstPtr const & element);
@@ -1013,8 +1013,8 @@ public:
 
     /**
      * Complete the creation of a nested object.
-     * @see #addNestedStructure(std::string)
-     * @see #addNestedUnion(std::string)
+     * @see #addNestedStructure(std::string const & name)
+     * @see #addNestedUnion(std::string const & name)
      * @return a previous (parent) {@code FieldBuilder}.
      */
     FieldBuilderPtr endNested();
@@ -1062,14 +1062,14 @@ public:
      * Create a {@code ScalarField}.
      * @param scalarType The scalar type.
      * @return a {@code Scalar} interface for the newly created object.
-     * @throws An {@code IllegalArgumentException} if an illegal type is specified.
+     * @throws IllegalArgumentException if an illegal type is specified.
      */
     ScalarConstPtr createScalar(ScalarType scalarType) const;
     /**
      * Create a {@code BoundedString}.
      * @param maxLength a string maximum length.
      * @return a {@code BoundedString} interface for the newly created object.
-     * @throws An {@code IllegalArgumentException} if maxLength == 0.
+     * @throws IllegalArgumentException if maxLength == 0.
      */
     BoundedStringConstPtr createBoundedString(std::size_t maxLength) const;
     /**
@@ -1088,14 +1088,13 @@ public:
     /**
      * Create an {@code Array} field, bounded size array.
      * @param elementType The {@code scalarType} for array elements
-     * @param size Array maximum capacity (bound).
+     * @param bound Array maximum capacity.
      * @return An {@code Array} Interface for the newly created object.
      */
      ScalarArrayConstPtr createBoundedScalarArray(ScalarType elementType, std::size_t bound) const;
      /**
       * Create an {@code Array} field that is has element type Structure
-      * @param fieldName The field name
-      * @param elementStructure The {@code Structure} for each array element.
+      * @param structure The {@code Structure} for each array element.
       * @return An {@code Array} Interface for the newly created object.
       */
     StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
@@ -1126,8 +1125,7 @@ public:
         FieldConstPtrArray const & fields) const;
      /**
       * Create an {@code Array} field that is has element type Union
-      * @param fieldName The field name
-      * @param elementUnion The {@code Union} for each array element.
+      * @param punion The {@code Union} for each array element.
       * @return An {@code Array} Interface for the newly created object.
       */
     UnionArrayConstPtr createUnionArray(UnionConstPtr const & punion) const;
@@ -1174,8 +1172,8 @@ public:
     /**
      * Append fields to a structure.
      * @param structure The structure to which the fields appended.
-     * @param fieldName The names of the fields.
-     * @param field The fields.
+     * @param fieldNames The names of the fields.
+     * @param fields The fields.
      * @return a {@code Structure} interface for the newly created object.
      */
     StructureConstPtr appendFields(
@@ -1201,7 +1199,7 @@ private:
 
 /**
  * Get the single class that implements FieldCreate,
- * @param The fieldCreate factory.
+ * @return The fieldCreate factory.
  */
 epicsShareExtern FieldCreatePtr getFieldCreate();
 
diff --git a/src/pv/pvSubArrayCopy.h b/src/pv/pvSubArrayCopy.h
index 04de8b6..eb3e2f3 100644
--- a/src/pv/pvSubArrayCopy.h
+++ b/src/pv/pvSubArrayCopy.h
@@ -71,7 +71,7 @@ epicsShareExtern void copy(
     PVStructureArray & pvFrom,
     size_t fromOffset,
     size_t fromStride,
-    PVStructureArray & pvToo,
+    PVStructureArray & pvTo,
     size_t toOffset,
     size_t toStride,
     size_t count);
@@ -91,7 +91,7 @@ epicsShareExtern void copy(
     PVArray & pvFrom,
     size_t fromOffset,
     size_t fromStride,
-    PVArray & pvToo,
+    PVArray & pvTo,
     size_t toOffset,
     size_t toStride,
     size_t count);
@@ -111,7 +111,7 @@ epicsShareExtern void copy(
     PVArray::shared_pointer const & pvFrom,
     size_t fromOffset,
     size_t fromStride,
-    PVArray::shared_pointer & pvToo,
+    PVArray::shared_pointer & pvTo,
     size_t toOffset,
     size_t toStride,
     size_t count);
diff --git a/src/pv/standardField.h b/src/pv/standardField.h
index 3388aac..0c2e669 100644
--- a/src/pv/standardField.h
+++ b/src/pv/standardField.h
@@ -93,14 +93,14 @@ public:
      */
     StructureConstPtr variantUnion(std::string const & properties);
     /** Create a structure that has a scalarArray value field.
-     * @param type The type.
+     * @param elementType The element type.
      * @param properties A comma separated list of properties.
      * This is some combination of "alarm,timeStamp,display,control,valueAlarm".
      * @return The const shared pointer to the structure.
      */
     StructureConstPtr scalarArray(ScalarType elementType, std::string const & properties);
     /** Create a structure that has a structureArray value field.
-     * @param type The type.
+     * @param structure The Structure introspection object for elements of the value field.
      * @param properties A comma separated list of properties.
      * This is some combination of "alarm,timeStamp,display,control,valueAlarm".
      * @return The const shared pointer to the structure.
@@ -109,7 +109,7 @@ public:
         StructureConstPtr const & structure,
         std::string const & properties);
     /** Create a structure that has a unionArray value field.
-     * @param type The type.
+     * @param punion The Union introspection object for elements of the value field.
      * @param properties A comma separated list of properties.
      * This is some combination of "alarm,timeStamp,display,control".
      * @return The const shared pointer to the structure.
@@ -118,7 +118,7 @@ public:
         UnionConstPtr const & punion,
         std::string const & properties);
     /** Create a structure that has an enumerated structure value field.
-     *  The id for the structure is "enum-t".
+     *  The id for the structure is "enum_t".
      * @return The const shared pointer to the structure.
      */
     StructureConstPtr enumerated();
diff --git a/src/pv/standardPVField.h b/src/pv/standardPVField.h
index 48c2542..aa68d14 100644
--- a/src/pv/standardPVField.h
+++ b/src/pv/standardPVField.h
@@ -54,7 +54,7 @@ public:
     PVStructurePtr scalar(ScalarType type,std::string const & properties);
     /**
      * Create a structure that has a scalar array value field.
-     * @param type The type.
+     * @param elementType The element scalar type.
      * @param properties A comma separated list of properties.
      * This is some combination of "alarm,timeStamp,display,control,valueAlarm".
      * @return The const shared pointer to the structure.
@@ -62,7 +62,7 @@ public:
     PVStructurePtr scalarArray(ScalarType elementType, std::string const & properties);
     /**
      * Create a structure that has a structure array value field.
-     * @param type The type.
+     * @param structure The Structure introspection object for elements of the value field.
      * @param properties A comma separated list of properties.
      * This is some combination of "alarm,timeStamp,display,control,valueAlarm".
      * @return The const shared pointer to the structure.
@@ -70,7 +70,7 @@ public:
     PVStructurePtr structureArray(StructureConstPtr const &structure,std::string const & properties);
     /**
      * Create a structure that has a union array value field.
-     * @param type The type.
+     * @param punion The Union introspection object for elements of the value field.
      * @param properties A comma separated list of properties.
      * This is some combination of "alarm,timeStamp,display,control,valueAlarm".
      * @return The const shared pointer to the structure.

From f5df29cf348238062947bc8e4b07adb604e943c3 Mon Sep 17 00:00:00 2001
From: Dave Hickin 
Date: Thu, 15 Oct 2015 06:50:26 +0100
Subject: [PATCH 5/8] Doxygen: remove @code when code block not wanted

@code produces a separate code block, rather than just displaying
contents as code.

Mostly replaced use with @c tag when block not wanted.
---
 src/misc/bitSet.h          |  81 +++++++++--------
 src/misc/byteBuffer.h      |  10 +--
 src/misc/serializeHelper.h |   2 +-
 src/pv/pvData.h            |  27 +++---
 src/pv/pvIntrospect.h      | 176 ++++++++++++++++++-------------------
 src/pv/pvType.h            |   2 +-
 6 files changed, 150 insertions(+), 148 deletions(-)

diff --git a/src/misc/bitSet.h b/src/misc/bitSet.h
index 6a61e9e..fb184c8 100644
--- a/src/misc/bitSet.h
+++ b/src/misc/bitSet.h
@@ -27,15 +27,15 @@ namespace epics { namespace pvData {
      * @brief A vector of bits.
      *
      * This class implements a vector of bits that grows as needed. Each
-     * component of the bit set has a {@code bool} value. The
-     * bits of a {@code BitSet} are indexed by nonnegative integers.
-     * Individual indexed bits can be examined, set, or cleared. One
-     * {@code BitSet} may be used to modify the contents of another
-     * {@code BitSet} through logical AND, logical inclusive OR, and
-     * logical exclusive OR operations.
+     * component of the bit set has a @c bool value. The bits of a
+     * @c BitSet are indexed by nonnegative integers. Individual
+     * indexed bits can be examined, set, or cleared. One @c BitSet may
+     * be used to modify the contents of another @c BitSet through
+     * logical AND, logical inclusive OR, and logical exclusive OR
+     * operations.
      *
      * 
By default, all bits in the set initially have the value
-     * {@code false}.
+     * @c false.
      *
      * 
Every bit set has a current size, which is the number of bits
      * of space currently in use by the bit set. Note that the size is
@@ -43,8 +43,8 @@ namespace epics { namespace pvData {
      * implementation. The length of a bit set relates to logical length
      * of a bit set and is defined independently of implementation.
      *
-     * 
A {@code BitSet} is not safe for multithreaded use without
-     * external synchronization.
+     * 
A @c BitSet is not safe for multithreaded use without external
+     * synchronization.
      *
      * Based on Java implementation.
      */
@@ -53,14 +53,14 @@ namespace epics { namespace pvData {
         POINTER_DEFINITIONS(BitSet);
         static BitSetPtr create(uint32 nbits);
         /**
-         * Creates a new bit set. All bits are initially {@code false}.
+         * Creates a new bit set. All bits are initially @c false.
          */
         BitSet();
 
         /**
          * Creates a bit set whose initial size is large enough to explicitly
-         * represent bits with indices in the range {@code 0} through
-         * {@code nbits-1}. All bits are initially {@code false}.
+         * represent bits with indices in the range @c 0 through
+         * @c nbits-1. All bits are initially @c false.
          *
          * @param  nbits the initial size of the bit set
          */
@@ -80,14 +80,14 @@ namespace epics { namespace pvData {
         void flip(uint32 bitIndex);
 
         /**
-         * Sets the bit at the specified index to {@code true}.
+         * Sets the bit at the specified index to @c true.
          *
          * @param  bitIndex a bit index
          */
         void set(uint32 bitIndex);
 
         /**
-         * Sets the bit specified by the index to {@code false}.
+         * Sets the bit specified by the index to @c false.
          *
          * @param  bitIndex the index of the bit to be cleared
          */
@@ -103,9 +103,8 @@ namespace epics { namespace pvData {
 
         /**
          * Returns the value of the bit with the specified index. The value
-         * is {@code true} if the bit with the index {@code bitIndex}
-         * is currently set in this {@code BitSet}; otherwise, the result
-         * is {@code false}.
+         * is @c true if the bit with the index @c bitIndex is currently
+         * set in this @c BitSet; otherwise, the result is @c false.
          *
          * @param  bitIndex   the bit index
          * @return the value of the bit with the specified index
@@ -113,16 +112,16 @@ namespace epics { namespace pvData {
         bool get(uint32 bitIndex) const;
 
         /**
-         * Sets all of the bits in this BitSet to {@code false}.
+         * Sets all of the bits in this BitSet to @c false.
          */
         void clear();
 
         /**
-         * Returns the index of the first bit that is set to {@code true}
-         * that occurs on or after the specified starting index. If no such
-         * bit exists then {@code -1} is returned.
+         * Returns the index of the first bit that is set to @c true that
+         * occurs on or after the specified starting index. If no such bit
+         * exists then @c -1 is returned.
          *
-         * 
To iterate over the {@code true} bits in a {@code BitSet},
+         * 
To iterate over the @c true bits in a @c BitSet,
          * use the following loop:
          *
          *  
 {@code
@@ -131,13 +130,13 @@ namespace epics { namespace pvData {
          * }}

          *
          * @param  fromIndex the index to start checking from (inclusive)
-         * @return the index of the next set bit, or {@code -1} if there
+         * @return the index of the next set bit, or @c -1 if there
          *         is no such bit
          */
         int32 nextSetBit(uint32 fromIndex) const;
 
         /**
-         * Returns the index of the first bit that is set to {@code false}
+         * Returns the index of the first bit that is set to @c false
          * that occurs on or after the specified starting index.
          *
          * @param  fromIndex the index to start checking from (inclusive)
@@ -146,23 +145,23 @@ namespace epics { namespace pvData {
         int32 nextClearBit(uint32 fromIndex) const;
 
         /**
-         * Returns true if this {@code BitSet} contains no bits that are set
-         * to {@code true}.
+         * Returns true if this @c BitSet contains no bits that are set
+         * to @c true.
          *
-         * @return indicating whether this {@code BitSet} is empty
+         * @return indicating whether this @c BitSet is empty
          */
         bool isEmpty() const;
 
         /**
-         * Returns the number of bits set to {@code true} in this {@code BitSet}.
+         * Returns the number of bits set to @c true in this @c BitSet.
          *
-         * @return the number of bits set to {@code true} in this {@code BitSet}
+         * @return the number of bits set to @c true in this @c BitSet
          */
         uint32 cardinality() const;
 
         /**
          * Returns the number of bits of space actually in use by this
-         * {@code BitSet} to represent bit values.
+         * @c BitSet to represent bit values.
          * The maximum element in the set is the size - 1st element.
          *
          * @return the number of bits currently in this bit set
@@ -172,9 +171,9 @@ namespace epics { namespace pvData {
         /**
          * Performs a logical AND of this target bit set with the
          * argument bit set. This bit set is modified so that each bit in it
-         * has the value {@code true} if and only if it both initially
-         * had the value {@code true} and the corresponding bit in the
-         * bit set argument also had the value {@code true}.
+         * has the value @c true if and only if it both initially
+         * had the value @c true and the corresponding bit in the
+         * bit set argument also had the value @c true.
          *
          * @param set a bit set
          */
@@ -183,9 +182,9 @@ namespace epics { namespace pvData {
         /**
          * Performs a logical OR of this bit set with the bit set
          * argument. This bit set is modified so that a bit in it has the
-         * value {@code true} if and only if it either already had the
-         * value {@code true} or the corresponding bit in the bit set
-         * argument has the value {@code true}.
+         * value @c true if and only if it either already had the
+         * value @c true or the corresponding bit in the bit set
+         * argument has the value @c true.
          *
          * @param set a bit set
          */
@@ -194,13 +193,13 @@ namespace epics { namespace pvData {
         /**
          * Performs a logical XOR of this bit set with the bit set
          * argument. This bit set is modified so that a bit in it has the
-         * value {@code true} if and only if one of the following
+         * value @c true if and only if one of the following
          * statements holds:
          * 
    
-         * 
  • The bit initially has the value {@code true}, and the
-         *     corresponding bit in the argument has the value {@code false}.
-         * 
  • The bit initially has the value {@code false}, and the
-         *     corresponding bit in the argument has the value {@code true}.
+         * 
  • The bit initially has the value @c true, and the
+         *     corresponding bit in the argument has the value @c false.
+         * 
  • The bit initially has the value @c false, and the
+         *     corresponding bit in the argument has the value @c true.
          * 

          *
          * @param  set a bit set
diff --git a/src/misc/byteBuffer.h b/src/misc/byteBuffer.h
index 087a8c5..2f1013b 100644
--- a/src/misc/byteBuffer.h
+++ b/src/misc/byteBuffer.h
@@ -208,7 +208,7 @@ inline double swap(double val)
 /**
  * @brief This class implements a Bytebuffer that is like the java.nio.ByteBuffer.
  * 
- * 
A {@code BitSet} is not safe for multithreaded use without
+ * 
A @c BitSet is not safe for multithreaded use without
  * external synchronization.
  *
  * Based on Java implementation.
@@ -373,7 +373,7 @@ public:
     template
     inline void put(std::size_t index, T value);
     /**
-     * Get the new object from  the byte buffer. The item MUST have type {@code T}.
+     * Get the new object from  the byte buffer. The item MUST have type @c T.
      * The position is adjusted based on the type.
      *
      * @return The object.
@@ -387,7 +387,7 @@ public:
 #endif
     /**
      * Get the new object from  the byte buffer at the specified index.
-     * The item MUST have type {@code T}.
+     * The item MUST have type @c T.
      * The position is adjusted based on the type.
      *
      * @param index The location in the byte buffer.
@@ -422,7 +422,7 @@ public:
         _position += count;
     }
     /**
-     * Put an array of type {@code T} into the byte buffer.
+     * Put an array of type @c T into the byte buffer.
      * The position is adjusted.
      *
      * @param  values The input array.
@@ -431,7 +431,7 @@ public:
     template
     inline void putArray(const T* values, std::size_t count);
     /**
-     * Get an array of type {@code T} from the byte buffer.
+     * Get an array of type @c T from the byte buffer.
      * The position is adjusted.
      *
      * @param  values The destination array.
diff --git a/src/misc/serializeHelper.h b/src/misc/serializeHelper.h
index 4c67b20..d741fb0 100644
--- a/src/misc/serializeHelper.h
+++ b/src/misc/serializeHelper.h
@@ -63,7 +63,7 @@ namespace epics {
              * std::string serialization helper method.
              *
              * @param[in] value std::string to serialize
-             * @param[in] offset start of the substring in {@code value}
+             * @param[in] offset start of the substring in value
              * @param[in] count the number of characters to write
              * @param[in] buffer serialization buffer
              * @param[in] flusher flusher
diff --git a/src/pv/pvData.h b/src/pv/pvData.h
index 1546a07..d68eb04 100644
--- a/src/pv/pvData.h
+++ b/src/pv/pvData.h
@@ -906,7 +906,7 @@ public:
 	/**
 	 * Undefined index.
 	 * Default value upon PVUnion construction. Can be set by the user.
-	 * Corresponds to {@code null} value.
+	 * Corresponds to @c null value.
 	 */
 	static int32 UNDEFINED_INDEX;
 
@@ -917,8 +917,8 @@ public:
     UnionConstPtr getUnion() const;
 
     /**
-     * Get the {@code PVField} value stored in the field.
-     * @return {@code PVField} value of field, {@code null} if {@code getSelectedIndex() == UNDEFINED_INDEX}.
+     * Get the @c PVField value stored in the field.
+     * @return @c PVField value of field, @c null if {@code getSelectedIndex() == UNDEFINED_INDEX}.
      */
     PVFieldPtr get() const;
    
@@ -930,7 +930,7 @@ public:
     /**
      * Select field (set index) and get the field at the index.
      * @param index index of the field to select.
-     * @return corresponding PVField (of undetermined value), {@code null} if {@code index == UNDEFINED_INDEX}.
+     * @return corresponding PVField (of undetermined value), @c null if {@code index == UNDEFINED_INDEX}.
      * @throws std::invalid_argument if index is invalid (out of range).
      */
     PVFieldPtr select(int32 index);
@@ -966,24 +966,27 @@ public:
     std::string getSelectedFieldName() const;
     
     /**
-     * Set the {@code PVField} (by reference!) as selected field.
-     * If a value is not a valid union field an {@code std::invalid_argument} exception is thrown.
+     * Set the @c PVField (by reference!) as selected field.
+     * If a value is not a valid union field an @c std::invalid_argument
+     * exception is thrown.
      * @param value the field to set.
      */
     void set(PVFieldPtr const & value);
     /**
-     * Set the {@code PVField} (by reference!) as field at given index.
-     * If a value is not a valid union field an {@code std::invalid_argument} exception is thrown.
-     * Use {@code select(int32)} to put by value.
+     * Set the @c PVField (by reference!) as field at given index.
+     * If a value is not a valid union field an @c std::invalid_argument
+     * exception is thrown.
+     * Use @c select(int32) to put by value.
      * @param index index of a field to put.
      * @param value the field to set.
      * @see #select(int32)
      */
     void set(int32 index, PVFieldPtr const & value);
     /**
-     * Set the {@code PVField} (by reference!) as field by given name.
-     * If a value is not a valid union field an {@code std::invalid_argument} exception is thrown.
-     * Use {@code select(std::string const &)} to put by value.
+     * Set the @c PVField (by reference!) as field by given name.
+     * If a value is not a valid union field an @c std::invalid_argument
+     * exception is thrown.
+     * Use @c select(std::string const &) to put by value.
      * @param fieldName Name of the field to put.
      * @param value the field to set.
      * @see #select(std::string const &)
diff --git a/src/pv/pvIntrospect.h b/src/pv/pvIntrospect.h
index eb12dcc..4708604 100644
--- a/src/pv/pvIntrospect.h
+++ b/src/pv/pvIntrospect.h
@@ -183,7 +183,7 @@ epicsShareExtern std::ostream& operator<<(std::ostream& o, const Type& type);
  */
 enum ScalarType {
     /**
-     * The type is boolean, i.e. value can be {@code false} or {@code true}
+     * The type is boolean, i.e. value can be @c false or @c true
      */
     pvBoolean,
     /**
@@ -884,7 +884,7 @@ typedef std::tr1::shared_ptr FieldBuilderPtr;
 /**
  * @brief Interface for in-line creating of introspection interfaces.
  *
- * One instance can be used to create multiple {@code Field} instances.
+ * One instance can be used to create multiple @c Field instances.
  * An instance of this object must not be used concurrently (an object has a state).
  * @author mse
  */
@@ -895,118 +895,118 @@ public:
 	/**
 	 * Set ID of an object to be created.
 	 * @param id id to be set.
-     * @return this instance of a {@code FieldBuilder}.
+     * @return this instance of a @c FieldBuilder.
 	 */
 	FieldBuilderPtr setId(std::string const & id);
 
     /**
-     * Add a {@code Scalar}.
+     * Add a @c Scalar.
      * @param name name of the array.
      * @param scalarType type of a scalar to add.
-     * @return this instance of a {@code FieldBuilder}.
+     * @return this instance of a @c FieldBuilder.
      */
     FieldBuilderPtr add(std::string const & name, ScalarType scalarType);
 
     /**
-     * Add a {@code BoundedString}.
+     * Add a @c BoundedString.
      * @param name name of the array.
      * @param maxLength a string maximum length.
-     * @return this instance of a {@code FieldBuilder}.
+     * @return this instance of a @c FieldBuilder.
      */
     FieldBuilderPtr addBoundedString(std::string const & name, std::size_t maxLength);
 
     /**
-     * Add a {@code Field} (e.g. {@code Structure}, {@code Union}).
+     * Add a @c Field (e.g. @c Structure, @c Union).
      * @param name name of the array.
      * @param field a field to add.
-     * @return this instance of a {@code FieldBuilder}.
+     * @return this instance of a @c FieldBuilder.
      */
     FieldBuilderPtr add(std::string const & name, FieldConstPtr const & field);
 
     /**
-     * Add variable size array of {@code Scalar} elements.
+     * Add variable size array of @c Scalar elements.
      * @param name name of the array.
      * @param scalarType type of a scalar element.
-     * @return this instance of a {@code FieldBuilder}.
+     * @return this instance of a @c FieldBuilder.
      */
     FieldBuilderPtr addArray(std::string const & name, ScalarType scalarType);
     
     /**
-     * Add fixed-size array of {@code Scalar} elements.
+     * Add fixed-size array of @c Scalar elements.
      * @param name name of the array.
      * @param scalarType type of a scalar element.
      * @param size Array fixed size.
-     * @return this instance of a {@code FieldBuilder}.
+     * @return this instance of a @c FieldBuilder.
      */
     FieldBuilderPtr addFixedArray(std::string const & name, ScalarType scalarType, std::size_t size);
 
     /**
-     * Add bounded-size array of {@code Scalar} elements.
+     * Add bounded-size array of @c Scalar elements.
      * @param name name of the array.
      * @param scalarType type of a scalar element.
      * @param bound Array maximum capacity (size).
-     * @return this instance of a {@code FieldBuilder}.
+     * @return this instance of a @c FieldBuilder.
      */
     FieldBuilderPtr addBoundedArray(std::string const & name, ScalarType scalarType, std::size_t bound);
 
     /**
-     * Add array of {@code Field} elements.
+     * Add array of @c Field elements.
      * @param name name of the array.
      * @param element a type of an array element.
-     * @return this instance of a {@code FieldBuilder}.
+     * @return this instance of a @c FieldBuilder.
      */
     FieldBuilderPtr addArray(std::string const & name, FieldConstPtr const & element);
 
     /**
-     * Create a {@code Structure}.
-     * This resets this instance state and allows new {@code Field} instance to be created.
-     * @return a new instance of a {@code Structure}.
+     * Create a @c Structure.
+     * This resets this instance state and allows new @c Field instance to be created.
+     * @return a new instance of a @c Structure.
      */
     StructureConstPtr createStructure();
     
     /**
-     * Create an {@code Union}.
-     * This resets this instance state and allows new {@code Field} instance to be created.
-     * @return a new instance of an {@code Union}.
+     * Create an @c Union.
+     * This resets this instance state and allows new @c Field instance to be created.
+     * @return a new instance of an @c Union.
      */
     UnionConstPtr createUnion();
 
     /**
-     * Add new nested {@code Structure}.
-     * {@code endNested()} method must be called
-     * to complete creation of the nested {@code Structure}.
+     * Add new nested @c Structure.
+     * endNested()  method must be called
+     * to complete creation of the nested @c Structure.
      * @param name nested structure name.
-     * @return a new instance of a {@code FieldBuilder} is returned.
+     * @return a new instance of a @c FieldBuilder is returned.
      * @see #endNested()
      */
     FieldBuilderPtr addNestedStructure(std::string const & name); 
     
     /**
-     * Add new nested {@code Union}.
-     * {@code endNested()} method must be called
-     * to complete creation of the nested {@code Union}.
+     * Add new nested @c Union.
+     * endNested() method must be called
+     * to complete creation of the nested @c Union.
      * @param name nested union name.
-     * @return a new instance of a {@code FieldBuilder} is returned.
+     * @return a new instance of a @c FieldBuilder is returned.
      * @see #endNested()
      */
     FieldBuilderPtr addNestedUnion(std::string const & name);
     
     /**
-     * Add new nested {@code Structure[]}.
-     * {@code endNested()} method must be called
-     * to complete creation of the nested {@code Structure}.
+     * Add new nested @c Structure[].
+     * endNested() method must be called
+     * to complete creation of the nested @c Structure.
      * @param name nested structure name.
-     * @return a new instance of a {@code FieldBuilder} is returned.
+     * @return a new instance of a @c FieldBuilder is returned.
      * @see #endNested()
      */
     FieldBuilderPtr addNestedStructureArray(std::string const & name); 
     
     /**
-     * Add new nested {@code Union[]}.
-     * {@code endNested()} method must be called
-     * to complete creation of the nested {@code Union}.
+     * Add new nested @c Union[].
+     * endNested() method must be called
+     * to complete creation of the nested @c Union.
      * @param name nested union name.
-     * @return a new instance of a {@code FieldBuilder} is returned.
+     * @return a new instance of a @c FieldBuilder is returned.
      * @see #endNested()
      */
     FieldBuilderPtr addNestedUnionArray(std::string const & name);
@@ -1015,7 +1015,7 @@ public:
      * Complete the creation of a nested object.
      * @see #addNestedStructure(std::string const & name)
      * @see #addNestedUnion(std::string const & name)
-     * @return a previous (parent) {@code FieldBuilder}.
+     * @return a previous (parent) @c FieldBuilder.
      */
     FieldBuilderPtr endNested();
 
@@ -1054,106 +1054,106 @@ class epicsShareClass FieldCreate {
 public:
     static FieldCreatePtr getFieldCreate();
 	/**
-	 * Create a new instance of in-line {@code Field} builder.
-	 * @return a new instance of a {@code FieldBuilder}.
+	 * Create a new instance of in-line @c Field builder.
+	 * @return a new instance of a @c FieldBuilder.
 	 */
 	FieldBuilderPtr createFieldBuilder() const;
     /**
-     * Create a {@code ScalarField}.
+     * Create a @c ScalarField.
      * @param scalarType The scalar type.
-     * @return a {@code Scalar} interface for the newly created object.
+     * @return a @c Scalar interface for the newly created object.
      * @throws IllegalArgumentException if an illegal type is specified.
      */
     ScalarConstPtr createScalar(ScalarType scalarType) const;
     /**
-     * Create a {@code BoundedString}.
+     * Create a @c BoundedString.
      * @param maxLength a string maximum length.
-     * @return a {@code BoundedString} interface for the newly created object.
+     * @return a @c BoundedString interface for the newly created object.
      * @throws IllegalArgumentException if maxLength == 0.
      */
     BoundedStringConstPtr createBoundedString(std::size_t maxLength) const;
     /**
-     * Create an {@code Array} field, variable size array.
-     * @param elementType The {@code scalarType} for array elements
-     * @return An {@code Array} Interface for the newly created object.
+     * Create an @c Array field, variable size array.
+     * @param elementType The @c ScalarType for array elements
+     * @return An @c Array Interface for the newly created object.
      */
     ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
     /*
-     * Create an {@code Array} field, fixed size array.
-     * @param elementType The {@code scalarType} for array elements
+     * Create an @c Array field, fixed size array.
+     * @param elementType The @c ScalarType for array elements
      * @param size Fixed array size.
-     * @return An {@code Array} Interface for the newly created object.
+     * @return An @c Array Interface for the newly created object.
      */
     ScalarArrayConstPtr createFixedScalarArray(ScalarType elementType, std::size_t size) const;
     /**
-     * Create an {@code Array} field, bounded size array.
-     * @param elementType The {@code scalarType} for array elements
+     * Create an @c Array field, bounded size array.
+     * @param elementType The @c ScalarType for array elements
      * @param bound Array maximum capacity.
-     * @return An {@code Array} Interface for the newly created object.
+     * @return An @c Array Interface for the newly created object.
      */
      ScalarArrayConstPtr createBoundedScalarArray(ScalarType elementType, std::size_t bound) const;
      /**
-      * Create an {@code Array} field that is has element type Structure
-      * @param structure The {@code Structure} for each array element.
-      * @return An {@code Array} Interface for the newly created object.
+      * Create an @c Array field that is has element type @c Structure
+      * @param structure The @c Structure for each array element.
+      * @return An @c Array Interface for the newly created object.
       */
     StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
     /**
-     * Create a {@code Structure} field.
-     * @return a {@code Structure} interface for the newly created object.
+     * Create a @c Structure field.
+     * @return a @c Structure interface for the newly created object.
      */
     StructureConstPtr createStructure () const;
     /**
-     * Create a {@code Structure} field.
-     * @param fieldNames The array of {@code fieldNames} for the structure.
-     * @param fields The array of {@code fields} for the structure.
-     * @return a {@code Structure} interface for the newly created object.
+     * Create a @c Structure field.
+     * @param fieldNames the names of the fields for the structure.
+     * @param fields The array of @c Field objects for the structure.
+     * @return a @c Structure interface for the newly created object.
      */
     StructureConstPtr createStructure (
         StringArray const & fieldNames,
         FieldConstPtrArray const & fields) const;
     /**
-     * Create a {@code Structure} field with identification string.
+     * Create a @c Structure field with identification string.
      * @param id The identification string for the structure.
-     * @param fieldNames The array of {@code fieldNames} for the structure.
-     * @param fields The array of {@code fields} for the structure.
-     * @return a {@code Structure} interface for the newly created object.
+     * @param fieldNames the names of the fields for the structure.
+     * @param fields The array of @c Field objects for the structure.
+     * @return a @c Structure interface for the newly created object.
      */
     StructureConstPtr createStructure (
     	std::string const & id,
         StringArray const & fieldNames,
         FieldConstPtrArray const & fields) const;
      /**
-      * Create an {@code Array} field that is has element type Union
-      * @param punion The {@code Union} for each array element.
-      * @return An {@code Array} Interface for the newly created object.
+      * Create an @c Array field that is has element type @c Union
+      * @param punion The @c Union for each array element.
+      * @return An @c Array Interface for the newly created object.
       */
     UnionArrayConstPtr createUnionArray(UnionConstPtr const & punion) const;
     /**
-     * Create a variant {@code UnionArray} (aka any type) field.
-     * @return a {@code UnionArray} interface for the newly created object.
+     * Create a variant @c UnionArray (aka any type) field.
+     * @return a @c UnionArray interface for the newly created object.
      */
     UnionArrayConstPtr createVariantUnionArray() const;
     /**
-     * Create a variant {@code Union} (aka any type) field.
-     * @return a {@code Union} interface for the newly created object.
+     * Create a variant @c Union (aka any type) field.
+     * @return a @c Union interface for the newly created object.
      */
     UnionConstPtr createVariantUnion() const;
     /**
-     * Create a {@code Union} field.
-     * @param fieldNames The array of {@code fieldNames} for the union.
-     * @param fields The array of {@code fields} for the union.
-     * @return a {@code Union} interface for the newly created object.
+     * Create a @c Union field.
+     * @param fieldNames the names of the fields for the union.
+     * @param fields The @c Field for each fields for the union.
+     * @return a @c Union interface for the newly created object.
      */
     UnionConstPtr createUnion (
         StringArray const & fieldNames,
         FieldConstPtrArray const & fields) const;
     /**
-     * Create a {@code Union} field with identification string.
+     * Create a @c Union field with identification string.
      * @param id The identification string for the union.
-     * @param fieldNames The array of {@code fieldNames} for the union.
-     * @param fields The array of {@code fields} for the union.
-     * @return a {@code Union} interface for the newly created object.
+     * @param fieldNames the names of the fields for the union.
+     * @param fields The array of @c Field objects for the union.
+     * @return a @c Union interface for the newly created object.
      */
     UnionConstPtr createUnion (
     	std::string const & id,
@@ -1164,7 +1164,7 @@ public:
      * @param structure The structure to which the field is appended.
      * @param fieldName The name of the field.
      * @param field The field.
-     * @return a {@code Structure} interface for the newly created object.
+     * @return a @c Structure interface for the newly created object.
      */
     StructureConstPtr appendField(
         StructureConstPtr const & structure,
@@ -1174,17 +1174,17 @@ public:
      * @param structure The structure to which the fields appended.
      * @param fieldNames The names of the fields.
      * @param fields The fields.
-     * @return a {@code Structure} interface for the newly created object.
+     * @return a @c Structure interface for the newly created object.
      */
     StructureConstPtr appendFields(
         StructureConstPtr const & structure,
         StringArray const & fieldNames,
         FieldConstPtrArray const & fields) const;
     /**
-     * Deserialize {@code Field} instance from given byte buffer.
-     * @param buffer Buffer containing serialized {@code Field} instance. 
+     * Deserialize @c Field instance from given byte buffer.
+     * @param buffer Buffer containing serialized @c Field instance. 
      * @param control Deserialization control instance.
-     * @return a deserialized {@code Field} instance.
+     * @return a deserialized @c Field instance.
      */
     FieldConstPtr deserialize(ByteBuffer* buffer, DeserializableControl* control) const;
         
diff --git a/src/pv/pvType.h b/src/pv/pvType.h
index fe2914c..1a77ead 100644
--- a/src/pv/pvType.h
+++ b/src/pv/pvType.h
@@ -53,7 +53,7 @@ namespace detail {
  */
 
 /**
- * boolean, i.e. can only have the values {@code false} or {@code true}
+ * boolean, i.e. can only have the values @c false or @c true
  */
 typedef detail::pick_type::type

From 9d877d764f7bed2b5849180fd2412f10dd1038bb Mon Sep 17 00:00:00 2001
From: Dave Hickin 
Date: Thu, 15 Oct 2015 07:12:42 +0100
Subject: [PATCH 6/8] Doxgen fixes and enhancements

Change ¶m to @param. Add missing parameter.
Add more doxygen comments in SerializeHelper.
---
 src/misc/serialize.h       |  4 ++--
 src/misc/serializeHelper.h | 10 ++++++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/src/misc/serialize.h b/src/misc/serialize.h
index db70a0d..0e30ba6 100644
--- a/src/misc/serialize.h
+++ b/src/misc/serialize.h
@@ -165,7 +165,7 @@ namespace epics { namespace pvData {
          * Serialize field into given buffer.
          * @param buffer serialization buffer.
          * @param flusher flush interface.
-         * ¶m bitSet The bitSet to serialize.
+         * @param bitSet The bitSet to serialize.
          */
         virtual void serialize(ByteBuffer *buffer,
             SerializableControl *flusher,BitSet *bitSet) const = 0;
@@ -173,7 +173,7 @@ namespace epics { namespace pvData {
          * Deserialize buffer.
          * @param buffer serialization buffer.
          * @param flusher deserialization control.
-         * ¶m bitSet The bitSet to deserialize.
+         * @param bitSet The bitSet to deserialize.
          */
         virtual void deserialize(ByteBuffer *buffer,
             DeserializableControl *flusher,BitSet *bitSet) = 0;
diff --git a/src/misc/serializeHelper.h b/src/misc/serializeHelper.h
index d741fb0..39f0799 100644
--- a/src/misc/serializeHelper.h
+++ b/src/misc/serializeHelper.h
@@ -31,19 +31,25 @@ namespace epics {
         public:
 
             /**
-             * Serialize array size.
+             * Serialize the specified array size into the specified
+             * buffer, flushing when necessary.
+             * The specified SerializableControl manages any flushing
+             * required.
              *
              * @param[in] s size to encode
              * @param[in] buffer serialization buffer
-             * @param[in] flusher flusher
+             * @param[in] flusher SerializableControl to manage the flushing
              */
             static void writeSize(std::size_t s, ByteBuffer* buffer,
                     SerializableControl* flusher);
 
             /**
              * Deserialize array size.
+             * The specified DeserializableControl ensures
+             * sufficient bytes are available.
              *
              * @param[in] buffer deserialization buffer.
+             * @param[in] control the DeserializableControl.
              * @returns array size.
              */
             static std::size_t readSize(ByteBuffer* buffer,

From 0a2243e033fc80c033acce8220dad13a4bb43c7b Mon Sep 17 00:00:00 2001
From: Dave Hickin 
Date: Thu, 15 Oct 2015 07:46:40 +0100
Subject: [PATCH 7/8] Update TODO

---
 documentation/TODO.html | 17 -----------------
 documentation/TODO.md   | 13 -------------
 2 files changed, 30 deletions(-)
 delete mode 100644 documentation/TODO.html

diff --git a/documentation/TODO.html b/documentation/TODO.html
deleted file mode 100644
index 289412d..0000000
--- a/documentation/TODO.html
+++ /dev/null
@@ -1,17 +0,0 @@
-
TODO

-
printer

-
pv/printer.h is not used.

-
doxygen

-
There is a lot of public code that does not have doxygen tags.

-
postMonitor: PVUnion, PVUnionArray, and PVStructureArray

-
PVUnion, PVUnionArray, and PVStructureArray all have elements
-that are treated like a top level field.

-
Currently if a subField of any of these is changed postMonitor is not called for the field itself.

-
David asked if this could be changed so that it is called.
-Marty thinks this may not be a good idea.

-
valueAlarm

-
normativeTypes.html describes valueAlarm only for a value field that has type
-double.
-The implementation also supports all the numeric scalar types.

-
monitorPlugin

-
A debate is on-going about what semantics should be.

\ No newline at end of file
diff --git a/documentation/TODO.md b/documentation/TODO.md
index 2ab06e5..c905c52 100644
--- a/documentation/TODO.md
+++ b/documentation/TODO.md
@@ -6,19 +6,6 @@ doxygen
 
 There is a lot of public code that does not have doxygen tags.
 
-
-postMonitor: PVUnion, PVUnionArray, and PVStructureArray
---------
-
-PVUnion, PVUnionArray, and PVStructureArray all have elements
-that are treated like a top level field.
-
-Currently if a subField of any of these is changed postMonitor is not called for the field itself.
-
-David asked if this could be changed so that it is called.
-Marty thinks this may not be a good idea.
-
-
 valueAlarm
 ---------
 

From fdc289d88852142c7156d13904031e4cac8ff3ab Mon Sep 17 00:00:00 2001
From: Dave Hickin 
Date: Thu, 15 Oct 2015 09:16:20 +0100
Subject: [PATCH 8/8] Add new README

Replace out of date HTML README with a new markdown one
---
 README.html | 82 -----------------------------------------------------
 README.md   | 57 +++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 82 deletions(-)
 delete mode 100644 README.html
 create mode 100644 README.md

diff --git a/README.html b/README.html
deleted file mode 100644
index 29015a0..0000000
--- a/README.html
+++ /dev/null
@@ -1,82 +0,0 @@
-
-
-
-
-  
-  EPICS pvData C++
-
-
-
-
EPICS pvData C++

-Overview

-2010.08.10

-CONTENTS 
-

-
-
Introduction

-

-
-
This project has the begining of the C++ implementation of pvData. The
-following is done:

-

-  
introspection interfaces

-    
The introspection interfaces for clients are described.

-  
introspection implementation

-    
The following have been implemented: Type, ScalarType, Field,
-    Scalar

-  
test

-    
A test of Scalar.

-  
As mentioned below there are problems with the current
-  implementation.

-

-

-
-
Building

-

-
-
The project is structured as an epics base client application. Edit
-configure/RELEASE so that it references your EPICS base and then just
-type:

-
   make

-
-
At the top. Then execute the test in the bin directory.

-
-
pvDataApp has the following sub directories:

-

-  
pv

-    
pvData.h has the interface descriptions for client code.

-  
factory

-    
FieldCreateFactory.cpp has the current implementation

-  
test

-    
Has a test for the current implementation.

-

-

-
-
Questions about Classes

-

-
-
The pure virtual classes defined in pvData.h now work. But there are still
-some things that are not so nice. Amoung these are:

-
    
-  
  • In FieldCreateFactory.cpp look for "WHY DO I". It asks why the derived
-    class must also define methods defined in the base class. If it does not
-    then a compilation error occurs. WHY??? 
    • 
-  
  • The toString methods have an argument of "std::string &buf" instead
-    of "std::string *". Does this seem correct?
    • 
-  
  • Can arguments and return descriptions be defined better?
    • 
-  
  • Is const present everywhere it should be? Remember that introspection
-    classes are immutable.
    • 
-  
  • The code is NOT thread safe. When we decide for sure what thread/lock
-    support to choose I will fix this.
    • 
-

-
-
HELP WILL BE GREATLY APPRECIATED. because I am still coming up to speed
-with c++

-

-
-
Garbage Collection

-

-
Not yet implemented. Lets get class structure correct first.

-
-
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f131ebf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+pvaDataCPP
+==========
+
+pvDataCPP is a set of data types and utilities that form part of the EPICS V4 project.
+
+
+Further Info
+------------
+
+Consult the documents in the documentation directory, in particular
+
+* pvDataCPP.html
+* RELEASE_NOTES.md
+
+Also see the [EPICS Version 4 website](http://epics-pvdata.sourceforge.net)
+
+Prerequisites
+-------------
+
+The pvDataCPP  requires recent versions of the following software:
+
+1. EPICS Base (v3.14.12.3 or later)
+2. EPICS4 pvCommonCPP (4.1.0 or later pvCommonCPP may not be needed)
+
+(pvCommonCPP may not be needed depending on host/compiler.)
+
+
+Building
+--------
+
+Building uses the make utility and the EPICS base build system.
+
+The build system needs the location of the prerequisites, e.g. by placing the
+lines of the form
+
+    PVCOMMON = /home/install/epicsV4/pvCommonCPP
+    EPICS_BASE = /home/install/epics/base
+
+pointing to the locations in a file called RELEASE.local
+in the configure directory or the parent directory of pvDataCPP.
+
+With this in place, to build type make
+
+    make
+
+To perform a clean build type
+
+    make clean uninstall
+
+To run the unit tests type
+
+    make runtests
+
+For more information on the EPICS build system consult the
+[Application Development guide](http://www.aps.anl.gov/epics/base/R3-14/12-docs/AppDevGuide.pdf).
+
+