From 262a5e12f7933f05faa4396686432b238d2d0487 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michal=20Mal=C3=A9=C5=99?= <mmaler@redhat.com>
Date: Thu, 28 Nov 2024 11:55:08 +0100
Subject: [PATCH] logging-and-datasource-docstyle-review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Michal Maléř <mmaler@redhat.com>
---
 docs/src/main/asciidoc/datasource.adoc |  9 ++++-----
 docs/src/main/asciidoc/logging.adoc    | 24 ++++++++++++++----------
 2 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/docs/src/main/asciidoc/datasource.adoc b/docs/src/main/asciidoc/datasource.adoc
index 974157657ffa3..83f02c99e9df9 100644
--- a/docs/src/main/asciidoc/datasource.adoc
+++ b/docs/src/main/asciidoc/datasource.adoc
@@ -259,12 +259,11 @@ For more information about configuring JDBC, see <<jdbc-url,JDBC URL format refe
 [[other-databases]]
 ===== Custom databases and drivers
 
-If you need to connect to a database for which Quarkus does not provide an extension with the JDBC driver,
-you can use a custom driver instead. For example, if you are using the OpenTelemetry JDBC driver in your project.
+If Quarkus does not provide a JDBC extension for your database, or you need to use a different JDBC driver, such as one for OpenTelemetry, you can configure the JDBC driver explicitly.
 
-Without an extension, the driver will work correctly in any Quarkus app running in JVM mode.
-However, the driver is unlikely to work when compiling your application to a native executable.
-If you plan to make a native executable, use the existing JDBC Quarkus extensions, or contribute one for your driver.
+Without an extension, JDBC drivers are expected to work correctly in JVM mode.
+However, they are unlikely to function when compiling your application into a native executable.
+To build a native executable, use an existing Quarkus JDBC extension or contribute a new extension for your driver.
 
 .An example for defining access to a database with no built-in support in JVM mode:
 
diff --git a/docs/src/main/asciidoc/logging.adoc b/docs/src/main/asciidoc/logging.adoc
index f3d56fa04a7b3..1a50a862618b0 100644
--- a/docs/src/main/asciidoc/logging.adoc
+++ b/docs/src/main/asciidoc/logging.adoc
@@ -115,21 +115,25 @@ The fully qualified name of the class that calls the `Log` methods is used as a
 In this example, the logger name would be `com.example.MyService`.
 <3> Finally, all calls to `Log` methods are rewritten to regular JBoss Logging calls on the logger field during the application build.
 
-WARNING: Only use the `Log` API in application classes, not in external dependencies.
-`Log` method calls that are not processed by Quarkus at build time will throw an exception.
-
 [[log-api-extension-warning]]
-==== Important Note on Using `io.quarkus.logging.Log` in Extensions
+[WARNING]
+====
+Use the `Log` API only in application classes, not in external dependencies.
+`Log` method calls not processed by Quarkus at build time will result in an exception.
 
-While the `Log` API simplifies logging in application classes, it should not be used in extension modules or external dependencies. The following considerations apply:
+.Using `io.quarkus.logging.Log` in extensions:
 
-* `io.quarkus.logging.Log` depends on Quarkus bytecode transformations that occur at build time.
-* In extension modules, the use of `Log` may work if the module has a Jandex index. However, this behavior is not officially supported and might lead to unreliable logging.
+While the `Log` API simplifies logging in application classes, it is not recommended for use in extension modules or external dependencies.
 
-For extension development:
+The following considerations apply:
 
-* Use standard loggers like `org.jboss.logging.Logger.getLogger(String)` instead of `io.quarkus.logging.Log`.
-* This avoids potential performance issues caused by the stack walk fallback when Quarkus build-time processing is unavailable.
+* `io.quarkus.logging.Log` depends on Quarkus bytecode transformations that occur at build time.
+
+* In extension modules, `Log` works only if the module includes a Jandex index.
+However, this behavior is unsupported and can lead to unreliable logging.
++
+For extension development, use `org.jboss.logging.Logger.getLogger(String)` instead of `io.quarkus.logging.Log`.
+====
 
 
 [[injection-of-a-configured-logger]]