Fixed documentation of return value for  BSONObject.put to indicate that it returns the previous value associated with the given key.
Also fixed some Javadoc in BSONObject implementations.

  JAVA-1502