update documentation

documentation/RELEASE_NOTES.md

@@ -4,6 +4,8 @@ Release release/3.1 IN DEVELOPMENT
 The main changes since release 3.0.2 are:
 
 * array semantics now enforce Copy On Write.
+* String no longer defined.
+* toString replaced by stream I/O 
 * union is new type.
 * copy is new.
 * monitorPlugin is new.
@@ -16,6 +18,36 @@ In order to limit memory usage the storage for raw data is managed via a new sha
 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.
 
+
+String no longer defined
+---------
+
+This is replaced by std::string.
+
+
+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);
+      cout << buffer << endl;
+      buffer.clear();
+      pvValue->getField()->toString(&buffer);
+      cout << buffer << evdl;
+
+is replaced by
+
+      PVDoublePtr pvValue;
+      cout << pvValue=>dumpValue(cout) << endl
+      cout << pvValue->getField()->dump(cout) << endl;
+
+
 union is a new basic type.
 ------------
 
@@ -41,6 +73,7 @@ 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
 ==========

documentation/TODO.md

@@ -1,33 +1,10 @@
 TODO
 ===========
 
-toString, dumpValue, printer, and streams
+printer
 ------------
 
-The way to print introspection and data instances is not consistent.
-This needs work.
-Some items that need work are:
-
-* Introspection  has no support for streams. Only for toString.
-* data has problems. toString is implemented by calling Convert::getString.
-It look like this was intended to use printer but that did nor properly indent fields of structures.
-
-The current implementation is:
-
-     void Convert::getString(StringBuilder buf,PVField const *pvField,int /*indentLevel*/)
-     {
-         // TODO indextLevel ignored
-         std::ostringstream strm;
-         strm << pvField->dumpValue(strm) << std::endl;
-     //    PrinterPlain p;
-     //    p.setStream(strm);
-     //    p.print(*pvField);
-         strm.str().swap(*buf);
-     }
-
-Thus it just uses dumpValue.
-What should it do?
-If printer is used it must do proper indentation.
+pv/printer.h is not used.
 
 doxygen
 -------
@@ -35,6 +12,15 @@ 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.
+The implementation should be changed so that it implements PostHandler.
+Thus when an element is modified it will call postPut for itself.
+
+
 monitorPlugin
 -------------
 
@@ -43,12 +29,7 @@ A debate is on-going about what semantics should be.
 PVFieldConstPtr etc
 -------------------
 
-In pvDataCPP.html look at the monoitorPlugin example.
-It has a discussion of a possible need for shared pointers that can not be used to modify data.
-This in addition to PVFieldPtr should PVFieldConstPtr exist.
+In addition to PVFieldPtr should PVFieldConstPtr exist.
 But this means that all methods defined in pvDataCPP must be checked.
 This is a BIG job.
 
-Release 3.0.2
-==========
-This was the starting point for RELEASE_NOTES

src/factory/Convert.cpp

@@ -18,7 +18,6 @@
 #include <pv/pvIntrospect.h>
 #include <pv/pvData.h>
 #include <pv/convert.h>
-#include <pv/printer.h>
 
 using std::tr1::static_pointer_cast;
 using std::size_t;

src/pv/convert.h

@@ -63,9 +63,7 @@ static inline bool operator!=(const UnionArray& a, const UnionArray& b)
  * pvUByte, pvUShort, pvUInt, pvULong,
  * pvFloat, or pvDouble.</p>
  * 
- * <p>getString converts any supported type to a std::string.
- * Code that implements a PVField interface should implement
- * method toString by calling this method.</p>
+ * <p>getString converts any supported type to a std::string.</p>
  *
  * <p>fromString converts a std::string to a scalar.
  * fromStringArray converts an array of std::strings
@@ -478,7 +476,7 @@ public:
     inline void fromDouble(PVScalarPtr const & pv, double from) { pv->putFrom<double>(from); }
 
     /**
-     * Convenience method for implementing toString.
+     * Convenience method for implementing dump.
      * It generates a newline and inserts blanks at the beginning of the newline.
      * @param builder The std::string * being constructed.
      * @param indentLevel Indent level, Each level is four spaces.