Improve docs.

mentions/src/main/kotlin/io/spine/examples/pingh/mentions/GitHubClientProcess.kt

@@ -64,7 +64,7 @@ public class GitHubClientProcess :
         archived = true
         builder().setToken(event.token)
         return GitHubTokenUpdated.newBuilder()
-            .setId(builder().id)
+            .setId(GitHubClientId::class.buildBy(event.id.username))
             .setToken(event.token)
             .vBuild()
     }
@@ -118,7 +118,7 @@ public class GitHubClientProcess :
         )
     }
 
-    private fun createUserMentionedEvents(gitHubMentions: List<Mention>): List<EventMessage> =
+    private fun createUserMentionedEvents(gitHubMentions: Set<Mention>): Set<EventMessage> =
         gitHubMentions
             .map { mention ->
                 with(UserMentioned.newBuilder()) {
@@ -133,7 +133,7 @@ public class GitHubClientProcess :
                     vBuild()
                 }
             }
-            .toList()
+            .toSet()
 
     /**
      * Sets the method for fetching mentions from GitHub.

mentions/src/main/kotlin/io/spine/examples/pingh/mentions/GitHubClientRepository.kt

@@ -28,7 +28,6 @@ package io.spine.examples.pingh.mentions
 
 import com.google.errorprone.annotations.OverridingMethodsMustInvokeSuper
 import io.spine.examples.pingh.sessions.SessionId
-import io.spine.examples.pingh.sessions.UserSession
 import io.spine.examples.pingh.sessions.event.UserLoggedIn
 import io.spine.server.procman.ProcessManagerRepository
 import io.spine.server.route.EventRouting
@@ -56,7 +55,7 @@ public class GitHubClientRepository(
     }
 
     /**
-     * Returns ID of [GitHubClient] of provided ID of [UserSession] the same user.
+     * Returns a set with a single GitHub client ID, that corresponds to the passed user session.
      */
     private fun toGitHubClientId(session: SessionId): Set<GitHubClientId> {
         return setOf(GitHubClientId::class.buildBy(session.username))

mentions/src/main/kotlin/io/spine/examples/pingh/mentions/GitHubClientService.kt

@@ -31,13 +31,13 @@ import io.spine.examples.pingh.github.PersonalAccessToken
 import io.spine.examples.pingh.github.Username
 
 /**
- * The external system that requests mentions using the GitHub API.
+ * The service that searches mentions using the GitHub API.
  */
 public interface GitHubClientService {
 
     /**
-     * Requests and returns user [Mention]s by [Username] and [PersonalAccessToken].
+     * Searches and returns user [Mention]s by [Username] and [PersonalAccessToken].
      */
     public fun fetchMentions(username: Username, token: PersonalAccessToken):
-            List<Mention>
+            Set<Mention>
 }

mentions/src/main/kotlin/io/spine/examples/pingh/mentions/MentionsContext.kt

@@ -30,12 +30,19 @@ import io.spine.server.BoundedContext
 import io.spine.server.BoundedContextBuilder
 
 /**
- * Name of the Mentions [BoundedContext].
+ * Name of the Mentions bounded context.
  */
 public const val NAME: String = "Mentions"
 
 /**
- * Configures Mentions [BoundedContext] with repositories.
+ * Configures Mentions bounded context with repositories.
+ *
+ * Mentions bounded context is responsible for working with mentions,
+ * searching for them on the GitHub, storing them, and changing their state.
+ *
+ * The context consists of the [GitHubClientProcess], for work with which the repository is used.
+ * It is also necessary to specify [GitHubClientService] to search for user mentions
+ * using the GitHub API.
  */
 public fun newBuilder(gitHubClientService: GitHubClientService): BoundedContextBuilder =
     BoundedContext.singleTenant(NAME)

mentions/src/main/kotlin/io/spine/examples/pingh/mentions/MentionsParser.kt

@@ -38,26 +38,26 @@ import io.spine.net.Url
 
 /**
  * Converts a JSON containing a list of GitHub items
- * where a user is mentioned to a list of [Mention]s.
+ * where a user is mentioned to a set of [Mention]s.
  */
 public class MentionsParser {
 
     /**
-     * Converts JSON to a list of [Mention]s.
+     * Converts JSON to a set of [Mention]s.
      */
-    public fun parseJson(json: String): List<Mention> {
+    public fun parseJson(json: String): Set<Mention> {
         val responseBuilder = IssuesAndPullRequestsSearchResult.newBuilder()
         JsonFormat.parser()
             .ignoringUnknownFields()
             .merge(json, responseBuilder)
         val response = responseBuilder.vBuild()
-        return mapToMention(response.itemList)
+        return mapToMentions(response.itemList).toSet()
     }
 
     /**
      * Converts list of [IssueOrPullRequestFragment]s to list of [Mention]s.
      */
-    private fun mapToMention(gitHubItems: List<IssueOrPullRequestFragment>):
+    private fun mapToMentions(gitHubItems: List<IssueOrPullRequestFragment>):
             List<Mention> =
         gitHubItems
             .map { fragment ->
@@ -73,5 +73,4 @@ public class MentionsParser {
                     vBuild()
                 }
             }
-            .toList()
 }

mentions/src/test/kotlin/io/spine/examples/pingh/mentions/given/GitHubClientSpecService.kt

@@ -43,17 +43,17 @@ import java.lang.Thread.sleep
 public class GitHubClientSpecService : GitHubClientService {
 
     /**
-     * Parses JSON from the GitHub API response to a list of [Mention]s.
+     * Parses JSON from the GitHub API response to a set of [Mention]s.
      */
     private val mentionsParser = MentionsParser()
 
     /**
-     * Returns list of [Mention]s retrieved from a JSON file in the resource folder.
+     * Returns set of [Mention]s retrieved from a JSON file in the resource folder.
      */
     public override fun fetchMentions(
         username: Username,
         token: PersonalAccessToken
-    ): List<Mention> {
+    ): Set<Mention> {
         val jsonFile = this::class.java.getResource("github_response.json")
         checkNotNull(jsonFile)
         val json = jsonFile.readText(Charsets.UTF_8)