zeroc-ice 3.7.0 → 3.7.1

data/ext/ice/cpp/include/Ice/InputStream.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -29,6 +29,7 @@ namespace Ice
 
 class UserException;
 
+/// \cond INTERNAL
 template<typename T> inline void
 patchHandle(void* addr, const ValuePtr& v)
 {
@@ -44,49 +45,139 @@ patchHandle(void* addr, const ValuePtr& v)
     _icePatchObjectPtr(*p, v); // Generated _icePatchObjectPtr function, necessary for forward declarations.
 #endif
 }
+/// \endcond
 
+/**
+ * Interface for input streams used to extract Slice types from a sequence of bytes.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API InputStream : public IceInternal::Buffer
 {
 public:
 
     typedef size_t size_type;
+
+    /**
+     * Signature for a patch function, used to receive an unmarshaled value.
+     * @param addr The target address.
+     * @param v The unmarshaled value.
+     */
     typedef void (*PatchFunc)(void*, const ValuePtr&);
 
-    //
-    // These constructors use the latest encoding version. Without a communicator, the stream
-    // will not be able to unmarshal a proxy. For other unmarshaling tasks, you can provide
-    // Helpers for objects that are normally provided by a communicator.
-    //
+    /**
+     * Constructs a stream using the latest encoding version but without a communicator.
+     * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks,
+     * you can provide Helpers for objects that are normally provided by a communicator.
+     * You can supply a communicator later by calling initialize().
+     */
     InputStream();
-    InputStream(const std::vector<Byte>&);
-    InputStream(const std::pair<const Byte*, const Byte*>&);
-    InputStream(IceInternal::Buffer&, bool = false);
-
-    //
-    // These constructors use the communicator's default encoding version.
-    //
-    InputStream(const CommunicatorPtr&);
-    InputStream(const CommunicatorPtr&, const std::vector<Byte>&);
-    InputStream(const CommunicatorPtr&, const std::pair<const Byte*, const Byte*>&);
-    InputStream(const CommunicatorPtr&, IceInternal::Buffer&, bool = false);
 
-    //
-    // These constructors use the given encoding version. Without a communicator, the stream
-    // will not be able to unmarshal a proxy. For other unmarshaling tasks, you can provide
-    // Helpers for objects that are normally provided by a communicator.
-    //
-    InputStream(const EncodingVersion&);
-    InputStream(const EncodingVersion&, const std::vector<Byte>&);
-    InputStream(const EncodingVersion&, const std::pair<const Byte*, const Byte*>&);
+    /**
+     * Constructs a stream using the latest encoding version but without a communicator.
+     * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks,
+     * you can provide Helpers for objects that are normally provided by a communicator.
+     * You can supply a communicator later by calling initialize().
+     * @param bytes The encoded data.
+     */
+    InputStream(const std::vector<Byte>& bytes);
+
+    /**
+     * Constructs a stream using the latest encoding version but without a communicator.
+     * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks,
+     * you can provide Helpers for objects that are normally provided by a communicator.
+     * You can supply a communicator later by calling initialize().
+     * @param bytes The encoded data.
+     */
+    InputStream(const std::pair<const Byte*, const Byte*>& bytes);
+
+    /// \cond INTERNAL
+    InputStream(IceInternal::Buffer&, bool = false);
+    /// \endcond
+
+    /**
+     * Constructs a stream using the communicator's default encoding version.
+     * @param communicator The communicator to use for unmarshaling tasks.
+     */
+    InputStream(const CommunicatorPtr& communicator);
+
+    /**
+     * Constructs a stream using the communicator's default encoding version.
+     * @param communicator The communicator to use for unmarshaling tasks.
+     * @param bytes The encoded data.
+     */
+    InputStream(const CommunicatorPtr& communicator, const std::vector<Byte>& bytes);
+
+    /**
+     * Constructs a stream using the communicator's default encoding version.
+     * @param communicator The communicator to use for unmarshaling tasks.
+     * @param bytes The encoded data.
+     */
+    InputStream(const CommunicatorPtr& communicator, const std::pair<const Byte*, const Byte*>& bytes);
+
+    /// \cond INTERNAL
+    InputStream(const CommunicatorPtr& communicator, IceInternal::Buffer&, bool = false);
+    /// \endcond
+
+    /**
+     * Constructs a stream using the given encoding version but without a communicator.
+     * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks,
+     * you can provide Helpers for objects that are normally provided by a communicator.
+     * You can supply a communicator later by calling initialize().
+     * @param version The encoding version used to encode the data to be unmarshaled.
+     */
+    InputStream(const EncodingVersion& version);
+
+    /**
+     * Constructs a stream using the given encoding version but without a communicator.
+     * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks,
+     * you can provide Helpers for objects that are normally provided by a communicator.
+     * You can supply a communicator later by calling initialize().
+     * @param version The encoding version used to encode the data to be unmarshaled.
+     * @param bytes The encoded data.
+     */
+    InputStream(const EncodingVersion& version, const std::vector<Byte>& bytes);
+
+    /**
+     * Constructs a stream using the given encoding version but without a communicator.
+     * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks,
+     * you can provide Helpers for objects that are normally provided by a communicator.
+     * You can supply a communicator later by calling initialize().
+     * @param version The encoding version used to encode the data to be unmarshaled.
+     * @param bytes The encoded data.
+     */
+    InputStream(const EncodingVersion& version, const std::pair<const Byte*, const Byte*>& bytes);
+
+    /// \cond INTERNAL
     InputStream(const EncodingVersion&, IceInternal::Buffer&, bool = false);
-
-    //
-    // These constructors use the given communicator and encoding version.
-    //
-    InputStream(const CommunicatorPtr&, const EncodingVersion&);
-    InputStream(const CommunicatorPtr&, const EncodingVersion&, const std::vector<Byte>&);
-    InputStream(const CommunicatorPtr&, const EncodingVersion&, const std::pair<const Byte*, const Byte*>&);
+    /// \endcond
+
+    /**
+     * Constructs a stream using the given communicator and encoding version.
+     * @param communicator The communicator to use for unmarshaling tasks.
+     * @param version The encoding version used to encode the data to be unmarshaled.
+     */
+    InputStream(const CommunicatorPtr& communicator, const EncodingVersion& version);
+
+    /**
+     * Constructs a stream using the given communicator and encoding version.
+     * @param communicator The communicator to use for unmarshaling tasks.
+     * @param version The encoding version used to encode the data to be unmarshaled.
+     * @param bytes The encoded data.
+     */
+    InputStream(const CommunicatorPtr& communicator, const EncodingVersion& version, const std::vector<Byte>& bytes);
+
+    /**
+     * Constructs a stream using the given communicator and encoding version.
+     * @param communicator The communicator to use for unmarshaling tasks.
+     * @param version The encoding version used to encode the data to be unmarshaled.
+     * @param bytes The encoded data.
+     */
+    InputStream(const CommunicatorPtr& communicator, const EncodingVersion& version,
+                const std::pair<const Byte*, const Byte*>& bytes);
+
+    /// \cond INTERNAL
     InputStream(const CommunicatorPtr&, const EncodingVersion&, IceInternal::Buffer&, bool = false);
+    /// \endcond
 
     ~InputStream()
     {
@@ -106,75 +197,184 @@ public:
 #endif
     }
 
-    //
-    // Use initialize() if you originally constructed the stream without a communicator.
-    //
-    void initialize(const CommunicatorPtr&);
-    void initialize(const CommunicatorPtr&, const EncodingVersion&);
-
+    /**
+     * Initializes the stream to use the communicator's default encoding version.
+     * Use initialize() if you originally constructed the stream without a communicator.
+     * @param communicator The communicator to use for unmarshaling tasks.
+     */
+    void initialize(const CommunicatorPtr& communicator);
+
+    /**
+     * Initializes the stream to use the given communicator and encoding version.
+     * Use initialize() if you originally constructed the stream without a communicator.
+     * @param communicator The communicator to use for unmarshaling tasks.
+     * @param version The encoding version used to encode the data to be unmarshaled.
+     */
+    void initialize(const CommunicatorPtr& communicator, const EncodingVersion& version);
+
+    /**
+     * Releases any data retained by encapsulations.
+     */
     void clear();
 
+    /// \cond INTERNAL
     //
     // Must return Instance*, because we don't hold an InstancePtr for
     // optimization reasons (see comments below).
     //
     IceInternal::Instance* instance() const { return _instance; } // Inlined for performance reasons.
-
-    void setValueFactoryManager(const ValueFactoryManagerPtr&);
-
-    void setLogger(const LoggerPtr&);
-
+    /// \endcond
+
+    /**
+     * Sets the value factory manager to use when unmarshaling value instances. If the stream
+     * was initialized with a communicator, the communicator's value factory manager will
+     * be used by default.
+     *
+     * @param vfm The value factory manager.
+     */
+    void setValueFactoryManager(const ValueFactoryManagerPtr& vfm);
+
+    /**
+     * Sets the logger to use when logging trace messages. If the stream
+     * was initialized with a communicator, the communicator's logger will
+     * be used by default.
+     *
+     * @param logger The logger to use for logging trace messages.
+     */
+    void setLogger(const LoggerPtr& logger);
+
+    /**
+     * Sets the compact ID resolver to use when unmarshaling value and exception
+     * instances. If the stream was initialized with a communicator, the communicator's
+     * resolver will be used by default.
+     *
+     * @param r The compact ID resolver.
+     */
 #ifdef ICE_CPP11_MAPPING
-    void setCompactIdResolver(std::function<std::string(int)>);
+    void setCompactIdResolver(std::function<std::string(int)> r);
 #else
-    void setCompactIdResolver(const CompactIdResolverPtr&);
+    void setCompactIdResolver(const CompactIdResolverPtr& r);
 #endif
 
 #ifndef ICE_CPP11_MAPPING
-    void setCollectObjects(bool);
+    /**
+     * Indicates whether to mark instances of Slice classes as collectable. If the stream is
+     * initialized with a communicator, this setting defaults to the value of the
+     * Ice.CollectObjects property, otherwise the setting defaults to false.
+     * @param b True to mark instances as collectable, false otherwise.
+     */
+    void setCollectObjects(bool b);
 #endif
 
-    void setSliceValues(bool);
-
-    void setTraceSlicing(bool);
-
-    void setClassGraphDepthMax(size_t);
-
+    /**
+     * Indicates whether to slice instances of Slice classes to a known Slice type when a more
+     * derived type is unknown. An instance is "sliced" when no static information is available
+     * for a Slice type ID and no factory can be found for that type, resulting in the creation
+     * of an instance of a less-derived type. If slicing is disabled in this situation, the
+     * stream raises the exception NoValueFactoryException. The default behavior is to allow slicing.
+     * @param b True to enable slicing, false otherwise.
+     */
+    void setSliceValues(bool b);
+
+    /**
+     * Indicates whether to log messages when instances of Slice classes are sliced. If the stream
+     * is initialized with a communicator, this setting defaults to the value of the Ice.Trace.Slicing
+     * property, otherwise the setting defaults to false.
+     * @param b True to enable logging, false otherwise.
+     */
+    void setTraceSlicing(bool b);
+
+    /**
+     * Sets an upper limit on the depth of a class graph. If this limit is exceeded during
+     * unmarshaling, the stream raises MarshalException.
+     * @param n The maximum depth.
+     */
+    void setClassGraphDepthMax(size_t n);
+
+    /**
+     * Obtains the closure data associated with this stream.
+     * @return The data as a void pointer.
+     */
     void* getClosure() const;
-    void* setClosure(void*);
-
-    void swap(InputStream&);
 
+    /**
+     * Associates closure data with this stream.
+     * @param p The data as a void pointer.
+     * @return The previous closure data, or nil.
+     */
+    void* setClosure(void* p);
+
+    /**
+     * Swaps the contents of one stream with another.
+     *
+     * @param other The other stream.
+     */
+    void swap(InputStream& other);
+
+    /// \cond INTERNAL
     void resetEncapsulation();
+    /// \endcond
 
+    /**
+     * Resizes the stream to a new size.
+     *
+     * @param sz The new size.
+     */
     void resize(Container::size_type sz)
     {
         b.resize(sz);
         i = b.end();
     }
 
+    /**
+     * Marks the start of a class instance.
+     */
     void startValue()
     {
         assert(_currentEncaps && _currentEncaps->decoder);
         _currentEncaps->decoder->startInstance(ValueSlice);
     }
+
+    /**
+     * Marks the end of a class instance.
+     *
+     * @param preserve Pass true and the stream will preserve the unknown slices of the instance, or false
+     * to discard the unknown slices.
+     * @return An object that encapsulates the unknown slice data.
+     */
     SlicedDataPtr endValue(bool preserve)
     {
         assert(_currentEncaps && _currentEncaps->decoder);
         return _currentEncaps->decoder->endInstance(preserve);
     }
 
+    /**
+     * Marks the start of a user exception.
+     */
     void startException()
     {
         assert(_currentEncaps && _currentEncaps->decoder);
         _currentEncaps->decoder->startInstance(ExceptionSlice);
     }
+
+    /**
+     * Marks the end of a user exception.
+     *
+     * @param preserve Pass true and the stream will preserve the unknown slices of the exception, or false
+     * to discard the unknown slices.
+     * @return An object that encapsulates the unknown slice data.
+     */
     SlicedDataPtr endException(bool preserve)
     {
         assert(_currentEncaps && _currentEncaps->decoder);
         return _currentEncaps->decoder->endInstance(preserve);
     }
 
+    /**
+     * Reads the start of an encapsulation.
+     *
+     * @return The encoding version used by the encapsulation.
+     */
     const EncodingVersion& startEncapsulation()
     {
         Encaps* oldEncaps = _currentEncaps;
@@ -214,6 +414,9 @@ public:
         return _currentEncaps->encoding;
     }
 
+    /**
+     * Ends the current encapsulation.
+     */
     void endEncapsulation()
     {
         assert(_currentEncaps);
@@ -254,6 +457,11 @@ public:
         }
     }
 
+    /**
+     * Skips an empty encapsulation.
+     *
+     * @return The encapsulation's encoding version.
+     */
     EncodingVersion skipEmptyEncapsulation()
     {
         Ice::Int sz;
@@ -286,6 +494,13 @@ public:
         return encoding;
     }
 
+    /**
+     * Returns a blob of bytes representing an encapsulation.
+     *
+     * @param v A pointer into the internal marshaling buffer representing the start of the encoded encapsulation.
+     * @param sz The number of bytes in the encapsulation.
+     * @return encoding The encapsulation's encoding version.
+     */
     EncodingVersion readEncapsulation(const Byte*& v, Int& sz)
     {
         EncodingVersion encoding;
@@ -305,32 +520,71 @@ public:
         return encoding;
     }
 
+    /**
+     * Determines the current encoding version.
+     *
+     * @return The encoding version.
+     */
     const EncodingVersion& getEncoding() const
     {
         return _currentEncaps ? _currentEncaps->encoding : _encoding;
     }
 
+    /**
+     * Determines the size of the current encapsulation, excluding the encapsulation header.
+     *
+     * @return The size of the encapsulated data.
+     */
     Int getEncapsulationSize();
+
+    /**
+     * Skips over an encapsulation.
+     *
+     * @return The encoding version of the skipped encapsulation.
+     */
     EncodingVersion skipEncapsulation();
 
+    /**
+     * Reads the start of a value or exception slice.
+     *
+     * @return The Slice type ID for this slice.
+     */
     std::string startSlice()
     {
         assert(_currentEncaps && _currentEncaps->decoder);
         return _currentEncaps->decoder->startSlice();
     }
+
+    /**
+     * Indicates that the end of a value or exception slice has been reached.
+     */
     void endSlice()
     {
         assert(_currentEncaps && _currentEncaps->decoder);
         _currentEncaps->decoder->endSlice();
     }
+
+    /**
+     * Skips over a value or exception slice.
+     */
     void skipSlice()
     {
         assert(_currentEncaps && _currentEncaps->decoder);
         _currentEncaps->decoder->skipSlice();
     }
 
+    /**
+     * Indicates that unmarshaling is complete, except for any class instances. The application must call this method
+     * only if the stream actually contains class instances. Calling readPendingValues triggers the
+     * patch callbacks to inform the application that unmarshaling of an instance is complete.
+     */
     void readPendingValues();
 
+    /**
+     * Extracts a size from the stream.
+     *
+     * @return The extracted size.
+     */
     Int readSize() // Inlined for performance reasons.
     {
         Byte byte;
@@ -352,10 +606,28 @@ public:
         }
     }
 
-    Int readAndCheckSeqSize(int);
-
-    void readBlob(std::vector<Byte>&, Int);
-
+    /**
+     * Reads and validates a sequence size.
+     *
+     * @param minSize The minimum size required by the sequence type.
+     * @return The extracted size.
+     */
+    Int readAndCheckSeqSize(int minSize);
+
+    /**
+     * Reads a blob of bytes from the stream.
+     *
+     * @param bytes The vector to hold a copy of the bytes from the marshaling buffer.
+     * @param sz The number of bytes to read.
+     */
+    void readBlob(std::vector<Byte>& bytes, Int sz);
+
+    /**
+     * Reads a blob of bytes from the stream.
+     *
+     * @param v A pointer into the internal marshaling buffer representing the start of the blob.
+     * @param sz The number of bytes to read.
+     */
     void readBlob(const Byte*& v, Container::size_type sz)
     {
         if(sz > 0)
@@ -373,11 +645,20 @@ public:
         }
     }
 
+    /**
+     * Reads a data value from the stream.
+     * @param v Holds the extracted data.
+     */
     template<typename T> void read(T& v)
     {
         StreamHelper<T, StreamableTraits<T>::helper>::read(this, v);
     }
 
+    /**
+     * Reads an optional data value from the stream.
+     * @param tag The tag ID.
+     * @param v Holds the extracted data (if any).
+     */
     template<typename T> void read(Int tag, IceUtil::Optional<T>& v)
     {
         if(readOptional(tag, StreamOptionalHelper<T,
@@ -401,6 +682,10 @@ public:
 
 #ifdef ICE_CPP11_MAPPING
 
+    /**
+     * Extracts a sequence of data values from the stream.
+     * @param v A pair of pointers representing the beginning and end of the sequence elements.
+     */
     template<typename T> void read(std::pair<const T*, const T*>& v)
     {
         auto holder = new std::vector<T>;
@@ -418,23 +703,35 @@ public:
         }
     }
 
+    /**
+     * Reads a list of mandatory data values.
+     */
     template<typename T> void readAll(T& v)
     {
         read(v);
     }
 
+    /**
+     * Reads a list of mandatory data values.
+     */
     template<typename T, typename... Te> void readAll(T& v, Te&... ve)
     {
         read(v);
         readAll(ve...);
     }
 
+    /**
+     * Reads a list of optional data values.
+     */
     template<typename T>
     void readAll(std::initializer_list<int> tags, IceUtil::Optional<T>& v)
     {
         read(*(tags.begin() + tags.size() - 1), v);
     }
 
+    /**
+     * Reads a list of optional data values.
+     */
     template<typename T, typename... Te>
     void readAll(std::initializer_list<int> tags, IceUtil::Optional<T>& v, IceUtil::Optional<Te>&... ve)
     {
@@ -445,7 +742,13 @@ public:
 
 #endif
 
-    // Read type and tag for optionals
+    /**
+     * Determine if an optional value is available for reading.
+     *
+     * @param tag The tag associated with the value.
+     * @param expectedFormat The optional format for the value.
+     * @return True if the value is present, false otherwise.
+     */
     bool readOptional(Int tag, OptionalFormat expectedFormat)
     {
         assert(_currentEncaps);
@@ -459,7 +762,10 @@ public:
         }
     }
 
-    // Byte
+    /**
+     * Reads a byte from the stream.
+     * @param v The extracted byte.
+     */
     void read(Byte& v)
     {
         if(i >= b.end())
@@ -468,19 +774,38 @@ public:
         }
         v = *i++;
     }
-    void read(std::vector<Byte>&);
-    void read(std::pair<const Byte*, const Byte*>&);
+
+    /**
+     * Reads a sequence of bytes from the stream.
+     * @param v A vector to hold a copy of the bytes.
+     */
+    void read(std::vector<Byte>& v);
+
+    /**
+     * Reads a sequence of bytes from the stream.
+     * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the
+     * sequence elements.
+     */
+    void read(std::pair<const Byte*, const Byte*>& v);
 
 #ifndef ICE_CPP11_MAPPING
-    // This method is useful for generic stream helpers
-    void read(std::pair<const Byte*, const Byte*>& p, ::IceUtil::ScopedArray<Byte>& result)
+    /**
+     * Reads a sequence of bytes from the stream.
+     * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the
+     * sequence elements.
+     * @param arr A scoped array.
+     */
+    void read(std::pair<const Byte*, const Byte*>& v, ::IceUtil::ScopedArray<Byte>& arr)
     {
-        result.reset();
-        read(p);
+        arr.reset();
+        read(v);
     }
 #endif
 
-    // Bool
+    /**
+     * Reads a bool from the stream.
+     * @param v The extracted bool.
+     */
     void read(bool& v)
     {
         if(i >= b.end())
@@ -489,24 +814,61 @@ public:
         }
         v = (0 != *i++);
     }
-    void read(std::vector<bool>&);
+
+    /**
+     * Reads a sequence of boolean values from the stream.
+     * @param v A vector to hold a copy of the boolean values.
+     */
+    void read(std::vector<bool>& v);
 
 #ifdef ICE_CPP11_MAPPING
-    void read(std::pair<const bool*, const bool*>&);
+    /**
+     * Reads a sequence of boolean values from the stream.
+     * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the
+     * sequence elements.
+     */
+    void read(std::pair<const bool*, const bool*>& v);
 #else
-    void read(std::pair<const bool*, const bool*>&, ::IceUtil::ScopedArray<bool>&);
+    /**
+     * Reads a sequence of boolean values from the stream.
+     * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the
+     * sequence elements.
+     * @param arr A scoped array.
+     */
+    void read(std::pair<const bool*, const bool*>& v, ::IceUtil::ScopedArray<bool>& arr);
 #endif
 
-    // Short
-    void read(Short&);
-    void read(std::vector<Short>&);
+    /**
+     * Reads a short from the stream.
+     * @param v The extracted short.
+     */
+    void read(Short& v);
+
+    /**
+     * Reads a sequence of shorts from the stream.
+     * @param v A vector to hold a copy of the short values.
+     */
+    void read(std::vector<Short>& v);
+
 #ifdef ICE_CPP11_MAPPING
-    void read(std::pair<const short*, const short*>&);
+    /**
+     * Reads a sequence of boolean values from the stream.
+     * @param v A pair of pointers representing the start and end of the sequence elements.
+     */
+    void read(std::pair<const short*, const short*>& v);
 #else
-    void read(std::pair<const Short*, const Short*>&, ::IceUtil::ScopedArray<Short>&);
+    /**
+     * Reads a sequence of shorts from the stream.
+     * @param v A pair of pointers representing the start and end of the sequence elements.
+     * @param arr A scoped array.
+     */
+    void read(std::pair<const Short*, const Short*>& v, ::IceUtil::ScopedArray<Short>& arr);
 #endif
 
-    // Int
+    /**
+     * Reads an int from the stream.
+     * @param v The extracted int.
+     */
     void read(Int& v) // Inlined for performance reasons.
     {
         if(b.end() - i < static_cast<int>(sizeof(Int)))
@@ -530,63 +892,175 @@ public:
 #endif
     }
 
-    void read(std::vector<Int>&);
+    /**
+     * Reads a sequence of ints from the stream.
+     * @param v A vector to hold a copy of the int values.
+     */
+    void read(std::vector<Int>& v);
+
 #ifdef ICE_CPP11_MAPPING
-    void read(std::pair<const int*, const int*>&);
+    /**
+     * Reads a sequence of ints from the stream.
+     * @param v A pair of pointers representing the start and end of the sequence elements.
+     */
+    void read(std::pair<const int*, const int*>& v);
 #else
-    void read(std::pair<const Int*, const Int*>&, ::IceUtil::ScopedArray<Int>&);
+    /**
+     * Reads a sequence of ints from the stream.
+     * @param v A pair of pointers representing the start and end of the sequence elements.
+     * @param arr A scoped array.
+     */
+    void read(std::pair<const Int*, const Int*>& v, ::IceUtil::ScopedArray<Int>& arr);
 #endif
 
-    // Long
+    /**
+     * Reads a long from the stream.
+     * @param v The extracted long.
+     */
+    void read(Long& v);
+
+    /**
+     * Reads a sequence of longs from the stream.
+     * @param v A vector to hold a copy of the long values.
+     */
+    void read(std::vector<Long>& v);
 
-    void read(Long&);
-    void read(std::vector<Long>&);
 #ifdef ICE_CPP11_MAPPING
-    void read(std::pair<const long long*, const long long*>&);
+    /**
+     * Reads a sequence of longs from the stream.
+     * @param v A pair of pointers representing the start and end of the sequence elements.
+     */
+    void read(std::pair<const long long*, const long long*>& v);
 #else
-    void read(std::pair<const Long*, const Long*>&, ::IceUtil::ScopedArray<Long>&);
+    /**
+     * Reads a sequence of longs from the stream.
+     * @param v A pair of pointers representing the start and end of the sequence elements.
+     * @param arr A scoped array.
+     */
+    void read(std::pair<const Long*, const Long*>& v, ::IceUtil::ScopedArray<Long>& arr);
 #endif
 
-    // Float
-    void read(Float&);
-    void read(std::vector<Float>&);
+    /**
+     * Reads a float from the stream.
+     * @param v The extracted float.
+     */
+    void read(Float& v);
+
+    /**
+     * Reads a sequence of floats from the stream.
+     * @param v A vector to hold a copy of the float values.
+     */
+    void read(std::vector<Float>& v);
+
 #ifdef ICE_CPP11_MAPPING
-    void read(std::pair<const float*, const float*>&);
+    /**
+     * Reads a sequence of floats from the stream.
+     * @param v A pair of pointers representing the start and end of the sequence elements.
+     */
+    void read(std::pair<const float*, const float*>& v);
 #else
-    void read(std::pair<const Float*, const Float*>&, ::IceUtil::ScopedArray<Float>&);
+    /**
+     * Reads a sequence of floats from the stream.
+     * @param v A pair of pointers representing the start and end of the sequence elements.
+     * @param arr A scoped array.
+     */
+    void read(std::pair<const Float*, const Float*>& v, ::IceUtil::ScopedArray<Float>& arr);
 #endif
 
-    // Double
-    void read(Double&);
-    void read(std::vector<Double>&);
+    /**
+     * Reads a double from the stream.
+     * @param v The extracted double.
+     */
+    void read(Double& v);
+
+    /**
+     * Reads a sequence of doubles from the stream.
+     * @param v A vector to hold a copy of the double values.
+     */
+    void read(std::vector<Double>& v);
+
 #ifdef ICE_CPP11_MAPPING
-    void read(std::pair<const double*, const double*>&);
+    /**
+     * Reads a sequence of doubles from the stream.
+     * @param v A pair of pointers representing the start and end of the sequence elements.
+     */
+    void read(std::pair<const double*, const double*>& v);
 #else
-    void read(std::pair<const Double*, const Double*>&, ::IceUtil::ScopedArray<Double>&);
+    /**
+     * Reads a sequence of doubles from the stream.
+     * @param v A pair of pointers representing the start and end of the sequence elements.
+     * @param arr A scoped array.
+     */
+    void read(std::pair<const Double*, const Double*>& v, ::IceUtil::ScopedArray<Double>& arr);
 #endif
 
-    // String
+    /**
+     * Reads a string from the stream.
+     * @param v The extracted string.
+     * @param convert Determines whether the string is processed by the string converter, if one
+     * is installed. The default behavior is to convert strings.
+     */
     void read(std::string& v, bool convert = true);
 
 #ifdef ICE_CPP11_MAPPING
+    /**
+     * Reads a string from the stream.
+     * @param vdata A pointer to the beginning of the string.
+     * @param vsize The number of bytes in the string.
+     * @param convert Determines whether the string is processed by the string converter, if one
+     * is installed. The default behavior is to convert strings.
+     */
     void read(const char*& vdata, size_t& vsize, bool convert = true);
 #else
     // For custom strings, convert = false
+    /**
+     * Reads a string from the stream. String conversion is disabled.
+     * @param vdata A pointer to the beginning of the string.
+     * @param vsize The number of bytes in the string.
+     */
     void read(const char*& vdata, size_t& vsize);
 
     // For custom strings, convert = true
+    /**
+     * Reads a string from the stream. String conversion is enabled.
+     * @param vdata A pointer to the beginning of the string.
+     * @param vsize The number of bytes in the string.
+     * @param holder Holds the string contents.
+     */
     void read(const char*& vdata, size_t& vsize, std::string& holder);
 #endif
 
-    void read(std::vector<std::string>&, bool = true);
-
-    void read(std::wstring&);
-    void read(std::vector<std::wstring>&);
+    /**
+     * Reads a sequence of strings from the stream.
+     * @param v The extracted string sequence.
+     * @param convert Determines whether strings are processed by the string converter, if one
+     * is installed. The default behavior is to convert the strings.
+     */
+    void read(std::vector<std::string>& v, bool convert = true);
+
+    /**
+     * Reads a wide string from the stream.
+     * @param v The extracted string.
+     */
+    void read(std::wstring& v);
+
+    /**
+     * Reads a sequence of wide strings from the stream.
+     * @param v The extracted sequence.
+     */
+    void read(std::vector<std::wstring>& v);
 
-    // Proxy
 #ifdef ICE_CPP11_MAPPING
+    /**
+     * Reads a proxy from the stream.
+     * @return The proxy as the base ObjectPrx type.
+     */
     std::shared_ptr<ObjectPrx> readProxy();
 
+    /**
+     * Reads a typed proxy from the stream.
+     * @param v The proxy as a user-defined type.
+     */
     template<typename T, typename ::std::enable_if<::std::is_base_of<ObjectPrx, T>::value>::type* = nullptr>
     void read(::std::shared_ptr<T>& v)
     {
@@ -602,14 +1076,26 @@ public:
         }
     }
 #else
-    void read(ObjectPrx&);
+    /**
+     * Reads a proxy from the stream.
+     * @param v The proxy as the base ObjectPrx type.
+     */
+    void read(ObjectPrx& v);
+
+    /**
+     * Reads a typed proxy from the stream.
+     * @param v The proxy as a user-defined type.
+     */
     template<typename T> void read(IceInternal::ProxyHandle<T>& v)
     {
         _readProxy(this, v); // Generated _readProxy method, necessary for forward declarations.
     }
 #endif
 
-    // Class
+    /**
+     * Reads a value (instance of a Slice class) from the stream.
+     * @param v The instance.
+     */
 #ifdef ICE_CPP11_MAPPING // C++11 mapping
     template<typename T, typename ::std::enable_if<::std::is_base_of<Value, T>::value>::type* = nullptr>
     void read(::std::shared_ptr<T>& v)
@@ -623,23 +1109,48 @@ public:
     }
 #endif
 
+    /**
+     * Reads a value (instance of a Slice class) from the stream.
+     * @param patchFunc The patch callback function.
+     * @param patchAddr Closure data passed to the callback.
+     */
     void read(PatchFunc patchFunc, void* patchAddr)
     {
         initEncaps();
         _currentEncaps->decoder->read(patchFunc, patchAddr);
     }
 
-    // Enum
-    Int readEnum(Int);
-
-    // Exception
-    void throwException(ICE_IN(ICE_DELEGATE(UserExceptionFactory)) = ICE_NULLPTR);
-
-    // Read/write/skip optionals
-    void skipOptional(OptionalFormat);
+    /**
+     * Reads an enumerator from the stream.
+     * @param maxValue The maximum enumerator value in the definition.
+     * @return The enumerator value.
+     */
+    Int readEnum(Int maxValue);
+
+    /**
+     * Extracts a user exception from the stream and throws it.
+     * @param factory If provided, this factory is given the first opportunity to instantiate
+     * the exception. If not provided, or if the factory does not throw an exception when invoked,
+     * the stream will attempt to instantiate the exception using static type information.
+     * @throws UserException The user exception that was unmarshaled.
+     */
+    void throwException(ICE_IN(ICE_DELEGATE(UserExceptionFactory)) factory = ICE_NULLPTR);
+
+    /**
+     * Skips one optional value with the given format.
+     * @param format The expected format of the optional, if present.
+     */
+    void skipOptional(OptionalFormat format);
+
+    /**
+     * Skips all remaining optional values.
+     */
     void skipOptionals();
 
-    // Skip bytes from the stream
+    /**
+     * Advances the current stream position by the given number of bytes.
+     * @param size The number of bytes to skip.
+     */
     void skip(size_type size)
     {
         if(i + size > b.end())
@@ -648,6 +1159,10 @@ public:
         }
         i += size;
     }
+
+    /**
+     * Reads a size at the current position and skips that number of bytes.
+     */
     void skipSize()
     {
         Byte bt;
@@ -658,22 +1173,32 @@ public:
         }
     }
 
+    /**
+     * Obtains the current position of the stream.
+     * @return The current position.
+     */
     size_type pos()
     {
         return i - b.begin();
     }
 
+    /**
+     * Sets a new position for the stream.
+     * @param p The new position.
+     */
     void pos(size_type p)
     {
         i = b.begin() + p;
     }
 
+    /// \cond INTERNAL
     InputStream(IceInternal::Instance*, const EncodingVersion&);
     InputStream(IceInternal::Instance*, const EncodingVersion&, IceInternal::Buffer&, bool = false);
 
     void initialize(IceInternal::Instance*, const EncodingVersion&);
 
     bool readOptImpl(Int, OptionalFormat);
+    /// \endcond
 
 private: