From 4d33be7e45da815f9ebcb73543baed153b357254 Mon Sep 17 00:00:00 2001
From: Marco Ferrer <35935108+marcoferrer@users.noreply.github.com>
Date: Wed, 13 Mar 2019 21:39:46 -0400
Subject: [PATCH] update docs for ServiceScope

---
 CHANGELOG.md                                  |  1 +
 .../coroutines/server/ServiceScope.kt         | 36 +++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2832cad..477ddd9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ _2018-\*\*-\*\*_
 * Fix: Remove unnecessary creation of `CoroutineScope` in `newSendChannelFromObserver`
 * New: Introduce `ServiceScope` interface and remove `CoroutineScope` from generated service classes
 * New: Use `Message.getDefaultInstance()` as default value of stub request parameters
+* New: Increased code coverage across the board
 * Deprecated: Legacy service stub rpc builders in favor of new back-pressure supporting stub APIs  
 
 #### gRPC Stub Extension 
diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServiceScope.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServiceScope.kt
index c81afeb..98544ef 100644
--- a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServiceScope.kt
+++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServiceScope.kt
@@ -16,10 +16,46 @@
 
 package com.github.marcoferrer.krotoplus.coroutines.server
 
+import kotlinx.coroutines.CoroutineScope
 import kotlin.coroutines.CoroutineContext
 
+
+/**
+ * Defines a scope for gRPC service implementations. The generated abstract base class for every gRPC coroutine service
+ * implements this interface. This interface allows service implementations to define the initial [CoroutineContext]
+ * that will be used to populate a new [CoroutineScope] for each incoming rpc method invocation.
+ *
+ * Usage of this interface from within service implementations may look like this:
+ *
+ * ```
+ * // GreeterCoroutineGrpc.GreeterImplBase implements the [ServiceScope] interface
+ *
+ * class GreeterServiceImpl : GreeterCoroutineGrpc.GreeterImplBase() {
+ *
+ *     // Attach the thread local logging context (which was initially setup up in a server interceptor)
+ *     // for every new rpc invocation.
+ *     val initialContext: CoroutineContext
+ *         get() = Dispatchers.Default + MDCContext()
+ *
+ *     suspend fun sayHello(request: HelloRequest): HelloReply {
+ *         ...
+ *     }
+ * }
+ * ```
+ *
+ * Details showing usage during server rpc invocation at:
+ * - Unary RPCs: [ServiceScope.serverCallUnary]
+ * - Client Streaming RPCs: [ServiceScope.serverCallClientStreaming]
+ * - Server Streaming RPCs: [ServiceScope.serverCallServerStreaming]
+ * - Bidirectional RPCs: [ServiceScope.serverCallBidiStreaming]
+ *
+ */
 interface ServiceScope {
 
+    /**
+     * The context that will be used to create a new [CoroutineScope] for
+     * every incoming rpc request.
+     */
     val initialContext: CoroutineContext
 
 }
\ No newline at end of file