scaladocs and cosmetics

Author: Roman Janusz

commons-mongo/jvm/src/main/scala/com/avsystem/commons/mongo/typed/TypedClientSession.scala

@@ -10,6 +10,9 @@ import org.bson.{BsonDocument, BsonTimestamp}
 
 import java.io.Closeable
 
+/**
+  * Better typed wrapper over [[ClientSession]].
+  */
 class TypedClientSession(val nativeSession: ClientSession)
   extends Closeable with TypedMongoUtils {
 
@@ -30,6 +33,11 @@ class TypedClientSession(val nativeSession: ClientSession)
   def abortTransaction: Task[Unit] =
     empty(nativeSession.abortTransaction())
 
+  /**
+    * Executes a MongoDB transaction - whose contents are expressed as Monix [[Task]].
+    * If the task succeeds, the transaction is committed. If the task fails, the transaction is aborted and the
+    * error is propagated. The transaction is also aborted upon cancellation.
+    */
   def inTransaction[T](
     transactionOptions: TransactionOptions = TransactionOptions.builder().build()
   )(

commons-mongo/jvm/src/main/scala/com/avsystem/commons/mongo/typed/TypedMongoClient.scala

@@ -70,13 +70,29 @@ class TypedMongoClient(
   ): Task[TypedClientSession] =
     single(nativeClient.startSession(options)).map(new TypedClientSession(_))
 
+  /**
+    * Executes some code in context of a MongoDB client session. The session is closed afterwards.
+    *
+    * Note: in order for actual MongoDB operations to be associated with the session, you need to use
+    * `withSession` on [[TypedMongoClient]], [[TypedMongoDatabase]] or [[TypedMongoCollection]] and use the
+    * returned copy of these objects.
+    */
   def inSession[T](
     options: ClientSessionOptions = ClientSessionOptions.builder().build()
   )(
     task: TypedClientSession => Task[T]
   ): Task[T] =
     startSession(options).bracket(task)(s => Task(s.close()))
 
+  /**
+    * Executes some code in context of a MongoDB client session, within a transaction.
+    * After the [[Task]] finishes, fails or is cancelled, the transaction is either committed or aborted depending
+    * on the outcome and the session is closed.
+    *
+    * Note: in order for actual MongoDB operations to be associated with the session and the transaction,
+    * you need to use `withSession` on [[TypedMongoClient]], [[TypedMongoDatabase]] or [[TypedMongoCollection]]
+    * and use the returned copy of these objects.
+    */
   def inTransaction[T](
     sessionOptions: ClientSessionOptions = ClientSessionOptions.builder().build(),
     transactionOptions: TransactionOptions = TransactionOptions.builder().build(),

commons-mongo/jvm/src/main/scala/com/avsystem/commons/mongo/typed/TypedMongoCollection.scala

@@ -19,8 +19,8 @@ class TypedMongoCollection[E <: BaseMongoEntity] private(
   val nativeCollection: MongoCollection[E],
   docCollection: MongoCollection[BsonDocument],
   val clientSession: Opt[TypedClientSession],
-)(
-  implicit meta: MongoEntityMeta[E]
+)(implicit
+  meta: MongoEntityMeta[E]
 ) extends DataTypeDsl[E] with TypedMongoUtils {
 
   def this(

commons-mongo/jvm/src/main/scala/com/avsystem/commons/mongo/typed/TypedMongoDatabase.scala

@@ -10,6 +10,9 @@ import monix.eval.Task
 import monix.reactive.Observable
 import org.bson.Document
 
+/**
+  * Better typed wrapper over [[MongoDatabase]].
+  */
 class TypedMongoDatabase(
   val nativeDatabase: MongoDatabase,
   val clientSession: OptArg[TypedClientSession] = OptArg.Empty,

commons-mongo/jvm/src/main/scala/com/avsystem/commons/mongo/typed/TypedMongoUtils.scala

@@ -20,5 +20,12 @@ trait TypedMongoUtils {
   protected final def multi[T](publisher: Publisher[T]): Observable[T] =
     Observable.fromReactivePublisher(publisher)
 
+  /**
+    * Transforms an expression `method(nullableArg, moreArgs)` into
+    * `if(nullableArg ne null) method(nullableArg, moreArgs) else method(moreArgs)`.
+    *
+    * Reduces boilerplate associated with calling overloaded methods from Mongo ReactiveStreams driver that
+    * may or may not take `ClientSession` as its first argument (non-nullable).
+    */
   protected def optionalizeFirstArg[T](expr: T): T = macro MiscMacros.optionalizeFirstArg
 }