Improve documentation

Closes #1

Signed-off-by: Dmitry Sulman <[email protected]>

Author: dmitrysulman

build.gradle.kts

@@ -1,7 +1,6 @@
 plugins {
     kotlin("jvm")
     alias(libs.plugins.dokka)
-    alias(libs.plugins.dokka.javadoc)
     alias(libs.plugins.jreleaser)
 }
 

buildSrc/build.gradle.kts

@@ -8,14 +8,21 @@ repositories {
 }
 
 kotlin {
-    jvmToolchain(17)
+    jvmToolchain(libs.versions.java.get().toInt())
 }
 
 dependencies {
+    // To make libs accessible from conventions.gradle.kts
+    // https://github.com/gradle/gradle/issues/15383#issuecomment-779893192
+    implementation(files(libs.javaClass.superclass.protectionDomain.codeSource.location))
+
+    // Override the old Jackson version that comes with dokka
+    // to fix READ_DATE_TIMESTAMPS_AS_NANOSECONDS on Jreleaser tasks
+    // https://github.com/dependency-check/DependencyCheck/issues/6192
     implementation(platform(libs.jackson.bom))
 
-    implementation(libs.dokka.gradlePlugin)
-    implementation(libs.dokka.javadocPlugin)
-    implementation(libs.kotlin.gradlePlugin)
-    implementation(libs.ktlintPlugin)
+    implementation(libs.dokka.javadoc.plugin)
+    implementation(libs.dokka.plugin)
+    implementation(libs.kotlin.plugin)
+    implementation(libs.ktlint.plugin)
 }

buildSrc/src/main/kotlin/conventions.gradle.kts

@@ -1,3 +1,4 @@
+import org.gradle.accessors.dm.LibrariesForLibs
 import org.jlleitschuh.gradle.ktlint.KtlintExtension
 
 plugins {
@@ -9,6 +10,9 @@ plugins {
     `maven-publish`
 }
 
+// https://github.com/gradle/gradle/issues/15383#issuecomment-779893192
+val libs = the<LibrariesForLibs>()
+
 repositories {
     mavenCentral()
     maven {
@@ -20,7 +24,7 @@ repositories {
 }
 
 kotlin {
-    jvmToolchain(17)
+    jvmToolchain(libs.versions.java.get().toInt())
 }
 
 java {
@@ -50,6 +54,31 @@ val dokkaJavadocJar by tasks.registering(Jar::class) {
     archiveClassifier.set("javadoc")
 }
 
+dokka {
+    dokkaSourceSets.configureEach {
+        includes.from("./src/main/resources/dokka/Module.md")
+        sourceLink {
+            localDirectory.set(file("src/main/kotlin"))
+            remoteUrl("https://github.com/dmitrysulman/logback-access-reactor-netty/tree/main/${project.name}/src/main/kotlin")
+            remoteLineSuffix.set("#L")
+        }
+        externalDocumentationLinks {
+            register("reactor-netty-docs") {
+                url("https://javadoc.io/doc/io.projectreactor.netty/reactor-netty-http/${libs.versions.reactorNetty.get()}/")
+                packageListUrl("https://javadoc.io/doc/io.projectreactor.netty/reactor-netty-http/${libs.versions.reactorNetty.get()}/package-list")
+            }
+            register("logback-access-docs") {
+                url("https://javadoc.io/doc/ch.qos.logback.access/logback-access-common/${libs.versions.logbackAccess.get()}/")
+                packageListUrl("https://javadoc.io/doc/ch.qos.logback.access/logback-access-common/${libs.versions.logbackAccess.get()}/element-list")
+            }
+            register("logback-core-docs") {
+                url("https://javadoc.io/doc/ch.qos.logback/logback-core/${libs.versions.logbackClassic.get()}/")
+                packageListUrl("https://javadoc.io/doc/ch.qos.logback/logback-core/${libs.versions.logbackClassic.get()}/element-list")
+            }
+        }
+    }
+}
+
 publishing {
     publications {
         create<MavenPublication>("maven") {
@@ -100,7 +129,7 @@ tasks.jacocoTestReport {
 }
 
 configure<KtlintExtension> {
-    version = "1.5.0"
+    version = libs.versions.ktlint
     additionalEditorconfig.set(
         mapOf(
             "ktlint_standard_backing-property-naming" to "disabled"

gradle/libs.versions.toml

@@ -1,11 +1,13 @@
 [versions]
 dokka = "2.0.0"
 jackson = "2.19.0"
+java = "17"
 jreleaser = "1.18.0"
 junit = "5.12.2"
 kotest = "5.9.1"
 kotlin = "2.1.21"
 kotlinxCoroutines = "1.10.2"
+ktlint = "1.5.0"
 ktlintPlugin = "12.2.0"
 logbackAccess = "2.0.6"
 logbackClassic = "1.5.18"
@@ -14,24 +16,22 @@ reactorNetty = "1.2.6"
 slf4j = "2.0.17"
 
 [libraries]
-dokka-gradlePlugin = { group = "org.jetbrains.dokka", name = "dokka-gradle-plugin", version.ref = "dokka" }
-dokka-javadocPlugin = { group = "org.jetbrains.dokka-javadoc", name = "org.jetbrains.dokka-javadoc.gradle.plugin", version.ref = "dokka" }
-jackson-bom = { group = "com.fasterxml.jackson", name = "jackson-bom", version.ref = "jackson" } # Override the old jackson version that comes with dokka
+dokka-plugin = { group = "org.jetbrains.dokka", name = "org.jetbrains.dokka.gradle.plugin", version.ref = "dokka" }
+dokka-javadoc-plugin = { group = "org.jetbrains.dokka-javadoc", name = "org.jetbrains.dokka-javadoc.gradle.plugin", version.ref = "dokka" }
+jackson-bom = { group = "com.fasterxml.jackson", name = "jackson-bom", version.ref = "jackson" }
 junit-jupiter = { group = "org.junit.jupiter", name = "junit-jupiter", version.ref = "junit" }
 junit-platformLauncher = { group = "org.junit.platform", name = "junit-platform-launcher" }
 kotest-assertions-core-jvm = { group = "io.kotest", name = "kotest-assertions-core-jvm", version.ref = "kotest" }
-kotlin-gradlePlugin = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-plugin", version.ref = "kotlin" }
+kotlin-plugin = { group = "org.jetbrains.kotlin.jvm", name = "org.jetbrains.kotlin.jvm.gradle.plugin", version.ref = "kotlin" }
 kotlinx-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "kotlinxCoroutines" }
 kotlinx-coroutines-reactor = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-reactor", version.ref = "kotlinxCoroutines" }
-ktlintPlugin = { group = "org.jlleitschuh.gradle.ktlint", name = "org.jlleitschuh.gradle.ktlint.gradle.plugin", version.ref = "ktlintPlugin" }
+ktlint-plugin = { group = "org.jlleitschuh.gradle.ktlint", name = "org.jlleitschuh.gradle.ktlint.gradle.plugin", version.ref = "ktlintPlugin" }
 logback-access-common = { group = "ch.qos.logback.access", name = "logback-access-common", version.ref = "logbackAccess" }
 logback-classic = { group = "ch.qos.logback", name = "logback-classic", version.ref = "logbackClassic" }
-logback-core = { group = "ch.qos.logback", name = "logback-core", version.ref = "logbackClassic" }
 mockk = { group = "io.mockk", name = "mockk", version.ref = "mockk" }
 reactorNetty-http = { group = "io.projectreactor.netty", name = "reactor-netty-http", version.ref = "reactorNetty" }
 slf4j-api = { group = "org.slf4j", name = "slf4j-api", version.ref = "slf4j" }
 
 [plugins]
 dokka = { id = "org.jetbrains.dokka" }
-dokka-javadoc = { id = "org.jetbrains.dokka-javadoc" }
 jreleaser = { id = "org.jreleaser", version.ref = "jreleaser" }

logback-access-reactor-netty/build.gradle.kts

@@ -14,7 +14,6 @@ dependencies {
     testImplementation(libs.kotlinx.coroutines.core)
     testImplementation(libs.kotlinx.coroutines.reactor)
     testImplementation(libs.logback.classic)
-    testImplementation(libs.logback.core)
     testImplementation(libs.mockk)
 
     testRuntimeOnly(libs.junit.platformLauncher)

logback-access-reactor-netty/src/main/kotlin/io/github/dmitrysulman/logback/access/reactor/netty/AccessEvent.kt

@@ -18,14 +18,15 @@ import java.util.Enumeration
  * This class implements the Logback Access [IAccessEvent] interface to provide detailed information about access logs,
  * including request and response data, headers, cookies, and contextual information.
  *
- * @constructor Initializes an [AccessEvent] instance with the given [AccessLogArgProvider] and [AccessContext].
- * The [AccessLogArgProvider] supplies information about the HTTP request and response to populate the event's details.
- * The [AccessContext] facilitates access logging within the specified context.
- *
  * This class includes various lazy-loaded properties to efficiently retrieve detailed information about
  * the request and response only when needed. It supports deferred processing of logging data through
  * the `prepareForDeferredProcessing` method, ensuring all necessary attributes are initialized.
  *
+ * @constructor Initializes an [AccessEvent] instance with the given [AccessLogArgProvider] and [AccessContext].
+ *
+ * The [AccessLogArgProvider] supplies information about the HTTP request and response to populate the event's details.
+ * The [AccessContext] facilitates access logging within the specified context.
+ *
  * @author Dmitry Sulman
  * @see IAccessEvent
  * @see AccessLog

logback-access-reactor-netty/src/main/kotlin/io/github/dmitrysulman/logback/access/reactor/netty/AccessLog.kt

@@ -17,6 +17,7 @@ import reactor.netty.http.server.logging.AccessLog as ReactorAccessLog
  * access-related information.
  *
  * @constructor Initializes an [AccessLog] instance with the given [AccessContext] and [AccessLogArgProvider].
+ *
  * The [AccessContext] facilitates access logging within the specified context.
  * The [AccessLogArgProvider] supplies information about the HTTP request and response to populate the event's details.
  *

logback-access-reactor-netty/src/main/kotlin/io/github/dmitrysulman/logback/access/reactor/netty/ReactorNettyAccessLogFactory.kt

@@ -111,7 +111,7 @@ class ReactorNettyAccessLogFactory : AccessLogFactory {
      * Primary constructor for the [ReactorNettyAccessLogFactory] class.
      *
      * Initializes the access log factory with the configuration file, a new [JoranConfigurator] instance,
-     * and debug mode set to `false`.The configuration file is taken from the `logback.access.reactor.netty.config`
+     * and debug mode set to `false`. The configuration file is taken from the `logback.access.reactor.netty.config`
      * system property or from the `logback-access.xml` file if the property is not set. If no default configuration
      * file is found, initialization will skip configuration steps.
      */

logback-access-reactor-netty/src/main/resources/dokka/Module.md

@@ -0,0 +1,7 @@
+# Module logback-access-reactor-netty
+
+A Java/Kotlin library that integrates Logback Access with Reactor Netty HTTP server, providing comprehensive access logging capabilities.
+
+# Package io.github.dmitrysulman.logback.access.reactor.netty
+
+This package contains core classes of the library.