You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ma...@apache.org on 2023/01/30 01:14:10 UTC
[logging-log4j-kotlin] 10/11: Update docs
This is an automated email from the ASF dual-hosted git repository.
mattsicker pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4j-kotlin.git
commit 499478be6b6dec1240060a9a94d2e6f698c239a8
Author: Matt Sicker <ma...@apache.org>
AuthorDate: Sun Jan 29 19:07:48 2023 -0600
Update docs
---
README.md | 35 ++++++++++++++++++-----------------
src/site/asciidoc/index.adoc | 6 ++----
src/site/asciidoc/usage.adoc | 2 +-
3 files changed, 21 insertions(+), 22 deletions(-)
diff --git a/README.md b/README.md
index a2f72a8..080b691 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
# [Apache Log4j 2 (Kotlin API)](http://logging.apache.org/log4j/2.x/)
-Log4j Kotlin API is a Kotlin logging facade based on Log4j 2. Log4j Kotlin API provides Log4j 2 as its
+Log4j Kotlin API is a Kotlin logging facade based on Apache Log4j API. Log4j Kotlin API provides Log4j Core 2.x as its
default logging implementation, but this is not strictly required (e.g., this API can also be used with Logback
or other Log4j 2 API provider implementations). Idiomatic Kotlin features are provided as an alternative to using
-the Log4j 2 Java API.
+the Log4j Java API.
[](https://search.maven.org/artifact/org.apache.logging.log4j/log4j-api-kotlin)
[](https://builds.apache.org/job/Logging/job/log4j-kotlin/job/master/)
@@ -100,32 +100,33 @@ assert(ContextStack.empty)
## Documentation
-The Kotlin's Log4j 2 User's Guide is available [here](https://logging.apache.org/log4j/kotlin/index.html).
+The user guide for Log4j Kotlin API is [available here](https://logging.apache.org/log4j/kotlin/).
## Requirements
-Log4j Kotlin API requires at least Java 8. This also requires Log4j 2 API, but it is specified as transitive
-dependencies automatically if you are using SBT, Maven, Gradle, or some other similar build system. This also
-requires Log4j 2 Core (or possibly an other implementation of Log4j 2 API) as a runtime dependency. Some
-Log4j 2 Core features require optional dependencies which are documented in the
-[Log4j 2 manual](https://logging.apache.org/log4j/2.x/manual/index.html).
+The minimum requirements for Log4j Kotlin API are Java 8 and Kotlin 1.3.x. Log4j API is also required, though
+this is already specified as a transitive dependency for `log4j-api-kotlin` which is supported by common build
+systems like Maven, Gradle, SBT, and Ivy. A logging backend library such as Log4j Core, Logback, or `java.util.logging`
+is required at runtime for an application to configure the output of logging. Log4j Core version 2.x includes
+various plugins and configuration options which may require additional dependencies. See the
+[Log4j manual](https://logging.apache.org/log4j/2.x/manual/) for more details.
-The Kotlin API requires the full `kotlin-reflect` dependency in order to name loggers appropriately, and
-optionally `kotlinx-coroutines-core` to set the mapped diagnostic context for a coroutine.
+This library requires a dependency on `kotlin-reflect` in order to determine appropriate logger names from
+classes. When `kotlinx-coroutines-core` is available, this library provides a `CoroutineThreadContext` for
+supporting the `ThreadContext` API (and MDC/NDC APIs) in coroutines.
-The Kotlin dependencies are not exposed transitively -- for maximum compatibility logging-log4j-kotlin is built
-with Kotlin 1.3, producing binaries that should be forward compatible. For maximum compat, the Kotlin dependencies
-are "provided" i.e. consumers of this library need to depend on them directly rather than transitively, thus
-avoiding version clashes.
+This library declares a `provided` scope dependency on Kotlin 1.3. This is to ensure that consumers of this library
+specify the proper Kotlin dependencies corresponding to the version of the Kotlin language in use and avoiding
+dependency conflicts.
## License
-Apache Log4j 2 is distributed under the [Apache License, version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
+Apache Log4j Kotlin API is distributed under the [Apache License, version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
## Download
-[How to download Log4j](http://logging.apache.org/log4j/2.x/download.html),
-and [how to use it from Maven, Ivy and Gradle](http://logging.apache.org/log4j/2.x/maven-artifacts.html).
+[How to download Log4j Kotlin API](http://logging.apache.org/log4j/kotlin/download.html),
+and [how to use it from Maven, Ivy and Gradle](http://logging.apache.org/log4j/kotlin/artifacts.html).
You can access the latest development snapshot by using the Maven repository `https://repository.apache.org/snapshots`,
see [Snapshot builds](https://logging.apache.org/log4j/2.x/maven-artifacts.html#Snapshot_builds).
diff --git a/src/site/asciidoc/index.adoc b/src/site/asciidoc/index.adoc
index 93dd3da..4a18410 100644
--- a/src/site/asciidoc/index.adoc
+++ b/src/site/asciidoc/index.adoc
@@ -17,11 +17,9 @@
= Apache Log4j Kotlin API
:toc: left
-Log4j Kotlin API is a https://kotlinlang.org/[Kotlin] logging facade based on https://logging.apache.org/log4j/2.x/[Log4j 2].
+Log4j Kotlin API is a https://kotlinlang.org/[Kotlin] logging facade based on https://logging.apache.org/log4j/2.x/[Apache Log4j API].
-Log4j Kotlin API uses Log4j 2.x as its logging backend.
-
-Log4j Kotlin API uses Log4j 2.x as its logging backend by default, but this can also be replaced with compatible libraries (e.g., https://logback.qos.ch/[Logback]).
+Log4j Kotlin API uses Log4j Core 2.x as its logging backend by default, but this can also be replaced with compatible libraries (e.g., https://logback.qos.ch/[Logback]).
While this library is not required to use Log4j API in Kotlin, it does provide idiomatic Kotlin APIs which are friendlier to use in Kotlin programs than the Java APIs.
diff --git a/src/site/asciidoc/usage.adoc b/src/site/asciidoc/usage.adoc
index b017926..29a48ed 100644
--- a/src/site/asciidoc/usage.adoc
+++ b/src/site/asciidoc/usage.adoc
@@ -98,7 +98,7 @@ assert(ContextStack.empty)
=== API Documentation
-See https://logging.apache.org/TODO[KDocs].
+See https://logging.apache.org/log4j/kotlin/log4j-api-kotlin/org.apache.logging.log4j.kotlin/[KDocs].
=== Configuration