Update release notes for 5.0.3 release

Split long line in README
missing buffer capacity check in PVUnion::serialize
2016-01-28 17:14:02 +00:00 · 2016-01-28 17:11:44 +00:00 · 2016-01-28 13:14:04 +00:00 · 2015-10-15 10:37:46 +01:00 · 2015-10-15 10:37:12 +01:00 · 2015-10-15 09:39:53 +01:00
24 changed files with 515 additions and 387 deletions
--- a/README.html
+++ b/README.html
@@ -1,82 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
-  <title>EPICS pvData C++</title>
-</head>
-
-<body>
-<h1 style="text-align: center">EPICS pvData C++<br />
-Overview<br />
-2010.08.10</h1>
-CONTENTS 
-<hr />
-
-<h2 style="text-align: center">Introduction</h2>
-<hr />
-
-<p>This project has the begining of the C++ implementation of pvData. The
-following is done:</p>
-<dl>
-  <dt>introspection interfaces</dt>
-    <dd>The introspection interfaces for clients are described.</dd>
-  <dt>introspection implementation</dt>
-    <dd>The following have been implemented: Type, ScalarType, Field,
-    Scalar</dd>
-  <dt>test</dt>
-    <dd>A test of Scalar.</dd>
-  <dt>As mentioned below there are problems with the current
-  implementation.</dt>
-</dl>
-<hr />
-
-<h2 style="text-align: center">Building</h2>
-<hr />
-
-<p>The project is structured as an epics base client application. Edit
-configure/RELEASE so that it references your EPICS base and then just
-type:</p>
-<pre>   make</pre>
-
-<p>At the top. Then execute the test in the bin directory.</p>
-
-<p>pvDataApp has the following sub directories:</p>
-<dl>
-  <dt>pv</dt>
-    <dd>pvData.h has the interface descriptions for client code.</dd>
-  <dt>factory</dt>
-    <dd>FieldCreateFactory.cpp has the current implementation</dd>
-  <dt>test</dt>
-    <dd>Has a test for the current implementation.</dd>
-</dl>
-<hr />
-
-<h2 style="text-align: center">Questions about Classes</h2>
-<hr />
-
-<p>The pure virtual classes defined in pvData.h now work. But there are still
-some things that are not so nice. Amoung these are:</p>
-<ul>
-  <li>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??? </li>
-  <li>The toString methods have an argument of "std::string &amp;buf" instead
-    of "std::string *". Does this seem correct?</li>
-  <li>Can arguments and return descriptions be defined better?</li>
-  <li>Is const present everywhere it should be? Remember that introspection
-    classes are immutable.</li>
-  <li>The code is NOT thread safe. When we decide for sure what thread/lock
-    support to choose I will fix this.</li>
-</ul>
-
-<p>HELP WILL BE GREATLY APPRECIATED. because I am still coming up to speed
-with c++</p>
-<hr />
-
-<h2 style="text-align: center">Garbage Collection</h2>
-<hr />
-<p>Not yet implemented. Lets get class structure correct first.</p>
-</body>
-</html>
--- a/README.md
+++ b/README.md
@@ -0,0 +1,58 @@
+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 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).
+
+
--- a/documentation/RELEASE_NOTES.html
+++ b/documentation/RELEASE_NOTES.html
@@ -1,66 +1,152 @@
-<h1>Release 4.1 IN DEVELOPMENT</h1>
-<p>The main changes since release 4.0 are:</p>
+<h1>Release 5.0.3</h1>
+
+<p>The only change since release 5.0.2 is:</p>
+
+<h2>Fixed buffer overflow in PVUnion::serialize() (issue #20)</h2>
+
+<p>A PVUnion whose stored value was null was serialized without checking 
+whether the buffer had sufficient capacity. This has been fixed by calling
+ensureBuffer().</p>
+
+<h1>Release 5.0.2</h1>
+
+<p>The main changes since release 4.0.3 are:</p>
+
 <ul>
+<li>Deprecated getXXXField() methods have been removed from PVStructure</li>
 <li>Convert copy methods and equals operators (re)moved</li>
 <li>Convert::copyUnion now always copies between subfields.</li>
-<li>CreateRequest prevents a possible SEGFAULT.</li>
-<li>New stream operators for Field and PVField are provided.</li>
-<li>New method getAs that is like getSubField except that it throws exception</li>
+<li>New method getSubFieldT, like getSubField except it throws an exception</li>
+<li>findSubField method removed from PVStructure</li>
+<li>New stream operators for Field and PVField are provided</li>
+<li>New template versions of Structure::getField</li>
+<li>Fixes for static initialisation order issues</li>
+<li>CreateRequest prevents a possible SEGFAULT</li>
 </ul>
+
+<h2>Deprecated getXXXField methods have been removed from PVStructure</h2>
+
+<p>The following methods have been removed from PVStructure</p>
+
+<ul>
+<li>getBooleanField</li>
+<li>getByteField, getShortField, getIntField, getLongField</li>
+<li>getUByteField, getUShortField, getUIntField, getULongField</li>
+<li>getStringField</li>
+<li>getStructureField, getUnionField</li>
+<li>getScalarArrayField, getStructureArrayField, getUnionArrayField</li>
+</ul>
+
+<p>Use template getSubField instead, e.g. use</p>
+
+<pre><code>getSubField&lt; PVInt &gt;(fieldName)
+</code></pre>
+
+<p>in place of</p>
+
+<pre><code>getIntField(fieldName)
+</code></pre>
+
 <h2>Convert copy methods and equals operators</h2>
+
 <p>Convert copy methods where moved and replaced with methods
 on PVField classes, i.e.</p>
+
 <pre><code>PVField::copy(const PVField&amp; from)
 </code></pre>
+
 <p>Methods</p>
+
 <pre><code>PVField::copyUnchecked(const PVField&amp; from)
 </code></pre>
-<p>where added to allow unchecked copies, to gain performance
+
+<p>were added to allow unchecked copies, to gain performance
 where checked are not needed (anymore).</p>
+
 <p>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</p>
+
 <h2>Convert::copyUnion</h2>
+
 <p>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.</p>
-<h2>CreateRequest change</h2>
-<p>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.</p>
+
+<h2>New method getSubFieldT, like getSubField except it throws an exception</h2>
+
+<p>PVStructure has a new template member</p>
+
+<pre><code>getSubFieldT(std::string const &amp;fieldName)
+</code></pre>
+
+<p>that is like <b>getSubField</b> except that it throws a runtime_error
+instead of returning null.</p>
+
+<h2>findSubField method removed from PVStructure</h2>
+
+<p>This was mainly used in the implementation of getSubField. With a change to
+the latter, findSubField was removed.</p>
+
 <h2>New stream operators</h2>
+
 <p>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:</p>
-<pre><code> void print(StructureConstPtr struct, PVStructurePtr pv)
+
+<pre><code> void print(StructureConstPtr struc, PVStructurePtr pv)
 {
-     if(struct) {
-         cout &lt;&lt; *struct &lt;&lt; endl;
+     if(struc) {
+         cout &lt;&lt; *struc &lt;&lt; endl;
     } else {
         cout &lt;&lt; "nullptr\n"
     }
     if(pv) {
-         cout &lt;&lt; *.struct &lt;&lt; endl;
+         cout &lt;&lt; *.struc &lt;&lt; endl;
     } else {
         cout &lt;&lt; "nullptr\n"
     }
 }
 </code></pre>
+
 <p>Now it can be done as follows:</p>
-<pre><code> void print(StructureConstPtr struct, PVStructurePtr pv)
+
+<pre><code> void print(StructureConstPtr struc, PVStructurePtr pv)
 {
-     cout &lt;&lt; struct &lt;&lt; endl;
+     cout &lt;&lt; struc &lt;&lt; endl;
     cout &lt;&lt; pv &lt;&lt; endl;
 }
 </code></pre>
-<h2>New method getAs that is like getSubField except that it throws exception</h2>
-<p><b>PVStructure</b> has a new template member <b>getAs(const char *name)</b>
-that is like <b>getSubField</b> except that it throws a runtime_error
-instead of returning null.</p>
-<h1>Release 4.0</h1>
+
+<h2>New template version of Structure::getField</h2>
+
+<p>A new template getField method has been added to Structure</p>
+
+<p>template<typename FT >
+std::tr1::shared_ptr&lt; const FT > getField(std::string const &amp;fieldName) const </p>
+
+<p>Can be used, for example, as follows:</p>
+
+<pre><code>StructurePtr tsStruc = struc-&gt;getField&lt;Structure&gt;("timeStamp");
+</code></pre>
+
+<h2>Fixes for static initialisation order issues</h2>
+
+<p>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.</p>
+
+<h2>CreateRequest change</h2>
+
+<p>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.</p>
+
+<h1>Release 4.0.3</h1>
+
 <p>The main changes since release 3.0.2 are:</p>
+
 <ul>
 <li>array semantics now enforce Copy On Write.</li>
 <li>String no longer defined.</li>
@@ -70,21 +156,31 @@ instead of returning null.</p>
 <li>copy is new.</li>
 <li>monitorPlugin is new.</li>
 </ul>
+
 <h2>New Semantics for Arrays</h2>
+
 <p>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 shared<em>vector 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.</p>
+COW is implemented via shared</em>vectors of const data, i. e. data that can not be modified.</p>
+
 <h2>String no longer defined</h2>
+
 <p>This is replaced by std::string.</p>
+
 <h2>timeStamp and valueAlarm name changes</h2>
+
 <p>In timeStamp nanoSeconds is changed to nanoseconds.</p>
-<p>In valueAlarm hystersis is changed to hysteresis</p>
+
+<p>In valueAlarm hysteresis is changed to hysteresis</p>
+
 <h2>toString replaced by stream I/O</h2>
+
 <p>pvData.h and pvIntrospect no longer defines toString
 Instead they have stream support.
 pvIntrospect uses method dump and pvData uses dumpValue.
 For example:</p>
+
 <pre><code>  PVDoublePtr pvValue;
  String buffer;
  pvValue-&gt;toString(&amp;buffer);
@@ -93,27 +189,40 @@ For example:</p>
  pvValue-&gt;getField()-&gt;toString(&amp;buffer);
  cout &lt;&lt; buffer &lt;&lt; evdl;
 </code></pre>
+
 <p>is replaced by</p>
+
 <pre><code>  PVDoublePtr pvValue;
  cout &lt;&lt; *pvValue &lt;&lt; endl
  cout &lt;&lt; *pvValue-&gt;getField() &lt;&lt; endl;
 </code></pre>
+
 <h2>union is a new basic type.</h2>
+
 <p>There are two new basic types: union_t and unionArray.</p>
+
 <p>A union is like a structure that has a single subfield.
 There are two flavors:</p>
+
 <ul>
-<li><b>varient union</b> The field can have any type.</li>
+<li><b>variant union</b> The field can have any type.</li>
 <li><b>union</b> The field can any of specified set of types.</li>
 </ul>
+
 <p>The field type can be dynamically changed.</p>
-<h2>copy</h2>
+
+<h2>copy </h2>
+
 <p>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.</p>
+only on pvData, i.e. it no longer has any knowledge of PVRecord.</p>
+
 <h2>monitorPlugin</h2>
+
 <p>This is for is for use by code that implements pvAccess monitors.
 This is prototype and is subject to debate.</p>
+
 <h1>Release 3.0.2</h1>
-<p>This was the starting point for RELEASE_NOTES</p>
+
+<p>This was the starting point for RELEASE_NOTES</p>
--- a/documentation/RELEASE_NOTES.md
+++ b/documentation/RELEASE_NOTES.md
@@ -1,13 +1,52 @@
-Release 4.1 IN DEVELOPMENT
-===========
+Release 5.0.3
+=============

-The main changes since release 4.0 are:
+The only change since release 5.0.2 is:

+Fixed buffer overflow in PVUnion::serialize() (issue #20)
+---------------------------------------------------------
+
+A PVUnion whose stored value was null was serialized without checking 
+whether the buffer had sufficient capacity. This has been fixed by calling
+ensureBuffer().
+
+
+Release 5.0.2
+=============
+
+The main changes since release 4.0.3 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 +60,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 +68,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 <b>getSubField</b> 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 +103,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,21 +119,43 @@ 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<typename FT >
+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
 --------------------

-<b>PVStructure</b> has a new template member <b>getSubFieldT(std::string const &fieldName)</b>
-that is like <b>getSubField</b> 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
-===========
+
+Release 4.0.3
+=============

 The main changes since release 3.0.2 are:

@@ -113,7 +187,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 +221,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:

-* <b>varient union</b> The field can have any type.
+* <b>variant union</b> The field can have any type.
 * <b>union</b> The field can any of specified set of types.

 The field type can be dynamically changed.
@@ -158,7 +232,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
 -------------
--- a/documentation/TODO.html
+++ b/documentation/TODO.html
@@ -1,17 +0,0 @@
-<h1>TODO</h1>
-<h2>printer</h2>
-<p>pv/printer.h is not used.</p>
-<h2>doxygen</h2>
-<p>There is a lot of public code that does not have doxygen tags.</p>
-<h2>postMonitor: PVUnion, PVUnionArray, and PVStructureArray</h2>
-<p>PVUnion, PVUnionArray, and PVStructureArray all have elements
-that are treated like a top level field.</p>
-<p>Currently if a subField of any of these is changed postMonitor is not called for the field itself.</p>
-<p>David asked if this could be changed so that it is called.
-Marty thinks this may not be a good idea.</p>
-<h2>valueAlarm</h2>
-<p>normativeTypes.html describes valueAlarm only for a value field that has type
-double.
-The implementation also supports all the numeric scalar types.</p>
-<h2>monitorPlugin</h2>
-<p>A debate is on-going about what semantics should be.</p>
--- 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
 ---------

--- 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
--- 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.
--- 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
--- a/src/factory/PVUnion.cpp
+++ b/src/factory/PVUnion.cpp
@@ -145,10 +145,10 @@ void PVUnion::serialize(ByteBuffer *pbuffer, SerializableControl *pflusher) cons
    if (variant)
    {
        // write introspection data
-        if (value.get() == 0)
+        if (value.get() == 0) {
+            pflusher->ensureBuffer(1);
            pbuffer->put((int8)-1);
-        else
-        {
+        }else {
            pflusher->cachedSerialize(value->getField(), pbuffer);
            value->serialize(pbuffer, pflusher);
        }
--- 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.
     *
     * <p>By default, all bits in the set initially have the value
-     * {@code false}.
+     * @c false.
     *
     * <p>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.
     *
-     * <p>A {@code BitSet} is not safe for multithreaded use without
-     * external synchronization.
+     * <p>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.
         *
-         * <p>To iterate over the {@code true} bits in a {@code BitSet},
+         * <p>To iterate over the @c true bits in a @c BitSet,
         * use the following loop:
         *
         *  <pre> {@code
@@ -131,13 +130,13 @@ namespace epics { namespace pvData {
         * }}</pre>
         *
         * @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 <b>AND</b> 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 <b>OR</b> 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 <b>XOR</b> 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:
         * <ul>
-         * <li>The bit initially has the value {@code true}, and the
-         *     corresponding bit in the argument has the value {@code false}.
-         * <li>The bit initially has the value {@code false}, and the
-         *     corresponding bit in the argument has the value {@code true}.
+         * <li>The bit initially has the value @c true, and the
+         *     corresponding bit in the argument has the value @c false.
+         * <li>The bit initially has the value @c false, and the
+         *     corresponding bit in the argument has the value @c true.
         * </ul>
         *
         * @param  set a bit set
--- 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.
 * 
- * <p>A {@code BitSet} is not safe for multithreaded use without
+ * <p>A @c BitSet is not safe for multithreaded use without
 * external synchronization.
 *
 * Based on Java implementation.
@@ -373,7 +373,7 @@ public:
    template<typename T>
    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.
@@ -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");
@@ -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<typename T>
    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.
@@ -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<double>(index); }
--- 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<const Field> cachedDeserialize(
@@ -166,7 +165,7 @@ namespace epics { namespace pvData {
         * Serialize field into given buffer.
         * @param buffer serialization buffer.
         * @param flusher flush interface.
-         * &param bitSet The bitSet to serialize.
+         * @param bitSet The bitSet to serialize.
         */
        virtual void serialize(ByteBuffer *buffer,
            SerializableControl *flusher,BitSet *bitSet) const = 0;
@@ -174,7 +173,7 @@ namespace epics { namespace pvData {
         * Deserialize buffer.
         * @param buffer serialization buffer.
         * @param flusher deserialization control.
-         * &param bitSet The bitSet to deserialize.
+         * @param bitSet The bitSet to deserialize.
         */
        virtual void deserialize(ByteBuffer *buffer,
            DeserializableControl *flusher,BitSet *bitSet) = 0;
@@ -196,7 +195,7 @@ namespace epics { namespace pvData {
         * Serialize field into given buffer.
         * @param buffer serialization buffer.
         * @param flusher flush interface.
-         * &param offset offset in elements.
+         * @param offset offset in elements.
         * @param count number of elements
         */
        virtual void serialize(
--- 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,
@@ -63,7 +69,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
--- 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);

--- 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.
     */
--- 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);
--- 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 <byte>.
+     * Convert a PV to a byte.
     * @param pv a PV
     * @return converted value
     */
--- 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;

@@ -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,8 +930,8 @@ 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).
+     * @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);

@@ -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);

@@ -966,27 +966,30 @@ 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(int)} 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(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.
+     * 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)
+     * @see #select(std::string const &)
     */
    void set(std::string const & fieldName, PVFieldPtr const & value);

@@ -1447,7 +1450,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 +1463,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<typename PVT>
@@ -1492,7 +1495,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 +1513,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 +1526,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<typename PVAT>
@@ -1587,9 +1589,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&);
--- 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,
    /**
@@ -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.
     */
@@ -884,7 +884,7 @@ typedef std::tr1::shared_ptr<FieldBuilder> 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,127 +895,127 @@ 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 field a type of an array element.
-     * @return this instance of a {@code FieldBuilder}.
+     * @param element a type of an array element.
+     * @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);

    /**
     * Complete the creation of a nested object.
-     * @see #addNestedStructure(std::string)
-     * @see #addNestedUnion(std::string)
-     * @return a previous (parent) {@code FieldBuilder}.
+     * @see #addNestedStructure(std::string const & name)
+     * @see #addNestedUnion(std::string const & name)
+     * @return a previous (parent) @c FieldBuilder.
     */
    FieldBuilderPtr endNested();

@@ -1054,108 +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.
-     * @throws An {@code IllegalArgumentException} if an illegal type is specified.
+     * @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.
-     * @throws An {@code IllegalArgumentException} if maxLength == 0.
+     * @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
-     * @param size Array maximum capacity (bound).
-     * @return An {@code Array} Interface for the newly created object.
+     * Create an @c Array field, bounded size array.
+     * @param elementType The @c ScalarType for array elements
+     * @param bound Array maximum capacity.
+     * @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 <i>Structure</i>
-      * @param fieldName The field name
-      * @param elementStructure 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 <i>Union</i>
-      * @param fieldName The field name
-      * @param elementUnion 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,
@@ -1166,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,19 +1172,19 @@ 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.
-     * @return a {@code Structure} interface for the newly created object.
+     * @param fieldNames The names of the fields.
+     * @param fields The fields.
+     * @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;
        
@@ -1201,7 +1199,7 @@ private:

 /**
 * Get the single class that implements FieldCreate,
- * @param The fieldCreate factory.
+ * @return The fieldCreate factory.
 */
 epicsShareExtern FieldCreatePtr getFieldCreate();

--- 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);
--- 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<int8_t, signed char,
                          detail::pick_type<uint8_t, char, unsigned char>::type
--- 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();
--- 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.
Author	SHA1	Message	Date
Dave Hickin	fff9884b4c	Update release notes for 5.0.3 release	2016-01-28 17:14:02 +00:00
Dave Hickin	8c92f5035b	Split long line in README	2016-01-28 17:11:44 +00:00
Michael Davidsaver	cdb79f8a22	missing buffer capacity check in PVUnion::serialize Allows a buffer overflow in PVUnionArray::serialize(). (cherry picked from commit `14b0e409f2`)	2016-01-28 13:14:04 +00:00
Dave Hickin	7fc3f50ae9	Merge branch 'master' into release/5.0	2015-10-15 10:37:46 +01:00
Dave Hickin	05d41f81e4	Minor correction to README	2015-10-15 10:37:12 +01:00
Dave Hickin	d400e8eaf5	Merge branch 'master' into release/5.0	2015-10-15 09:39:53 +01:00
Dave Hickin	fdc289d888	Add new README Replace out of date HTML README with a new markdown one	2015-10-15 09:16:20 +01:00
Dave Hickin	0a2243e033	Update TODO	2015-10-15 07:46:40 +01:00
Dave Hickin	9d877d764f	Doxgen fixes and enhancements Change &param to @param. Add missing parameter. Add more doxygen comments in SerializeHelper.	2015-10-15 07:12:42 +01:00
Dave Hickin	f5df29cf34	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.	2015-10-15 06:50:26 +01:00
Dave Hickin	8008823ea5	Fix doxygen warnings	2015-10-14 23:01:28 +01:00
Dave Hickin	6515de4bc0	Add release notes for 5.0	2015-10-08 15:24:14 +01:00
Ralph Lange	8c5f535b79	jenkins: fix CloudBees doc job	2015-09-28 15:29:39 +02:00
Ralph Lange	de2fac122c	jenkins: fix CloudBees doc job	2015-09-28 15:29:17 +02:00
Ralph Lange	036186fc12	jenkins: adapt doc script to new CloudBees jenkins job	2015-09-14 16:48:15 +02:00