MongoDB: fixes for style and consistency

MongoDB/include/Poco/MongoDB/Array.h

@@ -15,62 +15,68 @@
 // SPDX-License-Identifier:	BSL-1.0
 //
 
+
 #ifndef MongoDB_Array_INCLUDED
 #define MongoDB_Array_INCLUDED
 
-#include "Poco/NumberFormatter.h"
 
+#include "Poco/NumberFormatter.h"
 #include "Poco/MongoDB/MongoDB.h"
 #include "Poco/MongoDB/Document.h"
 
+
 namespace Poco {
 namespace MongoDB {
 
-class MongoDB_API Array : public Document
-	/// Implements the BSON Array
+
+class MongoDB_API Array: public Document
+	/// This class represents a BSON Array.
 {
 public:
 	typedef SharedPtr<Array> Ptr;
 
 	Array();
-		/// Constructor
+		/// Creates an empty Array.
 
 	virtual ~Array();
-		/// Destructor
+		/// Destroys the Array.
 
 	template<typename T>
 	T get(int pos) const
-		/// Returns the element on the given index and tries to convert
-		/// it to the template type. When the element is not found, a
-		/// NotFoundException will be thrown. When the element can't be
+		/// Returns the element at the given index and tries to convert
+		/// it to the template type. If the element is not found, a
+		/// Poco::NotFoundException will be thrown. If the element cannot be
 		/// converted a BadCastException will be thrown.
 	{
 		return Document::get<T>(Poco::NumberFormatter::format(pos));
 	}
 
 	template<typename T>
-	T get(int pos, const T& def) const
-		/// Returns the element on the given index and tries to convert
-		/// it to the template type. When the element is not found, or
-		/// has the wrong type, the def argument will be returned.
+	T get(int pos, const T& deflt) const
+		/// Returns the element at the given index and tries to convert
+		/// it to the template type. If the element is not found, or
+		/// has the wrong type, the deflt argument will be returned.
 	{
-		return Document::get<T>(Poco::NumberFormatter::format(pos), def);
+		return Document::get<T>(Poco::NumberFormatter::format(pos), deflt);
 	}
 
 	Element::Ptr get(int pos) const;
-		/// Returns the element on the given index.
-		/// An empty element will be returned when the element is not found.
+		/// Returns the element at the given index.
+		/// An empty element will be returned if the element is not found.
 
 	template<typename T>
 	bool isType(int pos) const
-		/// Returns true when the type of the element equals the TypeId of ElementTrait
+		/// Returns true if the type of the element equals the TypeId of ElementTrait,
+		/// otherwise false.
 	{
 		return Document::isType<T>(Poco::NumberFormatter::format(pos));
 	}
 
 	std::string toString(int indent = 0) const;
+		/// Returns a string representation of the Array.
 };
 
+
 // BSON Embedded Array
 // spec: document
 template<>
@@ -103,4 +109,4 @@ inline void BSONWriter::write<Array::Ptr>(Array::Ptr& from)
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_Array_INCLUDED
+#endif // MongoDB_Array_INCLUDED

MongoDB/include/Poco/MongoDB/BSONReader.h

@@ -29,16 +29,17 @@ namespace MongoDB {
 
 
 class MongoDB_API BSONReader
-	/// Class for reading BSON from a Poco::BinaryReader
+	/// Class for reading BSON using a Poco::BinaryReader
 {
 public:
-	BSONReader(const Poco::BinaryReader& reader) : _reader(reader)
-		/// Constructor
+	BSONReader(const Poco::BinaryReader& reader):
+		_reader(reader)
+		/// Creates the BSONReader using the given BinaryWriter.
 	{
 	}
 
 	virtual ~BSONReader()
-		/// Destructor
+		/// Destroys the BSONReader.
 	{
 	}
 
@@ -55,11 +56,13 @@ public:
 		/// A cstring is a string terminated with a 0x00.
 
 private:
-
 	Poco::BinaryReader _reader;
 };
 
 
+//
+// inlines
+//
 inline std::string BSONReader::readCString()
 {
 	std::string val;
@@ -80,4 +83,4 @@ inline std::string BSONReader::readCString()
 } } // namespace Poco::MongoDB
 
 
-#endif //  MongoDB_BSONReader_INCLUDED
+#endif // MongoDB_BSONReader_INCLUDED

MongoDB/include/Poco/MongoDB/BSONWriter.h

@@ -29,16 +29,17 @@ namespace MongoDB {
 
 
 class MongoDB_API BSONWriter
-	/// Class for writing BSON to a Poco::BinaryWriter.
+	/// Class for writing BSON using a Poco::BinaryWriter.
 {
 public:
-	BSONWriter(const Poco::BinaryWriter& writer) : _writer(writer)
-		/// Constructor
+	BSONWriter(const Poco::BinaryWriter& writer): 
+		_writer(writer)
+		/// Creates the BSONWriter.
 	{
 	}
 
 	virtual ~BSONWriter()
-		/// Destructor
+		/// Destroys the BSONWriter.
 	{
 	}
 
@@ -52,13 +53,16 @@ public:
 
 	void writeCString(const std::string& value);
 		/// Writes a cstring to the writer. A cstring is a string
-		/// terminated with 0x00
+		/// terminated a null character.
 
 private:
 	Poco::BinaryWriter _writer;
 };
 
 
+//
+// inlines
+//
 inline void BSONWriter::writeCString(const std::string& value)
 {
 	_writer.writeRaw(value);
@@ -69,4 +73,4 @@ inline void BSONWriter::writeCString(const std::string& value)
 } } // namespace Poco::MongoDB
 
 
-#endif //  MongoDB_BSONWriter_INCLUDED
+#endif // MongoDB_BSONWriter_INCLUDED

MongoDB/include/Poco/MongoDB/Binary.h

@@ -35,47 +35,49 @@ namespace MongoDB {
 
 
 class MongoDB_API Binary
-	/// Implements BSON Binary. It's a wrapper around a Poco::Buffer<unsigned char>.
+	/// Implements BSON Binary.
+	///
+	/// A Binary stores its data in a Poco::Buffer<unsigned char>.
 {
 public:
 	typedef SharedPtr<Binary> Ptr;
 
 	Binary();
-		/// Constructor
+		/// Creates an empty Binary with subtype 0.
 
 	Binary(Poco::Int32 size, unsigned char subtype);
-		/// Constructor
+		/// Creates a Binary with a buffer of the given size and the given subtype.
 
 	Binary(const UUID& uuid);
-		/// Constructor for setting a UUID in a binary element
+		/// Creates a Binary containing an UUID.
 		
 	Binary(const std::string& data, unsigned char subtype = 0);
-		/// Constructor for getting binary data from a string.
+		/// Creates a Binary with the contents of the given string and the given subtype.
 		
 	Binary(const void* data, Poco::Int32 size, unsigned char subtype = 0);
-		/// Constructor for getting binary data from a buffer.		
+		/// Creates a Binary with the contents of the given buffer and the given subtype.		
 
 	virtual ~Binary();
-		/// Destructor
+		/// Destroys the Binary.
 
 	Buffer<unsigned char>& buffer();
-		/// Returns a reference to the buffer
+		/// Returns a reference to the internal buffer
 
 	unsigned char subtype() const;
-		/// Returns the subtype
+		/// Returns the subtype.
 
 	void subtype(unsigned char type);
-		/// Sets the subtype
+		/// Sets the subtype.
 
 	std::string toString(int indent = 0) const;
-		/// Returns the binary encoded in Base64
+		/// Returns the contents of the Binary as Base64-encoded string.
 		
 	std::string toRawString() const;
-		/// Returns the raw content as a string.
+		/// Returns the raw content of the Binary as a string.
 
 	UUID uuid() const;
 		/// Returns the UUID when the binary subtype is 0x04.
-		/// Otherwise BadCastException will be thrown
+		/// Otherwise, throws a Poco::BadCastException.
 
 private:
 	Buffer<unsigned char> _buffer;
@@ -83,6 +85,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline unsigned char Binary::subtype() const
 {
 	return _subtype;

MongoDB/include/Poco/MongoDB/Connection.h

@@ -33,60 +33,80 @@ namespace MongoDB {
 
 class MongoDB_API Connection
 	/// Represents a connection to a MongoDB server
+	/// using the MongoDB wire protocol.
+	/// 
+	/// See https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/
+	/// for more information on the wire protocol.
 {
 public:
 	typedef Poco::SharedPtr<Connection> Ptr;
 
 	Connection();
-		/// Default constructor. Use this when you want to
-		/// connect later on.
+		/// Creates an unconnected Connection.
+		///
+		/// Use this when you want to connect later on.
 
 	Connection(const std::string& hostAndPort);
-		/// Constructor which connects to the given MongoDB host/port.
+		/// Creates a Connection connected to the given MongoDB instance at host:port.
+		///
 		/// The host and port must be separated with a colon.
 
 	Connection(const std::string& host, int port);
-		/// Constructor which connects to the given MongoDB host/port.
+		/// Creates a Connection connected to the given MongoDB instance at host and port.
 
-	Connection(const Net::SocketAddress& addrs);
-		/// Constructor which connects to the given MongoDB host/port.
+	Connection(const Poco::Net::SocketAddress& addrs);
+		/// Creates a Connection connected to the given MongoDB instance at the given address.
+
+	Connection(const Poco::Net::StreamSocket& socket);
+		/// Creates a Connection connected to the given MongoDB instance using the given socket,
+		/// which must already be connected.
 
 	virtual ~Connection();
-		/// Destructor
+		/// Destroys the Connection.
 
-	Net::SocketAddress address() const;
-		/// Returns the address of the MongoDB connection
+	Poco::Net::SocketAddress address() const;
+		/// Returns the address of the MongoDB server.
 
 	void connect(const std::string& hostAndPort);
-		/// Connects to the given MongoDB server. The host and port must be separated
-		/// with a colon.
+		/// Connects to the given MongoDB server. 
+		///
+		/// The host and port must be separated with a colon.
 
 	void connect(const std::string& host, int port);
 		/// Connects to the given MongoDB server.
 
-	void connect(const Net::SocketAddress& addrs);
+	void connect(const Poco::Net::SocketAddress& addrs);
 		/// Connects to the given MongoDB server.
+		
+	void connect(const Poco::Net::StreamSocket& socket);
+		/// Connects using an already connected socket.
 
 	void disconnect();
-		/// Disconnects from the MongoDB server
+		/// Disconnects from the MongoDB server.
 
 	void sendRequest(RequestMessage& request);
-		/// Sends a request to the MongoDB server
-		/// Only use this when the request hasn't a response.
+		/// Sends a request to the MongoDB server.
+		/// 
+		/// Used for one-way requests without a response.
 
 	void sendRequest(RequestMessage& request, ResponseMessage& response);
 		/// Sends a request to the MongoDB server and receives the response.
-		/// Use this when a response is expected: only a query or getmore
+		/// 
+		/// Use this when a response is expected: only a "query" or "getmore"
 		/// request will return a response.
 
-private:
-	Net::SocketAddress _address;
-	Net::StreamSocket _socket;
+protected:
 	void connect();
-		/// Connects to the MongoDB server
+
+private:
+	Poco::Net::SocketAddress _address;
+	Poco::Net::StreamSocket _socket;
 };
 
 
+//
+// inlines
+//
 inline Net::SocketAddress Connection::address() const
 {
 	return _address;
@@ -96,4 +116,4 @@ inline Net::SocketAddress Connection::address() const
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_Connection_INCLUDED
+#endif // MongoDB_Connection_INCLUDED

MongoDB/include/Poco/MongoDB/Cursor.h

@@ -30,26 +30,27 @@ namespace Poco {
 namespace MongoDB {
 
 
-class MongoDB_API Cursor : public Document
-	/// Cursor is an helper class for querying multiple documents
+class MongoDB_API Cursor: public Document
+	/// Cursor is an helper class for querying multiple documents.
 {
 public:
-	Cursor(const std::string& dbname, const std::string& collectionName, QueryRequest::Flags flags = QueryRequest::QUERY_NONE);
-		/// Constructor
+	Cursor(const std::string& dbname, const std::string& collectionName, QueryRequest::Flags flags = QueryRequest::QUERY_DEFAULT);
+		/// Creates a Cursor for the given database and collection, using the specified flags.
 
-	Cursor(const std::string& fullCollectionName, QueryRequest::Flags flags = QueryRequest::QUERY_NONE);
-		/// Constructor
+	Cursor(const std::string& fullCollectionName, QueryRequest::Flags flags = QueryRequest::QUERY_DEFAULT);
+		/// Creates a Cursor for the given database and collection ("database.collection"), using the specified flags.
 
 	virtual ~Cursor();
-		/// Destructor
+		/// Destroys the Cursor.
 
 	ResponseMessage& next(Connection& connection);
-		/// Try to get the next documents. As long as ResponseMessage has a
-		/// cursor id next can be called to retrieve the next bunch of documents.
-		/// kill must be called when not all documents are needed.
+		/// Tries to get the next documents. As long as ResponseMessage has a
+		/// cursor ID next can be called to retrieve the next bunch of documents.
+		///
+		/// The cursor must be killed (see kill()) when not all documents are needed.
 
 	QueryRequest& query();
-		/// Returns the associated query
+		/// Returns the associated query.
 
 	void kill(Connection& connection);
 		/// Kills the cursor and reset it so that it can be reused.
@@ -60,6 +61,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline QueryRequest& Cursor::query()
 {
 	return _query;
@@ -69,4 +73,4 @@ inline QueryRequest& Cursor::query()
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_Cursor_INCLUDED
+#endif // MongoDB_Cursor_INCLUDED

MongoDB/include/Poco/MongoDB/Database.h

@@ -39,13 +39,13 @@ class MongoDB_API Database
 	/// the database.
 {
 public:
-	Database(const std::string& db);
-		/// Constructor
+	explicit Database(const std::string& name);
+		/// Creates a Database for the database with the given name.
 
 	virtual ~Database();
-		/// Destructor
+		/// Destroys the Database.
 		
-	bool authenticate(Connection& connection, const std::string& username, const std::string& password, const std::string& method = AUTH_MONGODB_CR);
+	bool authenticate(Connection& connection, const std::string& username, const std::string& password, const std::string& method = AUTH_SCRAM_SHA1);
 		/// Authenticates against the database using the given connection,
 		/// username and password, as well as authentication method.
 		///
@@ -54,31 +54,37 @@ public:
 		/// authentication methods.
 		///
 		/// Returns true if authentication was successful, otherwise false.
+		///
+		/// May throw a Poco::ProtocolException if authentication fails for a reason other than
+		/// invalid credentials.
 
 	Int64 count(Connection& connection, const std::string& collectionName) const;
-		/// Sends a count request for the given collection to MongoDB. When
-		/// the command fails, -1 is returned.
+		/// Sends a count request for the given collection to MongoDB. 
+		///
+		/// If the command fails, -1 is returned.
 
 	Poco::SharedPtr<Poco::MongoDB::QueryRequest> createCommand() const;
 		/// Creates a QueryRequest for a command.
 
 	Poco::SharedPtr<Poco::MongoDB::QueryRequest> createCountRequest(const std::string& collectionName) const;
-		/// Creates a QueryRequest to count the given collection. The collectionname must not contain
-		/// the database name!
+		/// Creates a QueryRequest to count the given collection. 
+		/// The collectionname must not contain the database name.
 
 	Poco::SharedPtr<Poco::MongoDB::DeleteRequest> createDeleteRequest(const std::string& collectionName) const;
 		/// Creates a DeleteRequest to delete documents in the given collection.
-		/// The collectionname must not contain the database name!
+		/// The collectionname must not contain the database name.
 
 	Poco::SharedPtr<Poco::MongoDB::InsertRequest> createInsertRequest(const std::string& collectionName) const;
 		/// Creates an InsertRequest to insert new documents in the given collection.
-		/// The collectionname must not contain the database name!
+		/// The collectionname must not contain the database name.
 
 	Poco::SharedPtr<Poco::MongoDB::QueryRequest> createQueryRequest(const std::string& collectionName) const;
-		/// Creates a QueryRequest. The collectionname must not contain the database name!
+		/// Creates a QueryRequest. 
+		/// The collectionname must not contain the database name.
 
 	Poco::SharedPtr<Poco::MongoDB::UpdateRequest> createUpdateRequest(const std::string& collectionName) const;
-		/// Creates an UpdateRequest. The collectionname must not contain the database name!
+		/// Creates an UpdateRequest. 
+		/// The collectionname must not contain the database name.
 
 	Poco::MongoDB::Document::Ptr ensureIndex(Connection& connection,
 		const std::string& collection,
@@ -92,7 +98,7 @@ public:
 		/// For more info look at the ensureIndex information on the MongoDB website.
 
 	Document::Ptr getLastErrorDoc(Connection& connection) const;
-		/// Sends the getLastError command to the database and returns the document
+		/// Sends the getLastError command to the database and returns the error document.
 
 	std::string getLastError(Connection& connection) const;
 		/// Sends the getLastError command to the database and returns the err element
@@ -113,6 +119,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline Poco::SharedPtr<Poco::MongoDB::QueryRequest> Database::createCommand() const
 {
 	Poco::SharedPtr<Poco::MongoDB::QueryRequest> cmd = createQueryRequest("$cmd");

MongoDB/include/Poco/MongoDB/DeleteRequest.h

@@ -29,51 +29,57 @@ namespace Poco {
 namespace MongoDB {
 
 
-class MongoDB_API DeleteRequest : public RequestMessage
-	/// Class for creating an OP_DELETE client request. This request
-	/// is used to delete one ore more documents from a database.
+class MongoDB_API DeleteRequest: public RequestMessage
+	/// A DeleteRequest is used to delete one ore more documents from a database.
 	///
 	/// Specific flags for this request
-	///  - DELETE_NONE
-	///      No flags
-	///  - DELETE_SINGLE_REMOVE
-	///      Delete only the first document
+	///   - DELETE_DEFAULT: default delete operation
+	///   - DELETE_SINGLE_REMOVE: delete only the first document
 {
 public:
-	typedef enum
+	enum Flags
 	{
-		DELETE_NONE = 0,
-		DELETE_SINGLE_REMOVE = 1
-	} Flags;
+		DELETE_DEFAULT = 0,
+			/// Default
 
-	DeleteRequest(const std::string& collectionName, Flags flags = DELETE_NONE);
-		/// Constructor. The full collection name is the concatenation of the database 
+		DELETE_SINGLE_REMOVE = 1
+			/// Delete only the first document.
+	};
+
+	DeleteRequest(const std::string& collectionName, Flags flags = DELETE_DEFAULT);
+		/// Creates a DeleteRequest for the given collection using the given flags. 
+		///
+		/// The full collection name is the concatenation of the database 
 		/// name with the collection name, using a "." for the concatenation. For example, 
 		/// for the database "foo" and the collection "bar", the full collection name is 
 		/// "foo.bar".
 
 	DeleteRequest(const std::string& collectionName, bool justOne);
-		/// Constructor. The full collection name is the concatenation of the database
+		/// Creates a DeleteRequest for the given collection.
+		/// 
+		/// The full collection name is the concatenation of the database
 		/// name with the collection name, using a "." for the concatenation. For example,
 		/// for the database "foo" and the collection "bar", the full collection name is
-		/// "foo.bar". When justOne is true, only the first matching document will
+		/// "foo.bar". 
+		///
+		/// If justOne is true, only the first matching document will
 		/// be removed (the same as using flag DELETE_SINGLE_REMOVE).
 
 	virtual ~DeleteRequest();
 		/// Destructor
 
 	Flags flags() const;
-		/// Returns flags
+		/// Returns the flags.
 
 	void flags(Flags flag);
-		/// Sets flags
+		/// Sets the flags.
 
 	Document& selector();
-		/// Returns the selector document
+		/// Returns the selector document.
 
 protected:
 	void buildRequest(BinaryWriter& writer);
-		/// Writes the OP_DELETE request to the writer
+		/// Writes the OP_DELETE request to the writer.
 
 private:
 	Flags       _flags;
@@ -82,6 +88,9 @@ private:
 };
 
 
+///
+/// inlines
+///
 inline DeleteRequest::Flags DeleteRequest::flags() const
 {
 	return _flags;
@@ -103,4 +112,4 @@ inline Document& DeleteRequest::selector()
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_DeleteRequest_INCLUDED
+#endif // MongoDB_DeleteRequest_INCLUDED

MongoDB/include/Poco/MongoDB/Document.h

@@ -25,6 +25,7 @@
 #include "Poco/MongoDB/MongoDB.h"
 #include "Poco/MongoDB/Element.h"
 #include <algorithm>
+#include <cstdlib>
 
 
 namespace Poco {
@@ -34,7 +35,8 @@ namespace MongoDB {
 class ElementFindByName
 {
 public:
-	ElementFindByName(const std::string& name) : _name(name)
+	ElementFindByName(const std::string& name): 
+		_name(name)
 	{
 	}
 
@@ -49,26 +51,28 @@ private:
 
 
 class MongoDB_API Document
-	/// Represents a BSON document
+	/// Represents a MongoDB (BSON) document.
 {
 public:
 	typedef SharedPtr<Document> Ptr;
 	typedef std::vector<Document::Ptr> Vector;
 
 	Document();
-		/// Constructor
+		/// Creates an empty Document.
 
 	virtual ~Document();
-		/// Destructor
+		/// Destroys the Document.
 
 	Document& addElement(Element::Ptr element);
 		/// Add an element to the document.
+		///
 		/// The active document is returned to allow chaining of the add methods.
 
 	template<typename T>
 	Document& add(const std::string& name, T value)
 		/// Creates an element with the given name and value and
 		/// adds it to the document.
+		///
 		/// The active document is returned to allow chaining of the add methods.
 	{
 		return addElement(new ConcreteElement<T>(name, value));
@@ -77,6 +81,7 @@ public:
 	Document& add(const std::string& name, const char* value)
 		/// Creates an element with the given name and value and
 		/// adds it to the document.
+		///
 		/// The active document is returned to allow chaining of the add methods.
 	{
 		return addElement(new ConcreteElement<std::string>(name, std::string(value)));
@@ -94,10 +99,10 @@ public:
 		/// Puts all element names into std::vector.
 
 	bool empty() const;
-		/// Returns true when the document doesn't contain any documents.
+		/// Returns true if the document doesn't contain any documents.
 
 	bool exists(const std::string& name);
-		/// Returns true when the document has an element with the given name
+		/// Returns true if the document has an element with the given name.
 
 	template<typename T>
 	T get(const std::string& name) const
@@ -107,16 +112,16 @@ public:
 		/// converted a BadCastException will be thrown.
 	{
 		Element::Ptr element = get(name);
-		if ( element.isNull() )
+		if (element.isNull())
 		{
 			throw NotFoundException(name);
 		}
 		else
 		{
-			if ( ElementTraits<T>::TypeId == element->type() )
+			if (ElementTraits<T>::TypeId == element->type())
 			{
 				ConcreteElement<T>* concrete = dynamic_cast<ConcreteElement<T>* >(element.get());
-				if ( concrete != NULL )
+				if (concrete != 0)
 				{
 					return concrete->value();
 				}
@@ -132,15 +137,15 @@ public:
 		/// has the wrong type, the def argument will be returned.
 	{
 		Element::Ptr element = get(name);
-		if ( element.isNull() )
+		if (element.isNull())
 		{
 			return def;
 		}
 
-		if ( ElementTraits<T>::TypeId == element->type() )
+		if (ElementTraits<T>::TypeId == element->type())
 		{
 			ConcreteElement<T>* concrete = dynamic_cast<ConcreteElement<T>* >(element.get());
-			if ( concrete != NULL )
+			if (concrete != 0)
 			{
 				return concrete->value();
 			}
@@ -154,17 +159,17 @@ public:
 		/// An empty element will be returned when the element is not found.
 
 	Int64 getInteger(const std::string& name) const;
-		/// Returns an integer. Useful when MongoDB returns int32, int64
+		/// Returns an integer. Useful when MongoDB returns Int32, Int64
 		/// or double for a number (count for example). This method will always
 		/// return an Int64. When the element is not found, a
-		/// NotFoundException will be thrown.
+		/// Poco::NotFoundException will be thrown.
 
 	template<typename T>
 	bool isType(const std::string& name) const
-		/// Returns true when the type of the element equals the TypeId of ElementTrait
+		/// Returns true when the type of the element equals the TypeId of ElementTrait.
 	{
 		Element::Ptr element = get(name);
-		if ( element.isNull() )
+		if (element.isNull())
 		{
 			return false;
 		}
@@ -175,7 +180,7 @@ public:
 	void read(BinaryReader& reader);
 		/// Reads a document from the reader
 
-	size_t size() const;
+	std::size_t size() const;
 		/// Returns the number of elements in the document.
 
 	virtual std::string toString(int indent = 0) const;
@@ -189,6 +194,9 @@ protected:
 };
 
 
+//
+// inlines
+//
 inline Document& Document::addElement(Element::Ptr element)
 {
 	_elements.push_back(element);
@@ -218,7 +226,7 @@ inline bool Document::empty() const
 
 inline void Document::elementNames(std::vector<std::string>& keys) const
 {
-	for(ElementSet::const_iterator it = _elements.begin(); it != _elements.end(); ++it)
+	for (ElementSet::const_iterator it = _elements.begin(); it != _elements.end(); ++it)
 	{
 		keys.push_back((*it)->name());
 	}
@@ -231,7 +239,7 @@ inline bool Document::exists(const std::string& name)
 }
 
 
-inline size_t Document::size() const
+inline std::size_t Document::size() const
 {
 	return _elements.size();
 }
@@ -264,7 +272,8 @@ inline void BSONWriter::write<Document::Ptr>(Document::Ptr& from)
 	from->write(_writer);
 }
 
+
 } } // namespace Poco::MongoDB
 
 
-#endif //  MongoDB_Document_INCLUDED
+#endif // MongoDB_Document_INCLUDED

MongoDB/include/Poco/MongoDB/Element.h

@@ -42,19 +42,19 @@ namespace MongoDB {
 
 
 class MongoDB_API Element
-	/// Represents an element of a Document or an Array
+	/// Represents an Element of a Document or an Array.
 {
 public:
 	typedef Poco::SharedPtr<Element> Ptr;
 
-	Element(const std::string& name);
-		/// Constructor
+	explicit Element(const std::string& name);
+		/// Creates the Element with the given name.
 
 	virtual ~Element();
 		/// Destructor
 
-	std::string name() const;
-		/// Returns the name of the element
+	const std::string& name() const;
+		/// Returns the name of the element.
 
 	virtual std::string toString(int indent = 0) const = 0;
 		/// Returns a string representation of the element.
@@ -71,7 +71,10 @@ private:
 };
 
 
-inline std::string Element::name() const
+//
+// inlines
+//
+inline const std::string& Element::name() const
 {
 	return _name;
 }
@@ -114,7 +117,7 @@ struct ElementTraits<std::string>
 
 		oss << '"';
 
-		for(std::string::const_iterator it = value.begin(); it != value.end(); ++it)
+		for (std::string::const_iterator it = value.begin(); it != value.end(); ++it)
 		{
 			switch (*it)
 			{
@@ -350,10 +353,12 @@ struct ElementTraits<Int64>
 
 
 template<typename T>
-class ConcreteElement : public Element
+class ConcreteElement: public Element
 {
 public:
-	ConcreteElement(const std::string& name, const T& init) : Element(name), _value(init)
+	ConcreteElement(const std::string& name, const T& init):
+		Element(name), 
+		_value(init)
 	{
 	}
 
@@ -397,4 +402,4 @@ private:
 } } // namespace Poco::MongoDB
 
 
-#endif //  MongoDB_Element_INCLUDED
+#endif // MongoDB_Element_INCLUDED

MongoDB/include/Poco/MongoDB/GetMoreRequest.h

@@ -28,31 +28,31 @@ namespace Poco {
 namespace MongoDB {
 
 
-class MongoDB_API GetMoreRequest : public RequestMessage
-	/// Class for creating an OP_GETMORE client request. This request is used
-	/// to query the database for more documents in a collection after
-	/// a query request is send.
+class MongoDB_API GetMoreRequest: public RequestMessage
+	/// A GetMoreRequest is used to query the database for more documents in a collection 
+	/// after a query request is send (OP_GETMORE).
 {
 public:
 	GetMoreRequest(const std::string& collectionName, Int64 cursorID);
-		/// Constructor. The full collection name is the concatenation of the database 
+		/// Creates a GetMoreRequest for the give collection and cursor. 
+		///
+		/// The full collection name is the concatenation of the database 
 		/// name with the collection name, using a "." for the concatenation. For example, 
 		/// for the database "foo" and the collection "bar", the full collection name is 
 		/// "foo.bar". The cursorID has been returned by the response on the query request.
 		/// By default the numberToReturn is set to 100.
 
-
 	virtual ~GetMoreRequest();
-		/// Destructor
+		/// Destroys the GetMoreRequest.
 
 	Int32 getNumberToReturn() const;
-		/// Returns the limit of returned documents
+		/// Returns the limit of returned documents.
 
 	void setNumberToReturn(Int32 n);
-		/// Sets the limit of returned documents
+		/// Sets the limit of returned documents.
 
 	Int64 cursorID() const;
-		/// Returns the cursor id
+		/// Returns the cursor ID.
 
 protected:
 	void buildRequest(BinaryWriter& writer);
@@ -88,4 +88,4 @@ inline Int64 GetMoreRequest::cursorID() const
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_GetMoreRequest_INCLUDED
+#endif // MongoDB_GetMoreRequest_INCLUDED

MongoDB/include/Poco/MongoDB/InsertRequest.h

@@ -29,26 +29,34 @@ namespace Poco {
 namespace MongoDB {
 
 
-class MongoDB_API InsertRequest : public RequestMessage
-	/// Class for creating an OP_INSERT client request. This request is used
-	/// to insert one or more documents to the database.
+class MongoDB_API InsertRequest: public RequestMessage
+	/// A request for inserting one or more documents to the database
+	/// (OP_INSERT).
 {
 public:
-	typedef enum
+	enum Flags
 	{
-		INSERT_NONE = 0,
+		INSERT_DEFAULT = 0,
+			/// If specified, perform a normal insert operation.
+		
 		INSERT_CONTINUE_ON_ERROR = 1
-	} Flags;
+			/// If set, the database will not stop processing a bulk insert if one 
+			/// fails (e.g. due to duplicate IDs). This makes bulk insert behave similarly 
+			/// to a series of single inserts, except lastError will be set if any insert 
+			/// fails, not just the last one. If multiple errors occur, only the most 
+			/// recent will be reported.
+	};
 
-	InsertRequest(const std::string& collectionName, Flags flags = INSERT_NONE );
-		/// Constructor.
+	InsertRequest(const std::string& collectionName, Flags flags = INSERT_DEFAULT);
+		/// Creates an InsertRequest.
+		///
 		/// The full collection name is the concatenation of the database 
 		/// name with the collection name, using a "." for the concatenation. For example, 
 		/// for the database "foo" and the collection "bar", the full collection name is 
 		/// "foo.bar".
 
 	virtual ~InsertRequest();
-		/// Destructor
+		/// Destroys the InsertRequest.
 
 	Document& addNewDocument();
 		/// Adds a new document for insertion. A reference to the empty document is
@@ -56,20 +64,21 @@ public:
 		/// on destruction.
 
 	Document::Vector& documents();
-		/// Returns the documents to insert into the database
+		/// Returns the documents to insert into the database.
 
 protected:
-
 	void buildRequest(BinaryWriter& writer);
 
 private:
-
 	Int32 _flags;
 	std::string _fullCollectionName;
 	Document::Vector _documents;
 };
 
 
+//
+// inlines
+//
 inline Document& InsertRequest::addNewDocument()
 {
 	Document::Ptr doc = new Document();
@@ -87,4 +96,4 @@ inline Document::Vector& InsertRequest::documents()
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_InsertRequest_INCLUDED
+#endif // MongoDB_InsertRequest_INCLUDED

MongoDB/include/Poco/MongoDB/JavaScriptCode.h

@@ -32,31 +32,34 @@ namespace MongoDB {
 
 
 class MongoDB_API JavaScriptCode
-	/// Represents JavaScript type in BSON
+	/// Represents JavaScript type in BSON.
 {
 public:
 	typedef SharedPtr<JavaScriptCode> Ptr;
 
 	JavaScriptCode();
-		/// Constructor
+		/// Creates an empty JavaScriptCode object.
 
 	virtual ~JavaScriptCode();
-		/// Destructor
+		/// Destroys the JavaScriptCode.
 
-	void setCode(const std::string& s);
-		/// Set the code
+	void setCode(const std::string& code);
+		/// Sets the JavaScript code.
 
 	std::string getCode() const;
-		/// Get the code
+		/// Returns the JavaScript code.
 
 private:
 	std::string _code;
 };
 
 
-inline void JavaScriptCode::setCode(const std::string& s)
+//
+// inlines
+//
+inline void JavaScriptCode::setCode(const std::string& code)
 {
-	_code = s;
+	_code = code;
 }
 
 
@@ -65,6 +68,7 @@ inline std::string JavaScriptCode::getCode() const
 	return _code;
 }
 
+
 // BSON JavaScript code
 // spec: string
 template<>
@@ -100,4 +104,4 @@ inline void BSONWriter::write<JavaScriptCode::Ptr>(JavaScriptCode::Ptr& from)
 } } // namespace Poco::MongoDB
 
 
-#endif //  MongoDB_JavaScriptCode_INCLUDED
+#endif // MongoDB_JavaScriptCode_INCLUDED

MongoDB/include/Poco/MongoDB/KillCursorsRequest.h

@@ -28,20 +28,20 @@ namespace Poco {
 namespace MongoDB {
 
 
-class MongoDB_API KillCursorsRequest : public RequestMessage
+class MongoDB_API KillCursorsRequest: public RequestMessage
 	/// Class for creating an OP_KILL_CURSORS client request. This
 	/// request is used to kill cursors, which are still open, 
 	/// returned by query requests.
 {
 public:
 	KillCursorsRequest();
-		/// Constructor
+		/// Creates a KillCursorsRequest.
 
 	virtual ~KillCursorsRequest();
-		/// Destructor
+		/// Destroys the KillCursorsRequest.
 		
 	std::vector<Int64>& cursors();
-		/// Return the cursors
+		/// The internal list of cursors.
 		
 protected:
 	void buildRequest(BinaryWriter& writer);
@@ -49,6 +49,9 @@ protected:
 };
 
 
+//
+// inlines
+//
 inline std::vector<Int64>& KillCursorsRequest::cursors()
 {
 	return _cursors;
@@ -58,4 +61,4 @@ inline std::vector<Int64>& KillCursorsRequest::cursors()
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_KillCursorsRequest_INCLUDED
+#endif // MongoDB_KillCursorsRequest_INCLUDED

MongoDB/include/Poco/MongoDB/Message.h

@@ -33,11 +33,11 @@ namespace MongoDB {
 
 
 class MongoDB_API Message
-	/// Base class for all messages send or retrieved from MongoDB server
+	/// Base class for all messages send or retrieved from MongoDB server.
 {
 public:
-	Message(MessageHeader::OpCode opcode);
-		/// Constructor
+	explicit Message(MessageHeader::OpCode opcode);
+		/// Creates a Message using the given OpCode.
 	
 	virtual ~Message();
 		/// Destructor
@@ -53,6 +53,9 @@ protected:
 };
 
 
+//
+// inlines
+//
 inline MessageHeader& Message::header()
 {
 	return _header;
@@ -69,4 +72,4 @@ inline void Message::messageLength(Poco::Int32 length)
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_Message_INCLUDED
+#endif // MongoDB_Message_INCLUDED

MongoDB/include/Poco/MongoDB/MessageHeader.h

@@ -29,54 +29,54 @@ namespace MongoDB {
 
 
 class MongoDB_API MessageHeader
-	/// Represents the header which is always prepended to a request
-	/// or response of MongoDB
+	/// Represents the message header which is always prepended to a 
+	/// MongoDB request or response message.
 {
 public:
 	static const unsigned int MSG_HEADER_SIZE = 16;
 
-	typedef enum
+	enum OpCode
 	{
-		  Reply = 1
-		, Msg = 1000
-		, Update = 2001
-		, Insert = 2002
-		, Query = 2004
-		, GetMore = 2005
-		, Delete = 2006
-		, KillCursors = 2007
-	} OpCode;
+		OP_REPLY = 1,
+		OP_MSG = 1000,
+		OP_UPDATE = 2001,
+		OP_INSERT = 2002,
+		OP_QUERY = 2004,
+		OP_GET_MORE = 2005,
+		OP_DELETE = 2006,
+		OP_KILL_CURSORS = 2007
+	};
+
+	explicit MessageHeader(OpCode);
+		/// Creates the MessageHeader using the given OpCode.
 
 	virtual ~MessageHeader();
-		/// Destructor
+		/// Destroys the MessageHeader.
 
 	void read(BinaryReader& reader);
-		/// Reads the header
+		/// Reads the header using the given BinaryReader.
 
 	void write(BinaryWriter& writer);
-		/// Writes the header
+		/// Writes the header using the given BinaryWriter.
 
 	Int32 getMessageLength() const;
-		/// Returns the message length
+		/// Returns the message length.
 
 	OpCode opCode() const;
-		/// Returns the OpCode
+		/// Returns the OpCode.
 
 	Int32 getRequestID() const;
-		/// Returns the request id of the current message
+		/// Returns the request ID of the current message.
 
 	void setRequestID(Int32 id);
-		/// Sets the request id of the current message
+		/// Sets the request ID of the current message.
 
 	Int32 responseTo() const;
 		/// Returns the request id from the original request. 
 
 private:
-	MessageHeader(OpCode opcode);
-		/// Constructor.
-
 	void setMessageLength(Int32 length);
-		/// Sets the message length
+		/// Sets the message length.
 
 	Int32 _messageLength;
 	Int32 _requestID;
@@ -87,6 +87,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline MessageHeader::OpCode MessageHeader::opCode() const
 {
 	return _opCode;
@@ -126,4 +129,4 @@ inline Int32 MessageHeader::responseTo() const
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_MessageHeader_INCLUDED
+#endif // MongoDB_MessageHeader_INCLUDED

MongoDB/include/Poco/MongoDB/ObjectId.h

@@ -32,10 +32,10 @@ namespace MongoDB {
 class MongoDB_API ObjectId
 	/// ObjectId is a 12-byte BSON type, constructed using:
 	///
-	/// - a 4-byte timestamp,
-	/// - a 3-byte machine identifier,
-	/// - a 2-byte process id, and
-	/// - a 3-byte counter, starting with a random value.
+	///   - a 4-byte timestamp,
+	///   - a 3-byte machine identifier,
+	///   - a 2-byte process id, and
+	///   - a 3-byte counter, starting with a random value.
 	///
 	/// In MongoDB, documents stored in a collection require a unique _id field that acts
 	/// as a primary key. Because ObjectIds are small, most likely unique, and fast to generate,
@@ -46,15 +46,17 @@ class MongoDB_API ObjectId
 public:
 	typedef SharedPtr<ObjectId> Ptr;
 
-	ObjectId(const std::string& id);
-		/// Constructor. The string must contain a hexidecimal representation
-		/// of an object id. This means a string of 24 characters.
+	explicit ObjectId(const std::string& id);
+		/// Creates an ObjectId from a string. 
+		///
+		/// The string must contain a hexidecimal representation
+		/// of an object ID. This means a string of 24 characters.
 
 	ObjectId(const ObjectId& copy);
-		/// Copy constructor.
+		/// Creates an ObjectId by copying another one.
 
 	virtual ~ObjectId();
-		/// Destructor
+		/// Destroys the ObjectId.
 
 	Timestamp timestamp() const;
 		/// Returns the timestamp which is stored in the first four bytes of the id
@@ -65,22 +67,22 @@ public:
 		/// of the ID char array.
 
 private:
-
 	ObjectId();
-		/// Constructor. Creates an empty Id
 
+	static int fromHex(char c);	
+	static char fromHex(const char* c);
+	
 	unsigned char _id[12];
 
 	friend class BSONWriter;
 	friend class BSONReader;
 	friend class Document;
-	
-	static int fromHex(char c);
-	
-	static char fromHex(const char* c);
 };
 
 
+//
+// inlines
+//
 inline Timestamp ObjectId::timestamp() const
 {
 	int time;
@@ -92,6 +94,7 @@ inline Timestamp ObjectId::timestamp() const
 	return Timestamp::fromEpochTime((time_t) time);
 }
 
+
 inline int ObjectId::fromHex(char c)
 {
 	if ( '0' <= c && c <= '9' )
@@ -103,11 +106,13 @@ inline int ObjectId::fromHex(char c)
 	return 0xff;
 }
 
+
 inline char ObjectId::fromHex(const char* c)
 {
 	return (char)((fromHex(c[0]) << 4 ) | fromHex(c[1]));
 }
 
+
 // BSON Embedded Document
 // spec: ObjectId
 template<>
@@ -141,4 +146,4 @@ inline void BSONWriter::write<ObjectId::Ptr>(ObjectId::Ptr& from)
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_ObjectId_INCLUDED
+#endif // MongoDB_ObjectId_INCLUDED

MongoDB/include/Poco/MongoDB/PoolableConnectionFactory.h

@@ -33,13 +33,13 @@ class PoolableObjectFactory<MongoDB::Connection, MongoDB::Connection::Ptr>
 	/// are created with the given address.
 {
 public:
-	PoolableObjectFactory(Net::SocketAddress& address)
-		: _address(address)
+	PoolableObjectFactory(Net::SocketAddress& address):
+		_address(address)
 	{
 	}
 
-	PoolableObjectFactory(const std::string& address)
-		: _address(address)
+	PoolableObjectFactory(const std::string& address):
+		_address(address)
 	{
 	}
 
@@ -105,8 +105,7 @@ private:
 };
 
 
-} // namespace MongoDB
-} // namespace Poco
+} } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_PoolableConnectionFactory_INCLUDED
+#endif // MongoDB_PoolableConnectionFactory_INCLUDED

MongoDB/include/Poco/MongoDB/QueryRequest.h

@@ -29,59 +29,89 @@ namespace Poco {
 namespace MongoDB {
 
 
-class MongoDB_API QueryRequest : public RequestMessage
-	/// Class for creating an OP_QUERY client request. This request
-	/// is used to query documents from the database.
+class MongoDB_API QueryRequest: public RequestMessage
+	/// A request to query documents in a MongoDB database
+	/// using an OP_QUERY request.
 {
 public:
-	typedef enum
+	enum Flags
 	{
-		QUERY_NONE = 0, 
-		QUERY_TAILABLECURSOR = 2, 
+		QUERY_DEFAULT = 0, 
+			/// Do not set any flags.
+	
+		QUERY_TAILABLE_CURSOR = 2, 
+			/// Tailable means cursor is not closed when the last data is retrieved. 
+			/// Rather, the cursor marks the final object’s position. 
+			/// You can resume using the cursor later, from where it was located, 
+			/// if more data were received. Like any "latent cursor", the cursor may 
+			/// become invalid at some point (CursorNotFound) – for example if the final 
+			/// object it references were deleted.
+	
 		QUERY_SLAVE_OK = 4, 
-		//QUERY_OPLOG_REPLAY = 8 (internal replication use only - drivers should not implement)
-		QUERY_NOCUROSR_TIMEOUT = 16,
+			/// Allow query of replica slave. Normally these return an error except 
+			/// for namespace "local".
+			
+		// QUERY_OPLOG_REPLAY = 8 (internal replication use only - drivers should not implement)
+		
+		QUERY_NO_CURSOR_TIMEOUT = 16,
+			/// The server normally times out idle cursors after an inactivity period 
+			/// (10 minutes) to prevent excess memory use. Set this option to prevent that.
+	
 		QUERY_AWAIT_DATA = 32,
-		QUERY_EXHAUST = 64,
-		QUERY_PARTIAL = 128
-	} Flags;
+			/// Use with QUERY_TAILABLECURSOR. If we are at the end of the data, block for 
+			/// a while rather than returning no data. After a timeout period, we do 
+			/// return as normal.
 
-	QueryRequest(const std::string& collectionName, Flags flags = QUERY_NONE);
-		/// Constructor.
+		QUERY_EXHAUST = 64,
+			/// Stream the data down full blast in multiple "more" packages, on the 
+			/// assumption that the client will fully read all data queried. 
+			/// Faster when you are pulling a lot of data and know you want to pull 
+			/// it all down. 
+			/// Note: the client is not allowed to not read all the data unless it 
+			/// closes the connection.
+
+		QUERY_PARTIAL = 128
+			/// Get partial results from a mongos if some shards are down 
+			/// (instead of throwing an error).
+	};
+
+	QueryRequest(const std::string& collectionName, Flags flags = QUERY_DEFAULT);
+		/// Creates a QueryRequest.
+		///
 		/// The full collection name is the concatenation of the database 
 		/// name with the collection name, using a "." for the concatenation. For example, 
 		/// for the database "foo" and the collection "bar", the full collection name is 
 		/// "foo.bar".
 
 	virtual ~QueryRequest();
-		/// Destructor
+		/// Destroys the QueryRequest.
 
 	Flags getFlags() const;
-		/// Returns the flags
+		/// Returns the flags.
 
 	void setFlags(Flags flag);
-		/// Set the flags
+		/// Set the flags.
 
 	std::string fullCollectionName() const;
-		/// Returns the <db>.<collection> used for this query
+		/// Returns the <db>.<collection> used for this query.
 
 	Int32 getNumberToSkip() const;
-		/// Returns the number of documents to skip
+		/// Returns the number of documents to skip.
 
 	void setNumberToSkip(Int32 n);
-		/// Sets the number of documents to skip
+		/// Sets the number of documents to skip.
 
 	Int32 getNumberToReturn() const;
-		/// Returns the number to return
+		/// Returns the number of documents to return.
 
 	void setNumberToReturn(Int32 n);
-		/// Sets the number to return (limit)
+		/// Sets the number of documents to return (limit).
 
 	Document& selector();
-		/// Returns the selector document
+		/// Returns the selector document.
 
 	Document& returnFieldSelector();
-		/// Returns the field selector document
+		/// Returns the field selector document.
 
 protected:
 	void buildRequest(BinaryWriter& writer);
@@ -96,6 +126,9 @@ private:
 };
 
 
+//
+// inlines
+//
 inline QueryRequest::Flags QueryRequest::getFlags() const
 {
 	return _flags;
@@ -153,4 +186,4 @@ inline void QueryRequest::setNumberToReturn(Int32 n)
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_QueryRequest_INCLUDED
+#endif // MongoDB_QueryRequest_INCLUDED

MongoDB/include/Poco/MongoDB/RegularExpression.h

@@ -30,34 +30,34 @@ namespace MongoDB {
 
 
 class MongoDB_API RegularExpression
-	/// Represents a regular expression in BSON format
+	/// Represents a regular expression in BSON format.
 {
 public:
 	typedef SharedPtr<RegularExpression> Ptr;
 
 	RegularExpression();
-		/// Constructor
+		/// Creates an empty RegularExpression.
 
 	RegularExpression(const std::string& pattern, const std::string& options);
-		/// Constructor
+		/// Creates a RegularExpression using the given pattern and options.
 
 	virtual ~RegularExpression();
-		/// Destructor
+		/// Destroys the RegularExpression.
 
 	SharedPtr<Poco::RegularExpression> createRE() const;
-		/// Tries to create a Poco::RegularExpression
+		/// Tries to create a Poco::RegularExpression from the MongoDB regular expression.
 
 	std::string getOptions() const;
-		/// Returns the options
+		/// Returns the options string.
 
 	void setOptions(const std::string& options);
-		/// Sets the options
+		/// Sets the options string.
 
 	std::string getPattern() const;
-		/// Returns the pattern
+		/// Returns the pattern.
 
 	void setPattern(const std::string& pattern);
-		/// Sets the pattern
+		/// Sets the pattern.
 
 private:
 	std::string _pattern;
@@ -65,6 +65,9 @@ private:
 };
 
 
+///
+/// inlines
+///
 inline std::string RegularExpression::getPattern() const
 {
 	return _pattern;
@@ -125,4 +128,4 @@ inline void BSONWriter::write<RegularExpression::Ptr>(RegularExpression::Ptr& fr
 } } // namespace Poco::MongoDB
 
 
-#endif //  MongoDB_RegularExpression_INCLUDED
+#endif // MongoDB_RegularExpression_INCLUDED

MongoDB/include/Poco/MongoDB/ReplicaSet.h

@@ -30,21 +30,26 @@ namespace MongoDB {
 
 
 class MongoDB_API ReplicaSet
-	/// Class for working with a replicaset
+	/// Class for working with a MongoDB replica set.
 {
 public:
-	ReplicaSet(const std::vector<Net::SocketAddress>& addresses);
-		/// Constructor
+	explicit ReplicaSet(const std::vector<Net::SocketAddress>& addresses);
+		/// Creates the ReplicaSet using the given server addresses.
 
 	virtual ~ReplicaSet();
-		/// Destructor
+		/// Destroys the ReplicaSet.
 
 	Connection::Ptr findMaster();
 		/// Tries to find the master MongoDB instance from the addresses
+		/// passed to the constructor.
+		///
+		/// Returns the Connection to the master, or null if no master
+		/// instance was found.
 
-private:
+protected:
 	Connection::Ptr isMaster(const Net::SocketAddress& host);
 
+private:
 	std::vector<Net::SocketAddress> _addresses;
 };
 

MongoDB/include/Poco/MongoDB/RequestMessage.h

@@ -29,18 +29,18 @@ namespace Poco {
 namespace MongoDB {
 
 
-class MongoDB_API RequestMessage : public Message
-	/// Base class for a request
+class MongoDB_API RequestMessage: public Message
+	/// Base class for a request sent to the MongoDB server.
 {
 public:
-	RequestMessage(MessageHeader::OpCode opcode);
-		/// Constructor
+	explicit RequestMessage(MessageHeader::OpCode opcode);
+		/// Creates a RequestMessage using the given opcode.
 
 	virtual ~RequestMessage();
-		/// Destructor
+		/// Destroys the RequestMessage.
 
 	void send(std::ostream& ostr);
-		/// Sends the request to stream
+		/// Writes the request to stream.
 
 protected:
 	virtual void buildRequest(BinaryWriter& ss) = 0;
@@ -50,4 +50,4 @@ protected:
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_RequestMessage_INCLUDED
+#endif // MongoDB_RequestMessage_INCLUDED

MongoDB/include/Poco/MongoDB/ResponseMessage.h

@@ -24,42 +24,43 @@
 #include "Poco/MongoDB/Message.h"
 #include "Poco/MongoDB/Document.h"
 #include <istream>
+#include <cstdlib>
 
 
 namespace Poco {
 namespace MongoDB {
 
 
-class MongoDB_API ResponseMessage : public Message
-	/// Class that represents a response (OP_REPLY) from MongoDB
+class MongoDB_API ResponseMessage: public Message
+	/// This class represents a response (OP_REPLY) from MongoDB.
 {
 public:
 	ResponseMessage();
-		/// Constructor
+		/// Creates an empty ResponseMessage.
 
 	virtual ~ResponseMessage();
-		/// Destructor
+		/// Destroys the ResponseMessage.
 
 	Int64 cursorID() const;
-		/// Returns the cursor id
+		/// Returns the cursor ID.
 
 	void clear();
-		/// Clears the response
+		/// Clears the response.
 
-	size_t count() const;
-		/// Returns the number of documents in the response
+	std::size_t count() const;
+		/// Returns the number of documents in the response.
 
 	Document::Vector& documents();
-		/// Returns the retrieved documents
+		/// Returns a vector containing the received documents.
 
 	bool empty() const;
-		/// Returns true when the response doesn't contain any documents
+		/// Returns true if the response does not contain any documents.
 
 	bool hasDocuments() const;
-		/// Returns true when there is at least one document
+		/// Returns true if there is at least one document in the response.
 
 	void read(std::istream& istr);
-		/// Reads the response from the stream
+		/// Reads the response from the stream.
 
 private:
 	Int32 _responseFlags;
@@ -70,7 +71,10 @@ private:
 };
 
 
-inline size_t ResponseMessage::count() const
+//
+// inlines
+//
+inline std::size_t ResponseMessage::count() const
 {
 	return _documents.size();
 }
@@ -103,4 +107,4 @@ inline bool ResponseMessage::hasDocuments() const
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_ResponseMessage_INCLUDED
+#endif // MongoDB_ResponseMessage_INCLUDED

MongoDB/include/Poco/MongoDB/UpdateRequest.h

@@ -29,39 +29,42 @@ namespace Poco {
 namespace MongoDB {
 
 
-class UpdateRequest : public RequestMessage
-	/// Class for creating an OP_UPDATE client request. This request is used
-	/// to update a document.
+class UpdateRequest: public RequestMessage
+	/// This request is used to update a document in a database
+	/// using the OP_UPDATE client request. 
 {
 public:
-	typedef enum
+	enum Flags
 	{
-		UPDATE_NOFLAGS = 0,
-		// If set, the database will insert the supplied object into the
-		// collection if no matching document is found.
+		UPDATE_DEFAULT = 0,
+			/// If set, the database will insert the supplied object into the
+			/// collection if no matching document is found.
+			
 		UPDATE_UPSERT = 1,
-		// if set, the database will update all matching objects in the collection.
-		// Otherwise only updates first matching doc.
-		UPDATE_MULTIUPDATE = 2
-	} Flags;
+			/// If set, the database will update all matching objects in the collection.
+			/// Otherwise only updates first matching doc.
 
-	UpdateRequest(const std::string& collectionName, Flags flags = UPDATE_NOFLAGS);
-		/// Constructor.
+		UPDATE_MULTIUPDATE = 2
+			/// If set to, updates multiple documents that meet the query criteria.
+			/// Otherwise only updates one document.
+	};
+
+	UpdateRequest(const std::string& collectionName, Flags flags = UPDATE_DEFAULT);
+		/// Creates the UpdateRequest.
+		///
 		/// The full collection name is the concatenation of the database 
 		/// name with the collection name, using a "." for the concatenation. For example, 
 		/// for the database "foo" and the collection "bar", the full collection name is 
 		/// "foo.bar".
 
 	virtual ~UpdateRequest();
-		/// Destructor
-		
+		/// Destroys the UpdateRequest.
 
 	Document& selector();
-		/// Returns the selector document
-		
+		/// Returns the selector document.
 
 	Document& update();
-		/// The document to update
+		/// Returns the document to update.
 
 	Flags flags() const;
 		/// Returns the flags
@@ -72,7 +75,6 @@ public:
 protected:
 	void buildRequest(BinaryWriter& writer);
 
-
 private:
 	Flags       _flags;
 	std::string _fullCollectionName;
@@ -81,21 +83,27 @@ private:
 };
 
 
+//
+// inlines
+//
 inline UpdateRequest::Flags UpdateRequest::flags() const
 {
 	return _flags;
 }
 
+
 inline void UpdateRequest::flags(UpdateRequest::Flags flags)
 {
 	_flags = flags;
 }
 
+
 inline Document& UpdateRequest::selector()
 {
 	return _selector;
 }
 
+
 inline Document& UpdateRequest::update()
 {
 	return _update;
@@ -105,4 +113,4 @@ inline Document& UpdateRequest::update()
 } } // namespace Poco::MongoDB
 
 
-#endif //MongoDB_UpdateRequest_INCLUDED
+#endif // MongoDB_UpdateRequest_INCLUDED