From 45d543be8e8a232384f63c23b67e0890c145f547 Mon Sep 17 00:00:00 2001
From: Jay Ohms <jay.ohms@gmail.com>
Date: Tue, 27 Feb 2024 14:35:59 -0500
Subject: [PATCH] Add API docs to the top-level error types

---
 .../main/kotlin/dev/hotwire/turbo/errors/HttpError.kt    | 9 +++++++++
 .../main/kotlin/dev/hotwire/turbo/errors/LoadError.kt    | 4 ++++
 .../kotlin/dev/hotwire/turbo/errors/TurboVisitError.kt   | 3 +++
 .../src/main/kotlin/dev/hotwire/turbo/errors/WebError.kt | 5 +++++
 .../main/kotlin/dev/hotwire/turbo/errors/WebSslError.kt  | 5 +++++
 5 files changed, 26 insertions(+)

diff --git a/turbo/src/main/kotlin/dev/hotwire/turbo/errors/HttpError.kt b/turbo/src/main/kotlin/dev/hotwire/turbo/errors/HttpError.kt
index 5fdf8956..dcc7b1b5 100644
--- a/turbo/src/main/kotlin/dev/hotwire/turbo/errors/HttpError.kt
+++ b/turbo/src/main/kotlin/dev/hotwire/turbo/errors/HttpError.kt
@@ -2,10 +2,16 @@ package dev.hotwire.turbo.errors
 
 import android.webkit.WebResourceResponse
 
+/**
+ * Errors representing HTTP status codes received from the server.
+ */
 sealed interface HttpError : TurboVisitError {
     val statusCode: Int
     val reasonPhrase: String?
 
+    /**
+     * Errors representing HTTP client errors in the 400..499 range.
+     */
     sealed interface ClientError : HttpError {
         data object BadRequest : ClientError {
             override val statusCode = 400
@@ -78,6 +84,9 @@ sealed interface HttpError : TurboVisitError {
         ) : ClientError
     }
 
+    /**
+     * Errors representing HTTP server errors in the 500..599 range.
+     */
     sealed interface ServerError : HttpError {
         data object InternalServerError : ServerError {
             override val statusCode = 500
diff --git a/turbo/src/main/kotlin/dev/hotwire/turbo/errors/LoadError.kt b/turbo/src/main/kotlin/dev/hotwire/turbo/errors/LoadError.kt
index 4c32143a..07358dd7 100644
--- a/turbo/src/main/kotlin/dev/hotwire/turbo/errors/LoadError.kt
+++ b/turbo/src/main/kotlin/dev/hotwire/turbo/errors/LoadError.kt
@@ -1,5 +1,9 @@
 package dev.hotwire.turbo.errors
 
+/**
+ * Errors representing when turbo.js or the native adapter fails
+ * to load on a page.
+ */
 sealed interface LoadError : TurboVisitError {
     val description: String
 
diff --git a/turbo/src/main/kotlin/dev/hotwire/turbo/errors/TurboVisitError.kt b/turbo/src/main/kotlin/dev/hotwire/turbo/errors/TurboVisitError.kt
index c84ee42b..d6565618 100644
--- a/turbo/src/main/kotlin/dev/hotwire/turbo/errors/TurboVisitError.kt
+++ b/turbo/src/main/kotlin/dev/hotwire/turbo/errors/TurboVisitError.kt
@@ -1,3 +1,6 @@
 package dev.hotwire.turbo.errors
 
+/**
+ * Represents all possible errors received when attempting to load a page.
+ */
 sealed interface TurboVisitError
diff --git a/turbo/src/main/kotlin/dev/hotwire/turbo/errors/WebError.kt b/turbo/src/main/kotlin/dev/hotwire/turbo/errors/WebError.kt
index dc8ba5e8..36d4c7af 100644
--- a/turbo/src/main/kotlin/dev/hotwire/turbo/errors/WebError.kt
+++ b/turbo/src/main/kotlin/dev/hotwire/turbo/errors/WebError.kt
@@ -5,6 +5,11 @@ import androidx.webkit.WebViewClientCompat
 import androidx.webkit.WebViewFeature
 import androidx.webkit.WebViewFeature.isFeatureSupported
 
+/**
+ * Errors representing WebViewClient.ERROR_* errors received
+ * from the WebView when attempting to load a page.
+ * https://developer.android.com/reference/android/webkit/WebViewClient
+ */
 sealed interface WebError : TurboVisitError {
     val errorCode: Int
     val description: String?
diff --git a/turbo/src/main/kotlin/dev/hotwire/turbo/errors/WebSslError.kt b/turbo/src/main/kotlin/dev/hotwire/turbo/errors/WebSslError.kt
index 28d1d113..2da75bc2 100644
--- a/turbo/src/main/kotlin/dev/hotwire/turbo/errors/WebSslError.kt
+++ b/turbo/src/main/kotlin/dev/hotwire/turbo/errors/WebSslError.kt
@@ -2,6 +2,11 @@ package dev.hotwire.turbo.errors
 
 import android.net.http.SslError
 
+/**
+ * Errors representing SslError.SSL_* errors received
+ * from the WebView when attempting to load a page.
+ * https://developer.android.com/reference/android/net/http/SslError
+ */
 sealed interface WebSslError : TurboVisitError {
     val errorCode: Int
     val description: String?