Add doc for the public API classes and methods

Author: Oleg

src/commonMain/kotlin/com/github/optimumcode/json/pointer/JsonPointer.kt

@@ -3,9 +3,17 @@ package com.github.optimumcode.json.pointer
 import kotlin.jvm.JvmField
 import kotlin.jvm.JvmStatic
 
+/**
+ * Function to create [JsonPointer].
+ * It is a more convenient way to create a JSON pointer rather than using [JsonPointer.compile] function
+ */
 public fun JsonPointer(path: String): JsonPointer =
   JsonPointer.compile(path)
 
+/**
+ * Implementation of a JSON pointer described in the specification
+ * [RFC6901](https://datatracker.ietf.org/doc/html/rfc6901).
+ */
 public sealed class JsonPointer(
   private val fullPath: String,
   private val pathOffset: Int,
@@ -40,11 +48,22 @@ public sealed class JsonPointer(
     internal const val SEPARATOR: Char = '/'
     internal const val QUOTATION: Char = '~'
 
+    /**
+     * An empty [JsonPointer]. The empty JSON pointer corresponds to the current JSON element.s
+     */
     @JvmField
     public val ROOT: JsonPointer = EmptyPointer
 
     private const val DEFAULT_BUFFER_CAPACITY = 32
 
+    /**
+     * Returns instance of the [JsonPointer] class.
+     * If the [expr] is an empty string the [JsonPointer.ROOT] will be returned.
+     *
+     * If the [expr] is not an empty string it must start from the `/` character.
+     *
+     * @throws IllegalArgumentException the [expr] does not start from `/`
+     */
     @JvmStatic
     public fun compile(expr: String): JsonPointer {
       return if (expr.isEmpty()) {

src/commonMain/kotlin/com/github/optimumcode/json/pointer/extensions.kt

@@ -9,6 +9,15 @@ import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.JsonPrimitive
 import kotlin.jvm.JvmName
 
+/**
+ * Creates a new [JsonPointer] that points to an [index] in the array.
+ *
+ * Example:
+ * ```kotlin
+ * val pointer = JsonPointer("/test")
+ * val index = pointer[0] // "/test/0"
+ * ```
+ */
 public operator fun JsonPointer.get(index: Int): JsonPointer =
   JsonPointer(
     buildString {
@@ -21,6 +30,15 @@ public operator fun JsonPointer.get(index: Int): JsonPointer =
     },
   )
 
+/**
+ * Creates a new [JsonPointer] that points to a [property] passed as a parameter.
+ *
+ * Example:
+ *
+ * ```kotlin
+ * val pointer = JsonPointer.ROOT / "prop1" / "prop2"  // "/prop1/prop2"
+ * ```
+ */
 public operator fun JsonPointer.div(property: String): JsonPointer =
   JsonPointer(
     buildString {
@@ -33,6 +51,23 @@ public operator fun JsonPointer.div(property: String): JsonPointer =
     },
   )
 
+/**
+ * Appends [otherPointer] to the current [JsonPointer].
+ * If current or [otherPointer] JSON pointer is an empty JSON pointer. The first not-empty pointer will be returned.
+ * (or an empty pointer if both pointers are empty).
+ *
+ * If both are not-empty pointers the resulting JSON pointer will start from the current one
+ * and [otherPointer] appended at the end.
+ *
+ * Example:
+ * ```kotlin
+ * val pointer = JsonPointer.ROOT + JsonPointer.ROOT // ""
+ *
+ * val pointer = JsonPointer.ROOT + JsonPointer("/test") // "/test"
+ *
+ * val pointer = JsonPointer("/prop") + JsonPointer("/test") // "/prop/test"
+ * ```
+ */
 public operator fun JsonPointer.plus(otherPointer: JsonPointer): JsonPointer {
   if (this is EmptyPointer) {
     return otherPointer
@@ -53,16 +88,39 @@ public operator fun JsonPointer.plus(otherPointer: JsonPointer): JsonPointer {
   )
 }
 
+/**
+ * Returns a [JsonPointer] that is a relative pointer from current pointer to [other] pointer.
+ * If current pointer is an empty pointer the [other] pointer will be returned.
+ *
+ * If the [other] pointer is not starts from the current pointer the [other] pointer will be returned.
+ *
+ * Example:
+ * ```kotlin
+ * val pointer = JsonPointer("/test").relative(JsonPointer("/test/0/data") // "/0/data"
+ * ```
+ *
+ * @throws IllegalArgumentException when [other] is an empty pointer
+ */
 public fun JsonPointer.relative(other: JsonPointer): JsonPointer {
   if (this is EmptyPointer) {
     return other
   }
   require(other !is EmptyPointer) { "empty pointer is not relative to any" }
   val currentValue = this.toString()
   val otherValue = other.toString()
-  return JsonPointer(otherValue.substringAfter(currentValue))
+  val relative = otherValue.substringAfter(currentValue)
+  return if (relative == otherValue) {
+    other
+  } else {
+    JsonPointer(relative)
+  }
 }
 
+/**
+ * Extracts [JsonElement] from the current JSON element that corresponds to the specified [JsonPointer].
+ *
+ * If [pointer] path does not exist in the current [JsonElement] the `null` will be returned.
+ */
 public tailrec fun JsonElement.at(pointer: JsonPointer): JsonElement? {
   return when (pointer) {
     is EmptyPointer -> this

src/commonMain/kotlin/com/github/optimumcode/json/schema/ErrorCollector.kt

@@ -13,6 +13,9 @@ public fun interface ErrorCollector {
   public fun onError(error: ValidationError)
 
   public companion object {
+    /**
+     * Empty [ErrorCollector] can be used if you need only a simple `true`/`false` as a result of the validation
+     */
     @JvmField
     public val EMPTY: ErrorCollector = ErrorCollector { }
   }

src/commonMain/kotlin/com/github/optimumcode/json/schema/JsonSchema.kt

@@ -9,16 +9,30 @@ import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonElement
 import kotlin.jvm.JvmStatic
 
+/**
+ * JSON schema implementation. It allows you to validate the [JsonElement] against this schema
+ * and collect errors using [ErrorCollector]
+ */
 public class JsonSchema internal constructor(
   private val assertion: JsonSchemaAssertion,
   private val references: Map<RefId, JsonSchemaAssertion>,
 ) {
+  /**
+   * Validates [value] against this [JsonSchema].
+   * If the [value] is valid against the schema the function returns `true`.
+   * Otherwise, it returns `false`.
+   *
+   * All reported errors will be reported to [ErrorCollector.onError]
+   */
   public fun validate(value: JsonElement, errorCollector: ErrorCollector): Boolean {
     val context = DefaultAssertionContext(JsonPointer.ROOT, references)
     return assertion.validate(value, context, errorCollector)
   }
 
   public companion object {
+    /**
+     * Loads JSON schema from the [schema] definition
+     */
     @JvmStatic
     public fun fromDescription(schema: String): JsonSchema {
       val schemaElement: JsonElement = Json.parseToJsonElement(schema)