Added type aliases and companion objects

Code now under the org.mongodb.scala namespace

 - Unified the api docs
 - Fixed Documentation syntax errors
 - Added type aliases and companion objects to mirror the Java API

SCALA-157

Author: rozza

core/rootdoc.txt

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.mongodb.scala
+package org.mongodb.scala
 
 import scala.language.implicitConversions
 

core/src/main/scala/com/mongodb/scala/Implicits.scala

@@ -14,15 +14,15 @@
  * limitations under the License.
  */
 
-package com.mongodb.scala.codecs
+package org.mongodb.scala.codecs
 
 import org.bson.codecs.Codec
 import org.bson.codecs.configuration.{CodecProvider, CodecRegistry}
-import com.mongodb.scala.collection.{immutable, mutable}
+import org.mongodb.scala.collection.{immutable, mutable}
 
 /**
- * A {@code CodecProvider} for the Document class and all the default Codec implementations on which it depends.
- *
+ * A [[http://api.mongodb.org/java/current/org/bson/codecs/configuration/CodecProvider.html CodecProvider]] for the Document
+ * class and all the default Codec implementations on which it depends.
  */
 case class DocumentCodecProvider() extends CodecProvider {
 

core/src/main/scala/com/mongodb/scala/Helpers.scala renamed to core/src/main/scala/org/mongodb/scala/Helpers.scala

@@ -14,12 +14,12 @@
  * limitations under the License.
  */
 
-package com.mongodb.scala.codecs
+package org.mongodb.scala.codecs
 
 import org.bson.codecs.configuration.CodecRegistry
 import org.bson.codecs.{BsonDocumentCodec, CollectibleCodec, DecoderContext, EncoderContext}
 import org.bson.{BsonReader, BsonValue, BsonWriter}
-import com.mongodb.scala.collection.immutable.Document
+import org.mongodb.scala.collection.immutable.Document
 
 /**
  * Companion helper for immutable Document instances.

core/src/main/scala/com/mongodb/scala/codecs/DocumentCodecProvider.scala renamed to core/src/main/scala/org/mongodb/scala/codecs/DocumentCodecProvider.scala

@@ -14,12 +14,12 @@
  * limitations under the License.
  */
 
-package com.mongodb.scala.codecs
+package org.mongodb.scala.codecs
 
 import org.bson.codecs.configuration.CodecRegistry
 import org.bson.codecs.{BsonDocumentCodec, CollectibleCodec, DecoderContext, EncoderContext}
 import org.bson.{BsonReader, BsonValue, BsonWriter}
-import com.mongodb.scala.collection.mutable.Document
+import org.mongodb.scala.collection.mutable.Document
 
 /**
  * Companion helper for mutable Document instances.

core/src/main/scala/com/mongodb/scala/codecs/ImmutableDocumentCodec.scala renamed to core/src/main/scala/org/mongodb/scala/codecs/ImmutableDocumentCodec.scala

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.mongodb.scala
+package org.mongodb.scala
 
 import org.bson.codecs.configuration.CodecRegistries._
 import org.bson.codecs.configuration.CodecRegistry

core/src/main/scala/com/mongodb/scala/codecs/MutableDocumentCodec.scala renamed to core/src/main/scala/org/mongodb/scala/codecs/MutableDocumentCodec.scala

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.mongodb.scala.collection
+package org.mongodb.scala.collection
 
 import scala.collection.JavaConverters._
 import scala.collection.{GenTraversableOnce, Traversable}
@@ -24,7 +24,7 @@ import scala.util.{Failure, Success, Try}
 import org.bson._
 import org.bson.codecs.configuration.CodecRegistry
 import org.bson.conversions.Bson
-import com.mongodb.scala.Helpers.DefaultsTo
+import org.mongodb.scala.Helpers.DefaultsTo
 
 /**
  * Base Document trait.
@@ -69,12 +69,9 @@ trait BaseDocument[T] extends Traversable[(String, BsonValue)] with Bson {
    * @param   key      the key.
    * @param   default  a computation that yields a default value in case no binding for `key` is
    *                   found in the map.
-   * @tparam  B1       the result type of the default computation.
+   * @tparam  B        the result type of the default computation.
    * @return  the value associated with `key` if it exists,
    *          otherwise the result of the `default` computation.
-   *
-   * @usecase def getOrElse(key: A, default: => B): B
-   * @inheritdoc
    */
   def getOrElse[B >: BsonValue](key: String, default: => B): B = get(key) match {
     case Some(v) => v

core/src/main/scala/com/mongodb/scala/codecs/package.scala renamed to core/src/main/scala/org/mongodb/scala/codecs/package.scala

@@ -14,15 +14,15 @@
  * limitations under the License.
  */
 
-package com.mongodb.scala.collection.immutable
+package org.mongodb.scala.collection.immutable
 
 import scala.collection.JavaConverters._
 import scala.collection.generic.CanBuildFrom
 import scala.collection.mutable.{Builder, ListBuffer}
 import scala.collection.{Traversable, TraversableLike}
 
 import org.bson.{BsonDocument, BsonValue}
-import com.mongodb.scala.collection.BaseDocument
+import org.mongodb.scala.collection.BaseDocument
 
 
 /**
@@ -42,6 +42,16 @@ object Document {
    */
   def apply(): Document = Document(new BsonDocument())
 
+  /**
+   * Parses a string in MongoDB Extended JSON format to a `Document`
+   *
+   * @param json the JSON string
+   * @return a corresponding `Document` object
+   * @see org.bson.json.JsonReader
+   * @see [[http://docs.mongodb.com/manual/reference/mongodb-extended-json/ MongoDB Extended JSON]]
+   */
+  def apply(json: String): Document = Document(BsonDocument.parse(json))
+
   /**
    * Create a new document from the elems
    * @param elems   the key/value pairs that make up the Document
@@ -68,6 +78,7 @@ object Document {
   implicit def canBuildFrom: CanBuildFrom[Traversable[(String, BsonValue)], (String, BsonValue), Document] = {
     new CanBuildFrom[Traversable[(String, BsonValue)], (String, BsonValue), Document] {
       def apply(): Builder[(String, BsonValue), Document] = builder
+
       def apply(from: Traversable[(String, BsonValue)]): Builder[(String, BsonValue), Document] = builder
     }
   }
@@ -85,15 +96,13 @@ object Document {
  * An immutable Document implementation.
  *
  * A strictly typed `Map[String, BsonValue]` like structure that traverses the elements in insertion order. Unlike native scala maps there
- * is no variance in the value type and it always has to be a `BsonValue`.  The [[com.mongodb.scala.Implicits]]
+ * is no variance in the value type and it always has to be a `BsonValue`.  The [[org.mongodb.scala.implicits]]
  * helper provides simple interactions with Documents taking native data types and converting them to `BsonValues`.
  *
- * @note All user operations on the document are immutable. The *only* time the document can mutate state is when an `_id` is added by
- *       the underlying [[com.mongodb.scala.codecs.ImmutableDocumentCodec]] codec on insertion to the database.
  * @param underlying the underlying BsonDocument which stores the data.
  */
 case class Document(protected[scala] val underlying: BsonDocument)
-    extends BaseDocument[Document] with TraversableLike[(String, BsonValue), Document] {
+  extends BaseDocument[Document] with TraversableLike[(String, BsonValue), Document] {
 
   /**
    * Creates a new immutable document
@@ -112,8 +121,6 @@ case class Document(protected[scala] val underlying: BsonDocument)
    *             This result will always be ignored. Typically `U` is `Unit`,
    *             but this is not necessary.
    *
-   * @usecase def foreach(f: A => Unit): Unit
-   * @inheritdoc
    */
   override def foreach[U](f: ((String, BsonValue)) => U): Unit = underlying.asScala foreach f