Improve docs

src/main/kotlin/no/liflig/documentstore/entity/EntityList.kt

@@ -13,7 +13,7 @@ import no.liflig.documentstore.dao.ListWithTotalCount
 @Deprecated(
     "Use List<Versioned<T>> instead. Since Versioned is now replacing VersionedEntity, there is no longer a need to shorten this type signature.",
     /* IntelliJ can't correctly replace with nested generics, so it replaces with List<T> instead
-       (what we want is List<Versioned<T>>. I think it's better to provide no automatic replacement
+       (what we want is List<Versioned<T>>). I think it's better to provide no automatic replacement
        than a wrong one.
     ReplaceWith(
         "List<Versioned<T>>",
@@ -71,8 +71,8 @@ fun <T : Entity<*>> EntityList<T>.forEachEntity(action: (T) -> Unit) {
 @Deprecated(
     "Use ListWithTotalCount<Versioned<T>> instead (no.liflig.documentstore.repository.ListWithTotalCount). Since Versioned is now replacing VersionedEntity, there is no longer a need to shorten this type signature.",
     /* IntelliJ can't correctly replace with nested generics, so it replaces with
-       ListWithTotalCount<T> instead (what we want is ListWithTotalCount<Versioned<T>>. I think it's
-       better to provide no automatic replacement than a wrong one.
+       ListWithTotalCount<T> instead (what we want is ListWithTotalCount<Versioned<T>>). I think
+       it's better to provide no automatic replacement than a wrong one.
     ReplaceWith(
         "ListWithTotalCount<Versioned<T>>",
         imports = ["no.liflig.documentstore.entity.Versioned", "no.liflig.documentstore.repository.ListWithTotalCount"],

src/main/kotlin/no/liflig/documentstore/entity/Version.kt

@@ -22,7 +22,7 @@ data class Version(val value: Long) {
  * A wrapper around a database entity, providing metadata such as the current [Version] (used for
  * optimistic locking in [Repository.update][no.liflig.documentstore.repository.Repository.update]
  * and [delete][no.liflig.documentstore.repository.Repository.delete]), when it was created and when
- * it was last modified..
+ * it was last modified.
  */
 data class Versioned<out EntityT : Entity<*>>(
     val item: EntityT,

src/main/kotlin/no/liflig/documentstore/entity/VersionedListUtils.kt

@@ -15,7 +15,7 @@ inline fun <EntityT : Entity<*>> List<Versioned<EntityT>>.mapEntities(
 
 /**
  * Utility function for mapping a list of entities, but keeping the same version for each element.
- * Discards entities that return null from the given map function.
+ * Discards entities that return null from the given mapper function.
  */
 inline fun <EntityT : Entity<*>> List<Versioned<EntityT>>.mapEntitiesNotNull(
     mapper: (EntityT) -> EntityT?
@@ -54,7 +54,7 @@ inline fun <EntityT : Entity<*>> ListWithTotalCount<Versioned<EntityT>>.mapEntit
 
 /**
  * Utility function for mapping a list of entities, but keeping the same version for each element
- * and the same total count. Discards entities that return null from the given map function.
+ * and the same total count. Discards entities that return null from the given mapper function.
  */
 fun <EntityT : Entity<*>> ListWithTotalCount<Versioned<EntityT>>.mapEntitiesNotNull(
     mapper: (EntityT) -> EntityT?

src/main/kotlin/no/liflig/documentstore/repository/Repository.kt

@@ -1,4 +1,4 @@
-@file:Suppress("MemberVisibilityCanBePrivate", "unused") // This is a library
+@file:Suppress("MemberVisibilityCanBePrivate") // This is a library, we want to expose fields
 
 package no.liflig.documentstore.repository
 
@@ -145,6 +145,7 @@ open class RepositoryJdbi<EntityIdT : EntityId, EntityT : Entity<EntityIdT>>(
         val updateResult =
             handle
                 .createQuery(
+                    /** See [UpdateResult] for why we use RETURNING here. */
                     """
                       UPDATE "${tableName}"
                       SET
@@ -239,10 +240,10 @@ open class RepositoryJdbi<EntityIdT : EntityId, EntityT : Entity<EntityIdT>>(
    *
    * Example implementing a query where we want to look up users from a list of names:
    * ```
-   * fun getByNames(names: List<String>): EntityList<User> {
-   *     return getByPredicate("data->>'name' = ANY(:names)") {
-   *         bindArray("names", String::class.java, names)
-   *     }
+   * fun getByNames(names: List<String>): List<Versioned<User>> {
+   *   return getByPredicate("data->>'name' = ANY(:names)") {
+   *     bindArray("names", String::class.java, names)
+   *   }
    * }
    * ```
    */
@@ -337,8 +338,10 @@ open class RepositoryJdbi<EntityIdT : EntityId, EntityT : Entity<EntityIdT>>(
       val entities = rows.mapNotNull { row -> row.entity }
       val count =
           rows.firstOrNull()?.count
-          // Should never happen: the query should always return 1 row with the count, even if the
-          // results are empty (see [EntityRowWithCount])
+          /**
+           * Should never happen: the query should always return 1 row with the count, even if the
+           * results are empty (see [EntityRowWithTotalCount]).
+           */
           ?: throw IllegalStateException("Failed to get total count of objects in search query")
 
       return ListWithTotalCount(entities, count)

src/main/kotlin/no/liflig/documentstore/repository/RowMapper.kt

@@ -83,7 +83,7 @@ internal fun <EntityT : Entity<*>> createRowMapperWithTotalCount(
   return RowMapper { resultSet, context ->
     val row = kotlinMapper.map(resultSet, context) as EntityRowWithTotalCount
 
-    /** @see EntityRowWithTotalCount */
+    /** See [EntityRowWithTotalCount]. */
     val entity =
         if (row.data != null &&
             row.version != null &&