Merge pull request #44799 from MichalMaler/docstyle-review

Logging and Datasource docstyle review

Author: yrodiere

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:
 

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]]