comments

1 files changed, 10 insertions, 3 deletions

diff --git a/bson/bsonelement.h b/bson/bsonelement.h
index 52dbee3084e..23d59faaff6 100644
--- a/bson/bsonelement.h
+++ b/bson/bsonelement.h
@@ -63,11 +63,18 @@ namespace mongo {
         long long Long()            const { return chk(NumberLong)._numberLong(); }
         int Int()                   const { return chk(NumberInt)._numberInt(); }
         bool Bool()                 const { return chk(mongo::Bool).boolean(); }
-        BSONObj Obj()               const;
         vector<BSONElement> Array() const; // see implementation for detailed comments
         mongo::OID OID()            const { return chk(jstOID).__oid(); }
-        void Null()                 const { chk(isNull()); }
-        void OK()                   const { chk(ok()); }
+        void Null()                 const { chk(isNull()); } // throw UserException if not null
+        void OK()                   const { chk(ok()); }     // throw UserException if element DNE
+
+	/** @return the embedded object associated with this field.
+            Note the returned object is a reference to within the parent bson object. If that 
+	    object is out of scope, this pointer will no longer be valid. Call getOwned() on the 
+	    returned BSONObj if you need your own copy.
+	    throws UserException if the element is not of type object.
+	*/
+        BSONObj Obj()               const;
 
         /** populate v with the value of the element.  If type does not match, throw exception.
             useful in templates -- see also BSONObj::Vals().