diff --git a/.agents/java-kotlin-conversion.md b/.agents/java-kotlin-conversion.md deleted file mode 100644 index 95cf92954..000000000 --- a/.agents/java-kotlin-conversion.md +++ /dev/null @@ -1,43 +0,0 @@ -# 🪄 Converting Java code to Kotlin - -* Java code API comments are Javadoc format. -* Kotlin code API comments are in KDoc format. - -## Javadoc to KDoc conversion - -* The wording of original Javadoc comments must be preserved. - -## Treating nullability - -* Use nullable Kotlin type only if the type in Java is annotated as `@Nullable`. - -## Efficient Conversion Workflow - -* First, analyze the entire Java file structure before beginning conversion to understand dependencies and class relationships. -* Convert Java code to Kotlin systematically: imports first, followed by class definitions, methods, and finally expressions. -* Preserve all existing functionality and behavior during conversion. -* Maintain original code structure and organization to ensure readability. - -## Common Java to Kotlin Patterns - -* Convert Java getters/setters to Kotlin properties with appropriate visibility modifiers. -* Transform Java static methods to companion object functions or top-level functions as appropriate. -* Replace Java anonymous classes with Kotlin lambda expressions when possible. -* Convert Java interfaces with default methods to Kotlin interfaces with implementations. -* Transform Java builders to Kotlin DSL patterns when appropriate. - -## Error Prevention - -* Pay special attention to Java's checked exceptions versus Kotlin's unchecked exceptions. -* Be cautious with Java wildcards (`? extends`, `? super`) conversion to Kotlin's `out` and `in` type parameters. -* Ensure proper handling of Java static initialization blocks in Kotlin companion objects. -* Verify that Java overloaded methods convert correctly with appropriate default parameter values in Kotlin. -* Remember that Kotlin has smart casts which can eliminate explicit type casting needed in Java. - -## Documentation Conversion - -* Convert `@param` to `@param` with the same description. -* Convert `@return` to `@return` with the same description. -* Convert `@throws` to `@throws` with the same description. -* Convert `{@link}` to `[name][fully.qualified.Name]` format. -* Convert `{@code}` to inline code with backticks (`). diff --git a/.agents/project-overview.md b/.agents/project-overview.md deleted file mode 100644 index dfac73f03..000000000 --- a/.agents/project-overview.md +++ /dev/null @@ -1,7 +0,0 @@ -# 🛠️ Project overview - -- **Languages**: Kotlin (primary), Java (secondary). -- **Build tool**: Gradle with Kotlin DSL. -- **Static analysis**: detekt, ErrorProne, Checkstyle, PMD. -- **Testing**: JUnit 5, Kotest Assertions, Codecov. -- **Tools used**: Gradle plugins, IntelliJ IDEA Platform, KSP, KotlinPoet, Dokka. diff --git a/.agents/tasks/otel-backend-report.md b/.agents/tasks/otel-backend-report.md index 7cc72ef13..4b9c1ab79 100644 --- a/.agents/tasks/otel-backend-report.md +++ b/.agents/tasks/otel-backend-report.md @@ -585,7 +585,7 @@ Implications: ## 11. Phased plan - **Phase 0 — JVM-via-compat spike.** Backend on JVM only, `OpenTelemetry` provided as - `javaOtel.toOtelKotlinApi()`. Validate the full path (Spine log → OTLP → backend of choice)against + `javaOtel.toOtelKotlinApi()`. Validate the full path (Spine log → OTLP → backend of choice) against the mature Java SDK. Lowest risk; proves the mapping before touching KMP. - **Phase 1 — KMP commonMain backend (`:api`).** Move the mapping into `commonMain`, JVM target registered via `ServiceLoader`, SDK injected by the app. Severity, body, metadata→attributes, diff --git a/.claude/settings.json b/.claude/settings.json index 357650cf7..3c7da68c3 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,5 +1,6 @@ { "$schema": "https://json.schemastore.org/claude-code-settings.json", + "plansDirectory": ".claude/plans", "permissions": { "allow": [ "Edit(version.gradle.kts)", @@ -32,8 +33,11 @@ "Bash(mkdir:*)", "Bash(touch:*)", "Bash(python3 .agents/skills/update-copyright/scripts/update_copyright.py:*)", + "Bash(.agents/skills/version-bumped/scripts/version-bumped.sh)", "Bash(./config/pull)", - "Bash(./config/migrate)" + "Bash(./config/migrate)", + "Skill(pre-pr)", + "Skill(pre-pr:*)" ], "deny": [ "Bash(git reset --hard:*)", diff --git a/.gitignore b/.gitignore index dfb4774d4..ed1b0baa7 100644 --- a/.gitignore +++ b/.gitignore @@ -54,8 +54,12 @@ .idea/modules .idea/shelf +# `.idea/misc.xml` is intentionally NOT re-included below. It is project-local — +# it holds the per-project JDK name and IDEA's own churn (entry-point list +# indices, external-storage toggles) — so `.idea/*.xml` above keeps it ignored. +# `./config/pull` (via `migrate`) untracks any copy an earlier pull committed. + # Do not ignore the following IDEA settings -!.idea/misc.xml !.idea/codeStyleSettings.xml !.idea/codeStyles/ !.idea/copyright/ @@ -173,6 +177,12 @@ __pycache__/ # Claude working files /.claude/worktrees/ +# Ephemeral plan-mode scratch (durable task docs live in `.agents/tasks/`). +/.claude/plans/ + +# Personal, per-developer Claude Code settings overrides (never committed; +# the distributed `.claude/settings.json` is the shared, committed layer). +/.claude/settings.local.json # Auto-downloaded Lychee binary used by the `check-links` skill. /.agents/skills/check-links/.cache/ @@ -190,7 +200,6 @@ docs/_preview/resources/ # <<< shared config <<< # >>> repo-local entries (preserved across ./config/pull) >>> -!.idea/misc.xml !.idea/codeStyleSettings.xml !.idea/codeStyles/ !.idea/copyright/ diff --git a/.idea/live-templates/README.md b/.idea/live-templates/README.md index 950066731..267008ad1 100644 --- a/.idea/live-templates/README.md +++ b/.idea/live-templates/README.md @@ -22,6 +22,6 @@ In order to add these templates, perform the following steps: 1. Open the corresponding template: `Preferences -> Editor -> Live Templates -> User.todo`. 2. Click on `Edit variables`. -3. Set `USER` variable to your domain email address without `@teamdev.com` ending. For example, +3. Set `USER` variable to your domain email address without `@teamdev.com` ending. For example, for `jack.sparrow@teamdev.com` use the following expression `"jack.sparrow"`. 4. Verify that the template generates expected comments: `// TODO:2022-11-03:jack.sparrow: <...>`. diff --git a/.idea/misc.xml b/.idea/misc.xml deleted file mode 100644 index 264f82301..000000000 --- a/.idea/misc.xml +++ /dev/null @@ -1,44 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2185ef6d5..0bccb5340 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,13 +20,13 @@ Code contributions should: Contributor License Agreement ----------------------------- -Contributions to the code of Spine Event Engine framework and its libraries must be accompanied by -Contributor License Agreement (CLA). +Contributions to the code of the Spine Event Engine framework and its libraries must be accompanied by +a Contributor License Agreement (CLA). * If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an individual CLA. - * If you work for a company which wants you to contribute your work, + * If you work for a company that wants you to contribute your work, then an authorized person from your company will need to sign a corporate CLA. Please [contact us][legal-email] for arranging the paper formalities. diff --git a/README.md b/README.md index a8927c107..04dfb6efd 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Spine Logging is a versatile library designed for Kotlin and Java projects, with a potential for multi-platform use. -As of now, only JVM target is supported, with a JavaScript implementation +As of now, only the JVM target is supported, with a JavaScript implementation being our priority for future development. API and implementation are largely inspired by [Google Flogger][flogger], @@ -34,12 +34,12 @@ dependencies { ``` In this case, the default logging backend will be used. It outputs log records -to the console using `java.util.logging` (JUL) framework. +to the console using the `java.util.logging` (JUL) framework. All logging operations are done with an instance of `io.spine.logging.Logger`. To get a logger, one can use the following: -1. Make a logging class implement `WithLogging` interface. +1. Make a logging class implement the `WithLogging` interface. 2. Get a logger from `LoggingFactory`. ### Logging via `WithLogging` interface @@ -100,10 +100,10 @@ The following backends are available: See [the OpenTelemetry backend guide](docs/otel-backend.md). The default backend is supplied along the logging library itself. To use it, -one just needs to not supply any other backend. Then JUL backend will be +one just needs to not supply any other backend. Then the JUL backend will be used automatically. -For other backends, put a chosen one to `runtimeOnly` configuration, +For other backends, put a chosen one to the `runtimeOnly` configuration, and the logging library will discover it in the runtime. An example usage of Log4j2 backend: @@ -142,7 +142,7 @@ class Example : WithLogging { // INFO: Call #7 [CONTEXT ratelimit_count=7 skipped=6 ] ``` -Also, a user can attach its own metadata. For instance, you can attach +Also, a user can attach their own metadata. For instance, you can attach a user ID to all log records for the current request, or force logging level if the requested URL contains a debug parameter. diff --git a/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/AbstractJulBackend.kt b/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/AbstractJulBackend.kt index 23bb3e786..2338a832f 100644 --- a/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/AbstractJulBackend.kt +++ b/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/AbstractJulBackend.kt @@ -70,7 +70,7 @@ public abstract class AbstractJulBackend : LoggerBackend { /** * Logs the given record using this backend. If [wasForced] is set, the backend will make a - * best effort attempt to bypass any log level restrictions in the underlying Java [Logger], + * best-effort attempt to bypass any log level restrictions in the underlying Java [Logger], * but there are circumstances in which this can fail. */ public fun log(record: LogRecord, wasForced: Boolean) { @@ -108,7 +108,7 @@ public abstract class AbstractJulBackend : LoggerBackend { * Forces logging via a child logger, bypassing the parent handlers. * * WARNING: This code will fail for anonymous loggers `(getName() == null)` and - * when/if the Logging library supports anonymous loggers it must ensure that + * when/if the Logging library supports anonymous loggers, it must ensure that * this code path is avoided by not allowing subclasses of `Logger` to be used. */ internal fun forceLoggingViaChildLogger(record: LogRecord) { @@ -120,7 +120,7 @@ public abstract class AbstractJulBackend : LoggerBackend { Logger.getLogger("").log( SEVERE.toJavaLogging(), """ - Forcing log statements with has been partially disabled. + Forcing log statements has been partially disabled. The Logging library cannot modify logger log levels, which is necessary to force log statements. This is likely due to an installed `SecurityManager`. Forced log statements will still be published directly to log handlers, but diff --git a/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/AbstractJulRecord.kt b/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/AbstractJulRecord.kt index 42784f428..ca2526343 100644 --- a/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/AbstractJulRecord.kt +++ b/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/AbstractJulRecord.kt @@ -56,13 +56,13 @@ import java.util.logging.LogRecord * ## Non-null message, non-empty parameters * * This state is only reached if a user calls both [setMessage] and [setParameters]. - * In this state the message is treated as is it were a brace-format log + * In this state the message is treated as if it were a brace-format log * message, and no formatting is attempted. * Any relationship between this value, and the log message * implied by the contained [LogData] and [Metadata] is lost. * * For many reasons it is never a good idea for users to modify unknown [LogRecord] - * instances, but this does happen occasionally, so this class supports that in a best effort way, + * instances, but this does happen occasionally, so this class supports that in a best-effort way, * but users are always recommended to copy [LogRecord] instances if they need * to modify them. * @@ -175,7 +175,7 @@ public abstract class AbstractJulRecord : LogRecord { public fun getLogData(): LogData = data /** - * Returns the immutable [MetadataProcessor] which provides a unified view of scope and log site metadata. + * Returns the immutable [MetadataProcessor] that provides a unified view of scope and log site metadata. */ public fun getMetadataProcessor(): MetadataProcessor = metadata diff --git a/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/JulBackend.kt b/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/JulBackend.kt index 4c63185cd..f37fe4df8 100644 --- a/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/JulBackend.kt +++ b/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/JulBackend.kt @@ -78,7 +78,7 @@ internal class JulBackend(loggingClass: String): AbstractJulBackend(loggingClass * are involved. * * When a [parent logger][Logger.getParent] has a higher level - * (which is [Level.INFO][java.util.logging.Level.INFO] by default) its handler has + * (which is [Level.INFO][java.util.logging.Level.INFO] by default), its handler has * this level too. Because of this the method [Handler.isLoggable] filters * out the record. * @@ -91,7 +91,7 @@ internal class JulBackend(loggingClass: String): AbstractJulBackend(loggingClass * @see publishForced */ private fun doLog(record: LogRecord, wasForced: Boolean) { - // If not forced, do work as usually. + // If not forced, do work as usual. if (!wasForced || isLoggable(record.level.toLevel())) { logger.log(record) return @@ -107,7 +107,7 @@ internal class JulBackend(loggingClass: String): AbstractJulBackend(loggingClass /** * Publishes the given [record] using the handlers of the [logger]. * - * If the logger is configured to [use parent handlers][Logger.getUseParentHandlers] + * If the logger is configured to [use parent handlers][Logger.getUseParentHandlers], * propagates publishing to the [parent logger][Logger.getParent] too. */ private fun publishForced(logger: Logger, record: LogRecord) { diff --git a/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/JulBackendFactory.kt b/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/JulBackendFactory.kt index 3e8ca7fb0..d7d2efa0c 100644 --- a/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/JulBackendFactory.kt +++ b/backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/JulBackendFactory.kt @@ -30,7 +30,7 @@ import io.spine.logging.backend.BackendFactory import io.spine.logging.backend.LoggerBackend /** - * A [BackendFactory] producing [LoggerBackend] which supports publishing + * A [BackendFactory] producing [LoggerBackend] that supports publishing * of logging records according to configured [LogLevelMap][io.spine.logging.context.LogLevelMap]. */ public class JulBackendFactory: BackendFactory() { diff --git a/backends/jul-backend/src/test/kotlin/io/spine/logging/backend/jul/given/StubLogData.kt b/backends/jul-backend/src/test/kotlin/io/spine/logging/backend/jul/given/StubLogData.kt index fc35382ba..620179389 100644 --- a/backends/jul-backend/src/test/kotlin/io/spine/logging/backend/jul/given/StubLogData.kt +++ b/backends/jul-backend/src/test/kotlin/io/spine/logging/backend/jul/given/StubLogData.kt @@ -36,7 +36,7 @@ import io.spine.logging.toLevel import java.util.logging.Level as JLevel /** - * A mutable [LogData] fot testing backends and other log handling code. + * A mutable [LogData] for testing backends and other log handling code. * * @see Original Java code * for historical context. diff --git a/backends/log4j2-backend/src/main/kotlin/io/spine/logging/backend/log4j2/ValueQueue.kt b/backends/log4j2-backend/src/main/kotlin/io/spine/logging/backend/log4j2/ValueQueue.kt index 9494cfef2..0979b0a7b 100644 --- a/backends/log4j2-backend/src/main/kotlin/io/spine/logging/backend/log4j2/ValueQueue.kt +++ b/backends/log4j2-backend/src/main/kotlin/io/spine/logging/backend/log4j2/ValueQueue.kt @@ -103,7 +103,7 @@ internal class ValueQueue private constructor() : Iterable { return if (existingValue == null) { value } else { - // This should only rarely happen, so a few small allocations seems acceptable. + // This should only rarely happen, so a few small allocations seem acceptable. val existingQueue = existingValue as? ValueQueue ?: newQueue(existingValue) existingQueue.put(value) existingQueue @@ -136,7 +136,7 @@ internal class ValueQueue private constructor() : Iterable { * Emits a metadata label/value pair to a given KeyValueHandler, * handling Tags values specially. * - * Tags are key-value mappings which cannot be modified or replaced. + * Tags are key-value mappings that cannot be modified or replaced. * If you add the tag mapping "foo" -> true and later add "foo" -> false, * you get "foo" mapped to both true and false. * This is deliberate since the key space for tags is global and the risk diff --git a/backends/log4j2-backend/src/test/kotlin/io/spine/logging/backend/log4j2/given/StubLogData.kt b/backends/log4j2-backend/src/test/kotlin/io/spine/logging/backend/log4j2/given/StubLogData.kt index 6fc0c0c9a..d34f98b94 100644 --- a/backends/log4j2-backend/src/test/kotlin/io/spine/logging/backend/log4j2/given/StubLogData.kt +++ b/backends/log4j2-backend/src/test/kotlin/io/spine/logging/backend/log4j2/given/StubLogData.kt @@ -34,7 +34,7 @@ import io.spine.logging.MetadataKey import io.spine.logging.backend.LogData /** - * A mutable [LogData] fot testing backends and other log handling code. + * A mutable [LogData] for testing backends and other log handling code. * * @see Original Java code * for historical context. diff --git a/backends/probe-backend/README.md b/backends/probe-backend/README.md index e2e9b38aa..b63091fa9 100644 --- a/backends/probe-backend/README.md +++ b/backends/probe-backend/README.md @@ -3,7 +3,7 @@ **Note:** This is a specific backend implementation that is designed to be used in tests. The probe backend provides a backend factory that can switch -the current backend implementation on runtime. +the current backend implementation at runtime. The logging facade does not provide such a capability. Take a look at `DynamicBackendFactory` for details. diff --git a/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/CaptureLogData.kt b/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/CaptureLogData.kt index 96a718ef9..b40184b8a 100644 --- a/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/CaptureLogData.kt +++ b/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/CaptureLogData.kt @@ -30,7 +30,7 @@ import io.spine.logging.backend.LogData /** * Runs the given [action], capturing all log data that are passed - * to backend by the API. + * to the backend by the API. * * To make this work, please create a logger instance inside of [action]. * This method captures log data for loggers that are both created and used @@ -77,7 +77,7 @@ public inline fun captureLogData(action: () -> Unit): List { } // Several loggers could have been created within the `action`. - // Each logger spawns its own instance of backend. + // Each logger spawns its own instance of a backend. val loggedFromAllBackends = memoizingFactory.createdBackends.flatMap { it.logged } return loggedFromAllBackends } diff --git a/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/DynamicBackendFactory.kt b/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/DynamicBackendFactory.kt index 145083860..177154389 100644 --- a/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/DynamicBackendFactory.kt +++ b/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/DynamicBackendFactory.kt @@ -32,10 +32,10 @@ import io.spine.logging.backend.jul.JulBackendFactory /** * A factory that delegates backends creation to another factory - * and allows changing of the underlying factory in runtime. + * and allows changing of the underlying factory at runtime. * * In general, the logging facade doesn't provide a mechanism for changing - * the underlying backend factory in runtime. It shouldn't make any sense + * the underlying backend factory at runtime. It shouldn't make any sense * in real code. But for tests, it can be handy. * * Different tests may need different backend stubs to perform their assertions. diff --git a/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/DynamicBackendFactoryService.kt b/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/DynamicBackendFactoryService.kt index 0dae8997c..b15f2b7b7 100644 --- a/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/DynamicBackendFactoryService.kt +++ b/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/DynamicBackendFactoryService.kt @@ -35,7 +35,7 @@ import io.spine.logging.backend.BackendFactory * [ServiceLoader][java.util.ServiceLoader]. * * Each service should have a public no-args constructor to be used - * by the loader. Which is not a case for object declarations, as they + * by the loader. Which is not the case for object declarations, as they * do not have any constructors at all. * * Until [KT-25892](https://youtrack.jetbrains.com/issue/KT-25892/Allow-objects-to-be-loaded-via-ServiceLoader-or-similar-API) @@ -53,7 +53,7 @@ import io.spine.logging.backend.BackendFactory public class DynamicBackendFactoryService : BackendFactory() { /** - * Delegates actual backend creation to [DynamicBackendFactory] object. + * Delegates actual backend creation to the [DynamicBackendFactory] object. */ override fun create(loggingClass: String): LoggerBackend = DynamicBackendFactory.create(loggingClass) diff --git a/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/TypedBackendFactory.kt b/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/TypedBackendFactory.kt index 80809d728..1e0ebf7f5 100644 --- a/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/TypedBackendFactory.kt +++ b/backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/TypedBackendFactory.kt @@ -35,7 +35,7 @@ import io.spine.logging.backend.LoggerBackend * * Knowing a type of the returned backend is useful when it is used in a pair with * [DynamicBackendFactory] to perform test assertions. With a captured type, - * we do not lose the API of stub backends. For example, allowing to retrieve + * we do not lose the API of stub backends. For example, allowing us to retrieve * the remembered log data from `FakeLoggerBackend`. * * The type is public because it is used in a public inline method. diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts index a61d839f8..5b377272e 100644 --- a/buildSrc/build.gradle.kts +++ b/buildSrc/build.gradle.kts @@ -132,7 +132,7 @@ val kotestJvmPluginVersion = "0.4.10" /** * @see [io.spine.dependency.test.Kover] */ -val koverVersion = "0.9.8" +val koverVersion = "0.9.9" /** * The version of the Shadow Plugin. @@ -222,7 +222,7 @@ dependOnBuildSrcJar() /** * Adds a dependency on a `buildSrc.jar`, iff: * 1) the `src` folder is missing, and - * 2) `buildSrc.jar` is present in `buildSrc/` folder instead. + * 2) `buildSrc.jar` is present in the `buildSrc/` folder instead. * * This approach is used in the scope of integration testing. */ @@ -241,7 +241,7 @@ fun Project.dependOnBuildSrcJar() { * Includes the `implementation` dependency on `artifactregistry-auth-common`, * with the version defined in [googleAuthToolVersion]. * - * `artifactregistry-auth-common` has transitive dependency on Gson and Apache `commons-codec`. + * `artifactregistry-auth-common` has a transitive dependency on Gson and Apache `commons-codec`. * Gson from version `2.8.6` until `2.8.9` is vulnerable to Deserialization of Untrusted Data * (https://devhub.checkmarx.com/cve-details/CVE-2022-25647/). * diff --git a/buildSrc/quality/checkstyle-suppressions.xml b/buildSrc/quality/checkstyle-suppressions.xml index a761fca35..9d169de7f 100644 --- a/buildSrc/quality/checkstyle-suppressions.xml +++ b/buildSrc/quality/checkstyle-suppressions.xml @@ -1,7 +1,7 @@ io.spine logging -2.0.0-SNAPSHOT.422 +2.0.0-SNAPSHOT.423 2015 @@ -26,7 +26,7 @@ all modules and does not describe the project structure per-subproject. com.fasterxml.jackson jackson-bom - 2.22.0 + 2.22.1 compile @@ -104,7 +104,7 @@ all modules and does not describe the project structure per-subproject. io.spine spine-annotations - 2.0.0-SNAPSHOT.421 + 2.0.0-SNAPSHOT.425 compile @@ -164,7 +164,7 @@ all modules and does not describe the project structure per-subproject. com.google.errorprone error_prone_type_annotations - 2.36.0 + 2.42.0 provided @@ -229,7 +229,7 @@ all modules and does not describe the project structure per-subproject. com.google.errorprone error_prone_core - 2.36.0 + 2.42.0 com.puppycrawl.tools diff --git a/logging-testlib/src/jvmMain/kotlin/io/spine/logging/testing/Log4j2Recorder.kt b/logging-testlib/src/jvmMain/kotlin/io/spine/logging/testing/Log4j2Recorder.kt index 514cae5bc..54e648594 100644 --- a/logging-testlib/src/jvmMain/kotlin/io/spine/logging/testing/Log4j2Recorder.kt +++ b/logging-testlib/src/jvmMain/kotlin/io/spine/logging/testing/Log4j2Recorder.kt @@ -116,7 +116,7 @@ private class Log4jLogData(val event: LogEvent): LogData { * A reasonably high value to be used for the range calculations instead of * [Int.MAX_VALUE] or [Int.MIN_VALUE] used as high/low bounds in logging frameworks. * - * This is a safe assumption that log levels are defined withing this range, + * This is a safe assumption that log levels are defined within this range, * especially for tests. */ private const val BOUND = 1200 // java.util.logging.Level.intValue() + 1000 @@ -142,7 +142,7 @@ private val forceRegistration = Log4jLevelConverter public fun Level.toLog4j2(): L4jLevel = convert(this) /** - * Converts this Log4j2 level to Spine Logging level. + * Converts this Log4j2 level to a Spine Logging level. * * This function is used in tests and thus is `internal`. */ diff --git a/logging-testlib/src/jvmMain/kotlin/io/spine/logging/testing/TapConsole.kt b/logging-testlib/src/jvmMain/kotlin/io/spine/logging/testing/TapConsole.kt index 180da1fd4..7d721e017 100644 --- a/logging-testlib/src/jvmMain/kotlin/io/spine/logging/testing/TapConsole.kt +++ b/logging-testlib/src/jvmMain/kotlin/io/spine/logging/testing/TapConsole.kt @@ -65,7 +65,7 @@ public fun tapConsole(action: () -> Unit): String { * * Not restoring the streams does not affect our current testing requirements. * However, for more extensive testing scenarios that also involve console output - * interception and complex interactions with Java Logging framework's quirks, + * interception and complex interactions with the Java Logging framework's quirks, * this could potentially create issues. */ public object ConsoleTap { @@ -127,7 +127,7 @@ private class RedirectingPrintStream(initial: PrintStream): PrintStream(initial) } /** - * A [PrintStream] which stores the output in a byte array and allows to retrieve it. + * A [PrintStream] that stores the output in a byte array and allows retrieving it. * * @param size The initial size of the underlying byte array, which grows as needed. */ diff --git a/logging/src/commonMain/kotlin/io/spine/logging/AbstractLogger.kt b/logging/src/commonMain/kotlin/io/spine/logging/AbstractLogger.kt index 58e9e7b7a..014a18d7c 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/AbstractLogger.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/AbstractLogger.kt @@ -102,7 +102,7 @@ public abstract class AbstractLogger> protected constructo * * If a logger implementation determines that logging is definitely disabled at this point, * then this method is expected to return a "no-op" implementation of that logging API. - * This, in turn, will result in all further calls made for the log statement to + * This, in turn, will result in all further calls made for the log statement * being silently ignored. * * A simple implementation of this method in a concrete subclass might look like: @@ -206,7 +206,7 @@ public abstract class AbstractLogger> protected constructo public fun getBackend(): LoggerBackend = backend /** - * Invokes the logging backend to write a log statement, ensuring that all exceptions which + * Invokes the logging backend to write a log statement, ensuring that all exceptions that * could be caused during logging, including any subsequent error handling, are handled. * * This method can only fail due to instances of [LoggingException] or [Error] being thrown. @@ -243,7 +243,7 @@ public abstract class AbstractLogger> protected constructo } /** - * Only allow `LoggingException` and `Errors` to escape this method. + * Only allows `LoggingException` and `Errors` to escape this method. */ @Suppress("UseOfSystemOutOrSystemErr", "TooGenericExceptionCaught", "PrintStackTrace") private fun handleErrorRobustly(logError: RuntimeException, data: LogData) { diff --git a/logging/src/commonMain/kotlin/io/spine/logging/InjectedLogSite.kt b/logging/src/commonMain/kotlin/io/spine/logging/InjectedLogSite.kt index 49c25d76e..d9f9d67a2 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/InjectedLogSite.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/InjectedLogSite.kt @@ -34,7 +34,7 @@ import io.spine.annotation.Internal * * Used for compile-time log site injection, and by the agent. * - * @param internalClassName An internal, slash-separated, fully-qualified class name + * @param internalClassName An internal, slash-separated, fully qualified class name * (e.g., `"com/example/Foo$Bar"`). * @param methodName A bare method name without signature information. * @param encodedLineNumber A line number and per-line log statement index encoded as a single @@ -72,7 +72,7 @@ public fun injectedLogSite( * The class name is stored in the internal JVM format (slash-separated) and converted to * the standard dot-separated format when needed for proper identification. * - * @property internalClassName An internal, slash-separated, fully-qualified class name + * @property internalClassName An internal, slash-separated, fully qualified class name * (e.g., `"com/example/Foo$Bar"`). * @property method A bare method name without signature information. * @property encodedLineNumber A line number and per-line log statement index encoded as a single @@ -97,7 +97,7 @@ internal class InjectedLogSite( private var hashcode = 0 /** - * Obtains dot-separated class name. + * Obtains the dot-separated class name. * * ## Implementation note * diff --git a/logging/src/commonMain/kotlin/io/spine/logging/KeyPart.kt b/logging/src/commonMain/kotlin/io/spine/logging/KeyPart.kt index 1862c9644..2fbf4df90 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/KeyPart.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/KeyPart.kt @@ -27,7 +27,7 @@ package io.spine.logging /** - * A part of a log site key which has singleton semantics per logging scope. + * A part of a log site key that has singleton semantics per logging scope. * * This class is responsible for managing the lifecycle and cleanup of log site keys. * It ensures that key references are properly maintained and cleaned up when no longer needed. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/KeyValueHandler.kt b/logging/src/commonMain/kotlin/io/spine/logging/KeyValueHandler.kt index 7ba2e2582..472fd4456 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/KeyValueHandler.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/KeyValueHandler.kt @@ -36,7 +36,7 @@ package io.spine.logging public fun interface KeyValueHandler { /** - * Handles a single key/value a pair of contextual metadata for a log statement. + * Handles a single key/value pair of contextual metadata for a log statement. */ public fun handle(key: String, value: Any?) } diff --git a/logging/src/commonMain/kotlin/io/spine/logging/Level.kt b/logging/src/commonMain/kotlin/io/spine/logging/Level.kt index ffaa1f463..412c84f05 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/Level.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/Level.kt @@ -29,7 +29,7 @@ package io.spine.logging /** * Level of logging in an application. * - * Implemented as data class rather than enum to allow for custom logging level values. + * Implemented as a data class rather than an enum to allow for custom logging level values. * Please see the companion object for the standard levels. * * ## Adding custom levels @@ -47,7 +47,7 @@ package io.spine.logging * ``` * public fun > Logger.atNotice(): API = at(MyLoggingLevels.NOTICE) * ``` - * If the new logging level needs to be converted to a level of underlying logging backend + * If the new logging level needs to be converted to a level of the underlying logging backend, * a [LevelConverter] must be [registered][LevelConverter.register] prior to * performing the [conversion][LevelConverter.convert]. * diff --git a/logging/src/commonMain/kotlin/io/spine/logging/LogContext.kt b/logging/src/commonMain/kotlin/io/spine/logging/LogContext.kt index 34ad51796..c23556784 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/LogContext.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/LogContext.kt @@ -117,7 +117,7 @@ protected constructor( protected abstract fun api(): API /** - * Returns the logger which created this context. + * Returns the logger that created this context. * * This is implemented as an abstract method to save a field in every context. */ @@ -186,7 +186,7 @@ protected constructor( } /** - * A callback which can be overridden to implement post processing of logging contexts prior to + * A callback that can be overridden to implement post processing of logging contexts prior to * passing them to the backend. * * ## Basic Responsibilities @@ -248,7 +248,7 @@ protected constructor( * However, in most cases `postProcess()` is only expected to return `false` due to * rate limiting. * - * If rate limiters are used there are still situations in which `postProcess()` can + * If rate limiters are used, there are still situations in which `postProcess()` can * return `true`, but logging will not occur. This is due to race conditions around the * resetting of rate limiter state. A `postProcess()` method can "early exit" as soon as * `shouldLog` is false, but should assume logging will occur while it remains `true`. @@ -267,7 +267,7 @@ protected constructor( * The default implementation of this method enforces the rate limits as set * by [every] and [atMostEvery]. * - * @param logSiteKey The key used to lookup persistent, per log statement, state. + * @param logSiteKey The key used to look up persistent, per log statement, state. * @return true if logging should be attempted (usually based on rate limiter state). */ protected open fun postProcess(logSiteKey: LogSiteKey?): Boolean { @@ -321,7 +321,7 @@ protected constructor( stackSize, stackForCallerOf(LogContext::class, stackSize.maxDepth, 1) ) - // The "cause" is a unique metadata key, we must replace any existing value. + // The "cause" is a unique metadata key; we must replace any existing value. addMetadata(Key.LOG_CAUSE, context) } } @@ -331,7 +331,7 @@ protected constructor( /** * Callback to allow custom log contexts to apply additional rate limiting behaviour. - * This should be called from within an overriden `postProcess()` method. + * This should be called from within an overridden `postProcess()` method. * Typically, this is invoked after calling `super.postProcess(logSiteKey)`, such as: * * ```kotlin @@ -464,7 +464,7 @@ protected constructor( public final override fun isEnabled(): Boolean { // We can't guarantee that all logger implementations will return instances of this class - // _only_ when logging is enabled, so if would be potentially unsafe to just return + // _only_ when logging is enabled, so it would be potentially unsafe to just return // `true` here. // It's not worth caching this result in the instance because calls to this // method should be rare and they are only going to be made once per instance anyway. @@ -542,7 +542,7 @@ protected constructor( } require(n >= 0) { "Rate limit period cannot be negative: $n." } - // Rate limiting with a zero length period is a no-op, but if the time unit is + // Rate limiting with a zero-length period is a no-op, but if the time unit is // nanoseconds then the value is rounded up inside the rate limit object. if (n > 0) { addMetadata( @@ -658,7 +658,7 @@ protected constructor( * statement for other callers. * * The decision of whether to force a log statement is expected to be made based upon - * debug values provided by the logger which come from a scope greater than the log + * debug values provided by the logger that come from a scope greater than the log * statement itself. Thus it makes no sense to provide a public method to set this value * programmatically for a log statement. */ @@ -671,7 +671,7 @@ protected constructor( * * If tags are injected, they are added after post-processing if the log site is enabled. * Thus they are not available to the `postProcess()` method itself. The rationale is - * that a log statement's behavior should only be affected by code at the log site (other + * that a log statement's behaviour should only be affected by code at the log site (other * than "forcing" log statements, which is slightly a special case). * * Tags can be added at the log site, although this should rarely be necessary and using diff --git a/logging/src/commonMain/kotlin/io/spine/logging/LogPerBucketingStrategy.kt b/logging/src/commonMain/kotlin/io/spine/logging/LogPerBucketingStrategy.kt index f7f97295f..0a40acbb1 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/LogPerBucketingStrategy.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/LogPerBucketingStrategy.kt @@ -45,18 +45,18 @@ import io.spine.annotation.TestOnly * This multiplies the amount of memory that is retained indefinitely by * any use of [LoggingApi.per]. * - * One way to handle arbitrary key types would be to create a strategy which + * One way to handle arbitrary key types would be to create a strategy that * "interns" instances in some way, to produce singleton identifiers. * * Unfortunately, interning can itself be a cause of unbounded memory leaks, * so a bucketing strategy wishing to perform interning should probably - * support a user defined maximum capacity to limit the overall risk. + * support a user-defined maximum capacity to limit the overall risk. * * If too many instances are seen, the strategy should begin to return `null` * (and log an appropriate warning). * * The additional complexity created by this approach really tells us that - * types which require interning in order to be used as aggregation keys + * types that require interning in order to be used as aggregation keys * should be considered unsuitable, and callers should seek alternatives. * * @param name The name of this strategy, used for debugging purposes. @@ -127,7 +127,7 @@ public abstract class LogPerBucketingStrategy protected constructor( /** * This is a "safe" strategy as far as memory use is concerned, because a class object - * returns the same string instance every time its called, and class objects + * returns the same string instance every time it's called, and class objects * are effectively singletons. */ private val BY_CLASS_NAME = object : LogPerBucketingStrategy("ByClassName") { @@ -155,7 +155,7 @@ public abstract class LogPerBucketingStrategy protected constructor( public fun knownBounded(): LogPerBucketingStrategy = KNOWN_BOUNDED /** - * A strategy which uses the [Class] of the given key for log aggregation. + * A strategy that uses the [Class] of the given key for log aggregation. * * This is useful when you need to aggregate over specific exceptions or similar * type-distinguished instances. @@ -170,7 +170,7 @@ public abstract class LogPerBucketingStrategy protected constructor( public fun byClass(): LogPerBucketingStrategy = BY_CLASS /** - * A strategy which uses the [Class] name of the given key for log aggregation. + * A strategy that uses the [Class] name of the given key for log aggregation. * * This is useful when you need to aggregate over specific exceptions or similar * type-distinguished instances. @@ -190,7 +190,7 @@ public abstract class LogPerBucketingStrategy protected constructor( * Unlike [knownBounded], this strategy maps keys to a bounded set of identifiers, and * permits the use of non-singleton keys in [LoggingApi.per]. * - * If keys outside this set are used this strategy returns `null`, and + * If keys outside this set are used, this strategy returns `null`, and * log aggregation will not occur. * * Duplicates in [knownKeys] are ignored. @@ -221,7 +221,7 @@ public abstract class LogPerBucketingStrategy protected constructor( } /** - * A strategy which uses the [hashCode] of a given key, modulo [maxBuckets], for + * A strategy that uses the [hashCode] of a given key, modulo [maxBuckets], for * log aggregation. * * This is a fallback strategy for cases where the set of possible values is @@ -248,7 +248,7 @@ public abstract class LogPerBucketingStrategy protected constructor( * the typical expected number of unique keys. * * To avoid unwanted allocation at log sites, users are strongly encouraged to assign the - * returned value to a static field and pass that to any log statements which need it. + * returned value to a static field and pass that to any log statements that need it. */ @JvmStatic public fun byHashCode(maxBuckets: Int): LogPerBucketingStrategy { diff --git a/logging/src/commonMain/kotlin/io/spine/logging/LogSite.kt b/logging/src/commonMain/kotlin/io/spine/logging/LogSite.kt index 759661266..8a172b8e7 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/LogSite.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/LogSite.kt @@ -35,12 +35,12 @@ package io.spine.logging * For example, the logging [facade][LoggingApi] allows configuring of * a logging statement to be emitted only if a specific condition is satisfied. * Consider the [LoggingApi.atMostEvery] method, which configures a log statement - * to perform actual logging no often than once per the specified period when + * to perform actual logging no more often than once per the specified period when * called multiple times. To achieve this, the facade needs to track * previous invocations, and this information is part of metadata that is stored * for each statement. * - * Usually, this type if filled from a stack trace until it is injected + * Usually, this type is filled from a stack trace until it is injected * [manually][LoggingApi.withInjectedLogSite], or the used backend provides * its own mechanism to determine a log site. * diff --git a/logging/src/commonMain/kotlin/io/spine/logging/LogSiteStackTrace.kt b/logging/src/commonMain/kotlin/io/spine/logging/LogSiteStackTrace.kt index df14805ef..ac47d80d7 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/LogSiteStackTrace.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/LogSiteStackTrace.kt @@ -27,7 +27,7 @@ package io.spine.logging /** - * A synthetic exception which can be attached to log statements when additional stack trace + * A synthetic exception that can be attached to log statements when additional stack trace * information is required in log files or via tools such as ECatcher. */ @Suppress("UtilityClassWithPublicConstructor") diff --git a/logging/src/commonMain/kotlin/io/spine/logging/LoggingApi.kt b/logging/src/commonMain/kotlin/io/spine/logging/LoggingApi.kt index b91b022c1..edd4b64b0 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/LoggingApi.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/LoggingApi.kt @@ -40,8 +40,8 @@ import kotlin.time.DurationUnit * statement) and return the same API for chaining. * * The exceptions to this are: - * - Methods which return a NoOp implementation of the API in order to disable logging. - * - Methods which return an alternate API in order to implement context-specific grammar (though + * - Methods that return a NoOp implementation of the API in order to disable logging. + * - Methods that return an alternate API in order to implement context-specific grammar (though * these alternate APIs should always return the original logging API eventually). * * A hypothetical example of a context-specific grammar might be: @@ -292,7 +292,7 @@ public interface LoggingApi> { * This method allows an additional qualifier to be given which allows for * different conditional state for each unique qualifier. * - * This only makes a difference for log statements which use persistent state + * This only makes a difference for log statements that use persistent state * to control conditional behaviour (e.g., [atMostEvery] or [every]). * * This is the most general form of log aggregation and allows any keys to be used, @@ -357,7 +357,7 @@ public interface LoggingApi> { * This method allows an additional qualifier to be given which allows for * different conditional state for each unique qualifier. * - * This only makes a difference for log statements which use persistent state + * This only makes a difference for log statements that use persistent state * to control conditional behaviour (e.g., [atMostEvery] or [every]). * * This method is most useful in helping to avoid cases where a rare @@ -472,7 +472,7 @@ public interface LoggingApi> { * * - Keys that are recognised by specific logger backends (typically to control logging * behaviour in some way). - * - Key value pairs which are explicitly extracted from logs by tools. + * - Key-value pairs that are explicitly extracted from logs by tools. * * This method is just an alias for `with(key, true)` to improve readability. * @@ -589,7 +589,7 @@ public interface LoggingApi> { ): API /** - * An implementation of [LoggingApi] which does nothing, discarding all parameters. + * An implementation of [LoggingApi] that does nothing, discarding all parameters. * * Extending classes are likely to be non-wildcard, fully specified, no-op * implementations of the [API]. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/LoggingDomain.kt b/logging/src/commonMain/kotlin/io/spine/logging/LoggingDomain.kt index b7a8cc25f..b30cda699 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/LoggingDomain.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/LoggingDomain.kt @@ -29,7 +29,7 @@ package io.spine.logging import kotlin.annotation.AnnotationTarget.CLASS /** - * An annotation for classes which define a logging domain for loggers + * An annotation for classes that define a logging domain for loggers * created for the class. * * Logging statements for classes with the same logging domain are diff --git a/logging/src/commonMain/kotlin/io/spine/logging/LoggingFactory.kt b/logging/src/commonMain/kotlin/io/spine/logging/LoggingFactory.kt index c4a1a3622..975de6335 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/LoggingFactory.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/LoggingFactory.kt @@ -85,7 +85,7 @@ public expect object LoggingFactory { /** * Obtains a name of a logger to be used for this class. * - * For a fully-qualified class, its name will be used. + * For a fully qualified class, its name will be used. * Otherwise, if a class has a simple name, it will be used. * If a class does not have a simple name, the string representation * of the class will be returned. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/LoggingScope.kt b/logging/src/commonMain/kotlin/io/spine/logging/LoggingScope.kt index f1789d60c..24815b802 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/LoggingScope.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/LoggingScope.kt @@ -29,13 +29,13 @@ package io.spine.logging import io.spine.annotation.VisibleForTesting /** - * An opaque scope marker which can be attached to log sites to provide "per scope" behaviour + * An opaque scope marker that can be attached to log sites to provide "per scope" behaviour * for stateful logging operations (e.g., rate limiting). * * Scopes are provided via the [LoggingScopeProvider] interface and found by looking for * the current [ScopedLoggingContext][io.spine.logging.context.ScopedLoggingContext]. * - * Stateful fluent logging APIs which need to look up per log site information + * Stateful fluent logging APIs that need to look up per log site information * (e.g., rate limit state) should do so via a [LogSiteMap] using * the [LogSiteKey] passed into the [LogContext.postProcess] function. * @@ -53,7 +53,7 @@ import io.spine.annotation.VisibleForTesting public abstract class LoggingScope protected constructor(private val label: String) { /** - * Returns a specialization of the given key which accounts for this scope instance. + * Returns a specialization of the given key that accounts for this scope instance. * * Two specialized keys should compare as [equals] if and only if they are * specializations from the same log site, with the same sequence of scopes applied. @@ -72,7 +72,7 @@ public abstract class LoggingScope protected constructor(private val label: Stri protected abstract fun specialize(key: LogSiteKey): LogSiteKey /** - * Registers "hooks" which should be called when this scope is "closed". + * Registers "hooks" that should be called when this scope is "closed". * * The hooks are intended to remove the keys associated with this scope from any data * structures they may be held in, to avoid leaking allocations. @@ -81,7 +81,7 @@ public abstract class LoggingScope protected constructor(private val label: Stri * closed will remove it from any associated data structures. * * Conceptually, the scope that a log site is called from is the intersection of - * all the currently active scopes which apply to it. + * all the currently active scopes that apply to it. */ protected abstract fun onClose(removalHook: () -> Unit) @@ -103,11 +103,11 @@ public abstract class LoggingScope protected constructor(private val label: Stri public companion object { /** - * Creates a scope which automatically removes any associated keys + * Creates a scope that automatically removes any associated keys * from [LogSiteMap]s when it is garbage collected. * * The given label is used only for debugging purposes and may appear in log - * statements, it should not contain any user data or other runtime information. + * statements; it should not contain any user data or other runtime information. */ @JvmStatic public fun create(label: String): LoggingScope = WeakScope(label) diff --git a/logging/src/commonMain/kotlin/io/spine/logging/LoggingScopeProvider.kt b/logging/src/commonMain/kotlin/io/spine/logging/LoggingScopeProvider.kt index 1245e893b..b9983af10 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/LoggingScopeProvider.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/LoggingScopeProvider.kt @@ -30,7 +30,7 @@ package io.spine.logging * Provides a scope to a log statement via the [LogContext.per] method. * * This interface exists to avoid needing to pass specific instances of [LoggingScope] - * around in user code. The scope provider can lookup the correct scope instance for the current + * around in user code. The scope provider can look up the correct scope instance for the current * thread, and different providers can provide different types of scope. * E.g., you can have a provider for "request" scopes, and a provider for "subtask" scopes. * @@ -40,7 +40,7 @@ package io.spine.logging public fun interface LoggingScopeProvider { /** - * Returns the current scope (most likely via global or thread local state) or `null` if + * Returns the current scope (most likely via global or thread-local state) or `null` if * there is no current scope. */ public fun getCurrentScope(): LoggingScope? diff --git a/logging/src/commonMain/kotlin/io/spine/logging/MetadataKey.kt b/logging/src/commonMain/kotlin/io/spine/logging/MetadataKey.kt index 6512f7bc8..48bf6f487 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/MetadataKey.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/MetadataKey.kt @@ -37,7 +37,7 @@ import kotlin.reflect.KClass /** * A key for logging semi-structured metadata values. * - * Metadata keys can be used to provide log statements with strongly typed values which can be + * Metadata keys can be used to provide log statements with strongly typed values that can be * read and interpreted by logging backends or other logs related tools. This mechanism is * intended for values with specific semantics and should not be seen as a replacement for * logging arguments as part of a formatted log message. @@ -73,14 +73,14 @@ import kotlin.reflect.KClass * `withMetadata` method of the * [ScopedLoggingContext.Builder][io.spine.logging.context.ScopedLoggingContext.Builder]. * - * Custom subclasses of `MetadataKey` which override either of the protected [.emit] methods + * Custom subclasses of `MetadataKey` that override either of the protected [.emit] methods * should take care to avoid calling any code, which might trigger logging since this could lead * to unexpected recursion, especially if the key is being logged as part of a * `ScopedLoggingContext`. While there is protection against unbounded reentrant logging in * the logging framework, it is still best practice to avoid it where possible. * * Metadata keys are passed to a log statement via the `with()` method, so it can aid - * readability to choose a name for the constant field which reads "fluently" as part of the log + * readability to choose a name for the constant field that reads "fluently" as part of the log * statement. For example: * * ``` @@ -114,7 +114,7 @@ public open class MetadataKey( private val isCustom: Boolean ) { /** - * A short, human-readable text label which will prefix the metadata in cases + * A short, human-readable text label that will prefix the metadata in cases * where it is formatted as part of the log message. */ public val label: String = checkMetadataIdentifier(label) @@ -231,7 +231,7 @@ public open class MetadataKey( * * * Calling any code, which could log using the same `MetadataKey` instance (unless you * implement protection against reentrant calling in this method). - * * Calling code which might block (e.g., performing file I/O or acquiring locks). + * * Calling code that might block (e.g., performing file I/O or acquiring locks). * * * Allocating non-trivial amounts of memory (e.g., recording values in an unbounded data * structure). * @@ -271,7 +271,7 @@ public open class MetadataKey( emitRepeated(values, kvh) /** - * Prevent subclasses using `toString()` for anything unexpected. + * Prevents subclasses using `toString()` for anything unexpected. */ override fun toString(): String = this::class.qualifiedName + '/' + label + '[' + clazz.qualifiedName + ']' diff --git a/logging/src/commonMain/kotlin/io/spine/logging/MutableMetadata.kt b/logging/src/commonMain/kotlin/io/spine/logging/MutableMetadata.kt index 8b8744ed2..71b4fca86 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/MutableMetadata.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/MutableMetadata.kt @@ -117,7 +117,7 @@ internal class MutableMetadata : Metadata() { if (2 * (keyValueCount + 1) > keyValuePairs.size) { // Use doubling here (this code should almost never be hit in normal // usage and the total number of items should always stay relatively small. - // If this resizing algorithm is ever modified it is vital that the new value + // If this resizing algorithm is ever modified, it is vital that the new value // is always an even number. keyValuePairs = keyValuePairs.copyOf(2 * keyValuePairs.size) } diff --git a/logging/src/commonMain/kotlin/io/spine/logging/RateLimitStatus.kt b/logging/src/commonMain/kotlin/io/spine/logging/RateLimitStatus.kt index a38c703a4..6e077c5b4 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/RateLimitStatus.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/RateLimitStatus.kt @@ -35,9 +35,9 @@ import kotlinx.atomicfu.atomic * * ## Design Notes * - * The purpose of this class is to allow rate limiters to behave in a way which + * The purpose of this class is to allow rate limiters to behave in a way that * is consistent when multiple rate limiters are combined for a single log statement. - * If you are writing a rate limiter for logging which you want to "play well" with + * If you are writing a rate limiter for logging that you want to "play well" with * other rate limiters, it is essential that you understand how `RateLimitStatus` * is designed to work. * @@ -126,7 +126,7 @@ public abstract class RateLimitStatus protected constructor() { * Note that the skipped count is tracked via the "log site key" and there may be several * keys for a single log site (e.g., due to use of the `per(...)` methods). * - * This is consistent with everywhere else which handles log site specific state, + * This is consistent with everywhere else that handles log site specific state, * but does make it a little less obvious what the skipped count refers to at first glance. */ private class LogGuard { @@ -172,7 +172,7 @@ public abstract class RateLimitStatus protected constructor() { * Note: This method is never invoked concurrently with another `reset()` operation, * but it can be concurrent with calls to update rate limiter state. * Thus, it must be thread safe in general, but can assume it is the only reset operation - * active for the limiter which returned it. + * active for the limiter that returned it. */ internal abstract fun reset() diff --git a/logging/src/commonMain/kotlin/io/spine/logging/StackSize.kt b/logging/src/commonMain/kotlin/io/spine/logging/StackSize.kt index 936d84566..bb860eaa7 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/StackSize.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/StackSize.kt @@ -42,14 +42,14 @@ package io.spine.logging public enum class StackSize(public val maxDepth: Int) { /** - * Produces a small stack suitable for finer grained debugging. + * Produces a small stack suitable for finer-grained debugging. * * For performance reasons, this is the only stack size suitable for log statements at * level `INFO` or finer, but it may also be useful for `WARNING` level log statements * in cases where context is not as important. For `SEVERE` log statements, it is * advised to use a stack size of [MEDIUM] or above. * - * Requesting a small stack trace for log statements which occur under normal + * Requesting a small stack trace for log statements that occur under normal * circumstances is acceptable but may affect performance. Consider using * [LoggingApi.withStackTrace] in conjunction with rate-limiting methods, * such as [LoggingApi.atMostEvery], to mitigate performance issues. @@ -66,7 +66,7 @@ public enum class StackSize(public val maxDepth: Int) { * trace elements in a `MEDIUM` stack to provide sufficient debugging context in most * cases. * - * Requesting a medium stack trace for any log statements which can occur regularly + * Requesting a medium stack trace for any log statements that can occur regularly * under normal circumstances is not recommended. * * The current maximum size of a `MEDIUM` stack trace is 20 elements, but this @@ -77,10 +77,10 @@ public enum class StackSize(public val maxDepth: Int) { /** * Produces a large stack suitable for providing highly detailed contextual information. * - * This is most useful for `SEVERE` log statements which might be processed by external + * This is most useful for `SEVERE` log statements that might be processed by external * tools and subject to automated analysis. * - * Requesting a large stack trace for any log statement which can occur under normal + * Requesting a large stack trace for any log statement that can occur under normal * circumstances is not recommended. * * The current maximum size of a `LARGE` stack trace is 50 elements, but this @@ -94,7 +94,7 @@ public enum class StackSize(public val maxDepth: Int) { * This is included for situations in which it is known that the uppermost elements * of the stack are definitely required for analysis. * - * Requesting a full stack trace for any log statement which can occur under normal + * Requesting a full stack trace for any log statement that can occur under normal * circumstances is not recommended. */ FULL(-1), diff --git a/logging/src/commonMain/kotlin/io/spine/logging/WeakRef.kt b/logging/src/commonMain/kotlin/io/spine/logging/WeakRef.kt index f91d1ad3f..6761465c6 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/WeakRef.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/WeakRef.kt @@ -27,7 +27,7 @@ package io.spine.logging /** - * A weak reference holder that manages references which can be garbage collected. + * A weak reference holder that manages references that can be garbage collected. * * This class provides platform-specific implementation of weak references, * which allow objects to be garbage collected when they are no longer strongly diff --git a/logging/src/commonMain/kotlin/io/spine/logging/WithLogging.kt b/logging/src/commonMain/kotlin/io/spine/logging/WithLogging.kt index 8e0618302..ea7bd582f 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/WithLogging.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/WithLogging.kt @@ -29,7 +29,7 @@ package io.spine.logging import io.spine.logging.LoggingFactory.loggerFor /** - * Provides [Logger] instance as a property. + * Provides a [Logger] instance as a property. * * Implement this interface when logging is needed. * diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/BackendFactory.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/BackendFactory.kt index 83e08c7c5..3c993e092 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/BackendFactory.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/BackendFactory.kt @@ -36,7 +36,7 @@ package io.spine.logging.backend * * Any implementation of this API **MUST** follow the rules listed below to avoid any risk of * re-entrant code calling during logger initialization. Failure to do so risks creating complex, - * hard to debug, issues with Flogger configuration. + * hard-to-debug, issues with Flogger configuration. * * 1. Implementations **MUST NOT** attempt any logging in static methods or constructors. * 2. Implementations **MUST NOT** statically depend on any unknown code. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/Clock.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/Clock.kt index 44084bab1..eb0f8183d 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/Clock.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/Clock.kt @@ -36,7 +36,7 @@ package io.spine.logging.backend * * Any implementation of this API **MUST** follow the rules listed below to avoid any risk of * re-entrant code calling during logger initialization. Failure to do so risks creating complex, - * hard to debug, issues with Flogger configuration. + * hard-to-debug, issues with Flogger configuration. * * 1. Implementations **MUST NOT** attempt any logging in static methods or constructors. * 2. Implementations **MUST NOT** statically depend on any unknown code. @@ -47,7 +47,7 @@ package io.spine.logging.backend * easiest way to achieve this is to simply avoid having any non-trivial static fields or any * instance fields at all in the implementation. * - * While this sounds onerous it's not difficult to achieve because this API is a singleton, and + * While this sounds onerous, it's not difficult to achieve because this API is a singleton, and * can delay any actual work until its methods are called. For example if any additional state is * required in the implementation, it can be held via a "lazy holder" to defer initialization. * diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/KeyValueFormatter.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/KeyValueFormatter.kt index a132c6aa7..3821f0cf8 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/KeyValueFormatter.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/KeyValueFormatter.kt @@ -51,7 +51,7 @@ import io.spine.logging.KeyValueHandler * - If no key/value pairs are handled, the log message is unchanged (no prefix is added). * - Keys can be repeated. * - Key labels do not need quoting. - * - String-like values are properly quoted and escaped (e.g. \", \\, \n, \t) + * - String-like values are properly quoted and escaped (e.g. \", \\, \n, \t). * - Unsafe control characters in string-like values are replaced by U+FFFD (�). * - All key/value pairs are on the "same line" of the log message. * @@ -125,7 +125,7 @@ public class KeyValueFormatter( /** * Helper method to emit metadata key/value pairs in a format consistent with JSON. * - * String values which need to be quoted are JSON escaped, while other values are appended + * String values that need to be quoted are JSON escaped, while other values are appended * without quoting or escaping. Labels are expected to be JSON "safe", and are never quoted. * * This format is compatible with various "lightweight" JSON representations. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/LogCallerFinder.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/LogCallerFinder.kt index f3cab1fe5..600ae393a 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/LogCallerFinder.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/LogCallerFinder.kt @@ -34,7 +34,7 @@ import kotlin.reflect.KClass /** * API for determining the logging class and log statement sites, - * return from [Platform.getCallerFinder]. + * returned from [Platform.getCallerFinder]. * * These classes are immutable and thread-safe. * @@ -48,7 +48,7 @@ import kotlin.reflect.KClass * * Any implementation of this API *MUST* follow the rules listed below to avoid any risk of * re-entrant code calling during logger initialization. Failure to do so risks creating complex, - * hard to debug, issues with Flogger configuration. + * hard-to-debug, issues with Flogger configuration. * * 1. Implementations *MUST NOT* attempt any logging in static methods or constructors. * 2. Implementations *MUST NOT* statically depend on any unknown code. @@ -60,7 +60,7 @@ import kotlin.reflect.KClass * easiest way to achieve this is to simply avoid having any non-trivial static fields or any * instance fields at all in the implementation. * - * While this sounds onerous it is not difficult to achieve because this API is a singleton, and + * While this sounds onerous, it is not difficult to achieve because this API is a singleton, and * can delay any actual work until its methods are called. For example, if any additional state is * required in the implementation, it can be held via a "lazy holder" to defer initialization. * @@ -77,8 +77,8 @@ public abstract class LogCallerFinder { * This is useful when determining the class name with which to create a logger backend. * * @param loggerClass The class containing the log() methods whose caller we need to find. - * @return The name of the class called the specified logger. - * @throws IllegalStateException If there was no caller of the specified logged passed + * @return The name of the class that called the specified logger. + * @throws IllegalStateException If there was no caller of the specified logger passed * on the stack (which may occur if the logger class was invoked directly by JNI). */ public abstract fun findLoggingClass(loggerClass: KClass>): String @@ -88,7 +88,7 @@ public abstract class LogCallerFinder { * on the given logging class. * * @param loggerApi The class containing the log() methods whose caller we need to find. - * @param stackFramesToSkip The number of method calls which exist on the stack between the + * @param stackFramesToSkip The number of method calls that exist on the stack between the * `log()` method, and the point at which this method is invoked. * @return A log site inferred from the stack, or [io.spine.logging.LogSite.Invalid] if no log site * can be determined. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/LogData.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/LogData.kt index ca390e705..6a1d098ec 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/LogData.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/LogData.kt @@ -35,7 +35,7 @@ import io.spine.logging.LogSite * Some metadata is expected to be available for all log statements (such as the log level or a * timestamp) whereas other data is optional (class/method name for example). * - * As well providing the common logging metadata, customized loggers can choose to add arbitrary + * As well as providing the common logging metadata, customized loggers can choose to add arbitrary * key/value pairs to the log data. It is up to each logging backend implementation to decide how * it interprets this data using the hierarchical key. * @@ -87,7 +87,7 @@ public interface LogData { * Returns whether this log statement should be emitted regardless of its log * level or any other properties. * - * This allows extensions of `LogContext` or `LoggingBackend` which implement + * This allows extensions of `LogContext` or `LoggingBackend` that implement * additional filtering or rate-limiting fluent methods to easily check whether * a log statement was forced. * diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/LogMessageFormatter.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/LogMessageFormatter.kt index b367f598b..727f73df0 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/LogMessageFormatter.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/LogMessageFormatter.kt @@ -43,7 +43,7 @@ public abstract class LogMessageFormatter { // TODO(dbeaumont): This [class] needs to either move into "system" or be extended somehow. // This is currently tightly coupled with the JDK log handler behaviour // (by virtue of what data is expected to be used for formatting) so it is - // not suitable as a general purpose API yet. + // not suitable as a general-purpose API yet. /** * Returns a formatted representation of the log message and metadata. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/LoggerBackend.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/LoggerBackend.kt index 40709f5e2..54a49b5a7 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/LoggerBackend.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/LoggerBackend.kt @@ -38,15 +38,15 @@ import io.spine.logging.Level * that logger backends have as little per-instance state as possible. * * It is also essential that no implementation of `LoggerBackend` - * ever holds onto user supplied objects (especially log statement arguments) + * ever holds onto user-supplied objects (especially log statement arguments) * after the `log()` or `handleError()` methods to which they * were passed have exited. * * This means that **ALL** formatting or serialization of log statement arguments or * metadata values **MUST** be completed inside the log method itself. - * If the backend needs to perform asynchronous I/O operations it can do so + * If the backend needs to perform asynchronous I/O operations, it can do so * by constructing a serialized form of the [LogData] instance and - * enqueing that for processing. + * enqueuing that for processing. * * Note also that this restriction is **NOT** purely about mutable arguments (which could * change before formatting occurs and produce incorrect output), but also stops log statements from @@ -104,16 +104,16 @@ public abstract class LoggerBackend { * Typically, a backend would handle an error by logging an alternative representation of * the "bad" log data, being careful not to allow any more exceptions to occur. * - * If a backend chooses to propagate an error (e.g., when testing or debugging) + * If a backend chooses to propagate an error (e.g., when testing or debugging), * it must wrap it in [LoggingException] to avoid it being re-caught. * - * @param error the exception throw when `badData` was initially logged. - * @param badData the original `LogData` instance which caused an error. + * @param error the exception thrown when `badData` was initially logged. + * @param badData the original `LogData` instance that caused an error. * It is not expected that simply trying to log this again will succeed, and error * handlers must be careful in how they handle this instance, its arguments and metadata. * References to `badData` must not be held after the `handleError` invocation returns. * - * @throws LoggingException to indicate an error which should be propagated into user code. + * @throws LoggingException to indicate an error that should be propagated into user code. */ public abstract fun handleError(error: RuntimeException, badData: LogData) } diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/LoggingException.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/LoggingException.kt index 5acd7526c..9679e640a 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/LoggingException.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/LoggingException.kt @@ -30,13 +30,13 @@ package io.spine.logging.backend * An exception thrown when a log statement cannot be emitted correctly. * * This exception should only be thrown by logger backend implementations - * which have opted not to handle specific issues. + * that have opted not to handle specific issues. * * Typically, a logger backend would only throw `LoggingException` in response * to issues in **test code** or other debugging environments. * * In **production code**, the backend should be configured - * to emit a modified log statement which includes the error information. + * to emit a modified log statement that includes the error information. * * @see LoggerBackend.handleError * diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/Metadata.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/Metadata.kt index 07c5b3e21..3ae1199ac 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/Metadata.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/Metadata.kt @@ -29,15 +29,15 @@ package io.spine.logging.backend import io.spine.logging.MetadataKey /** - * A sequence of metadata key/value pairs which can be associated to a log statement, - * either directly via methods in the fluent API, of as part of a scoped logging context. + * A sequence of metadata key/value pairs that can be associated to a log statement, + * either directly via methods in the fluent API, or as part of a scoped logging context. * * Metadata keys can be "single valued" or "repeating" based on [MetadataKey.canRepeat], * but it is permitted for a `Metadata` implementation to retain multiple single valued * keys, and in that situation the key at the largest index is the one that should be used. * * Multiple `Metadata` instances can be merged, in order, to provide a final sequence for - * a log statement. When `Metadata` instance are merged, the result is just the concatenation + * a log statement. When `Metadata` instances are merged, the result is just the concatenation * of the sequence of key/value pairs, and this is what results in the potential for multiple * single valued keys to exist. * @@ -67,16 +67,16 @@ public abstract class Metadata { /** * Returns the key for the Nth piece of metadata. * - * @throws IndexOutOfBoundsException if either `n` is negative or `n` is greater - * or equal to `getCount()`. + * @throws IndexOutOfBoundsException if either `n` is negative or `n` is greater than + * or equal to `size()`. */ public abstract fun getKey(n: Int): MetadataKey /** * Returns the non-null value for the Nth piece of metadata. * - * @throws IndexOutOfBoundsException if either `n` is negative or `n` is greater - * or equal to `getCount()`. + * @throws IndexOutOfBoundsException if either `n` is negative or `n` is greater than + * or equal to `size()`. */ public abstract fun getValue(n: Int): Any diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataHandler.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataHandler.kt index 37330745d..ad1e664e5 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataHandler.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataHandler.kt @@ -85,7 +85,7 @@ public abstract class MetadataHandler { } /** - * Builder for a map-based [MetadataHandler] which allows handlers to + * Builder for a map-based [MetadataHandler] that allows handlers to * be associated with individual callbacks. * * @param C The context type. @@ -250,7 +250,7 @@ public abstract class MetadataHandler { * which can result in repeated keys being seen more than once. * * A default handler is required because no handler can know the complete set of - * keys which might be available and it is very undesirable to drop unknown keys. + * keys that might be available and it is very undesirable to drop unknown keys. * * If default repeated values should be handled together, * [Builder.setDefaultRepeatedHandler] should be called as well. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataKeyValueHandlers.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataKeyValueHandlers.kt index baf87669c..f5c7050d1 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataKeyValueHandlers.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataKeyValueHandlers.kt @@ -51,27 +51,27 @@ public object MetadataKeyValueHandlers { } /** - * Returns a singleton value handler which dispatches metadata to a [KeyValueHandler]. + * Returns a singleton value handler that dispatches metadata to a [KeyValueHandler]. */ @JvmStatic public fun getDefaultValueHandler(): ValueHandler = EMIT_METADATA /** - * Returns a singleton value handler which dispatches metadata to a [KeyValueHandler]. + * Returns a singleton value handler that dispatches metadata to a [KeyValueHandler]. */ @JvmStatic public fun getDefaultRepeatedValueHandler(): RepeatedValueHandler = EMIT_REPEATED_METADATA /** - * Returns a new [MetadataHandler.Builder] which handles all non-ignored + * Returns a new [MetadataHandler.Builder] that handles all non-ignored * metadata keys by dispatching their values to the key itself. * * This is convenient for generic metadata processing when used in conjunction with * something like [KeyValueFormatter]. * - * The returned builder can be built immediately or customized further to handler some keys + * The returned builder can be built immediately or customized further to handle some keys * specially (e.g., allowing keys/values to modify logging behaviour). * * @return a builder configured with the default key/value handlers and ignored keys. @@ -85,7 +85,7 @@ public object MetadataKeyValueHandlers { .ignoring(ignored) /** - * Returns a new [MetadataHandler] which handles all non-ignored + * Returns a new [MetadataHandler] that handles all non-ignored * metadata keys by dispatching their values to the key itself. * * This is convenient for generic metadata processing when used in diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataProcessor.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataProcessor.kt index f00764390..87ef5a0bb 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataProcessor.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/MetadataProcessor.kt @@ -61,7 +61,7 @@ public abstract class MetadataProcessor { public companion object { /** - * Immutable empty processor which never handles any metadata. + * Immutable empty processor that never handles any metadata. */ private val EMPTY_PROCESSOR = NoOpProcessor() @@ -169,7 +169,7 @@ public abstract class MetadataProcessor { } /** - * Immutable no-op processor which never handles any metadata. + * Immutable no-op processor that never handles any metadata. */ private class NoOpProcessor: MetadataProcessor() { @@ -183,7 +183,7 @@ private class NoOpProcessor: MetadataProcessor() { } /** - * The metadata processor involved when the number of metadata elements is less or + * The metadata processor involved when the number of metadata elements is less than or * equal to [MAX_LIGHTWEIGHT_ELEMENTS]. * * The values in the [keyMap] array are structured as: @@ -200,7 +200,7 @@ private class NoOpProcessor: MetadataProcessor() { * Obviously, this could be extended to a `long`, but the bloom filter is only efficient up to * about 10-15 elements (and that's a super rare case anyway). * - * At some point it is just not worth trying to squeeze anymore value from this class, and + * At some point it is just not worth trying to squeeze any more value from this class, and * the [SimpleProcessor] should be used instead (we might even want to switch before hitting * 28 elements depending on performance). */ @@ -226,8 +226,8 @@ private class LightweightProcessor( init { // We can never have more distinct keys, so this never needs resizing. - // This should be the only variable sized allocation required by this algorithm. - // When duplicate keys exist some elements at the end of the array will be unused, + // This should be the only variable-sized allocation required by this algorithm. + // When duplicate keys exist, some elements at the end of the array will be unused, // but the array is typically small and it is common for all keys to be distinct, // so "right sizing" the array wouldn't be worth it. val maxKeyCount = scope.size() + logged.size() @@ -296,7 +296,7 @@ private class LightweightProcessor( override fun keySet(): Set> { // We may want to cache this, since it's effectively immutable, - // but it's also a small and likely short lived instance, + // but it's also a small and likely short-lived instance, // so quite possibly not worth it for the cost of another field. return object : AbstractSet>() { @@ -420,7 +420,7 @@ private class LightweightProcessor( * * ### Implementation note * This could be made a reusable instance (reset between callbacks) if we wanted to - * same a little on allocations. However, this is a fixed size instance, and repeated + * save a little on allocations. However, this is a fixed-size instance, and repeated * keys are a fairly unusual use case. */ @Suppress("MagicNumber") @@ -469,7 +469,7 @@ private class LightweightProcessor( } /** - * A simple version of a metadata processor which allocates "large" data structures. + * A simple version of a metadata processor that allocates "large" data structures. * * This is needed when a large number of metadata elements need processing. * It should behave exactly the same as the [LightweightProcessor] if diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/Platform.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/Platform.kt index efeaf801a..3bb7d3e2f 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/Platform.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/Platform.kt @@ -62,7 +62,7 @@ public abstract class Platform { * Returns the current depth of recursion for logging in the current thread. * * This method is intended only for use by logging backends or the core of the Logging library. - * It needs to be called by code which is invoking user code that might trigger + * It needs to be called by code that is invoking user code that might trigger * reentrant logging. * * - A value of 1 means that this thread is in a normal log statement. @@ -135,7 +135,7 @@ public abstract class Platform { * or other filtering. * * This method is intended to be invoked unconditionally from a fluent logger's - * `at(Level)` method to permit overriding of default logging behavior. + * `at(Level)` method to permit overriding of default logging behaviour. * * @param loggerName The fully qualified logger name (e.g., "com.example.SomeClass"). * @param level The level of the log statement being invoked. @@ -225,7 +225,7 @@ public abstract class Platform { * Returns the implementation of [LogCallerFinder] for this platform. * * Platform implementations must provide their own [LogCallerFinder] - * which handles stack trace analysis in a platform-specific way. + * that handles stack trace analysis in a platform-specific way. */ protected abstract fun getCallerFinderImpl(): LogCallerFinder diff --git a/logging/src/commonMain/kotlin/io/spine/logging/backend/SimpleMessageFormatter.kt b/logging/src/commonMain/kotlin/io/spine/logging/backend/SimpleMessageFormatter.kt index 7d854298a..3a1060aa4 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/backend/SimpleMessageFormatter.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/backend/SimpleMessageFormatter.kt @@ -43,7 +43,7 @@ import io.spine.logging.backend.SimpleMessageFormatter.mustBeFormatted * Note however, that it makes several assumptions regarding metadata and formatting, * which may not apply to every text-based logging backend. * - * This primarily exists to support both the JDK logging classes and text only Android backends. + * This primarily exists to support both the JDK logging classes and text-only Android backends. * Code in here may be factored out as necessary to support other use cases in the future. * * If a text-based logger backend is not performance-critical, then it should just append the log @@ -93,7 +93,7 @@ public object SimpleMessageFormatter { public fun getDefaultFormatter(): LogMessageFormatter = defaultFormatter /** - * Returns a log message formatter which formats log messages in the form: + * Returns a log message formatter that formats log messages in the form: * * ``` * Log message [CONTEXT key="value" id=42 ] @@ -168,7 +168,7 @@ public object SimpleMessageFormatter { logData.literalArgument.safeToString() /** - * An internal helper function for logger backends which are aggressively + * An internal helper function for logger backends that are aggressively * optimized for performance. * * This function is a best-effort optimization and should not be necessary for most @@ -178,8 +178,8 @@ public object SimpleMessageFormatter { * default message formatting performed by the other methods in this class would * just result in the literal log message being used, with no additional formatting. * - * If this method returns `false` then the literal log message can be obtained via - * [getLiteralLogMessage], otherwise it must be formatted manually. + * If this method returns `false`, then the literal log message can be obtained via + * [getLiteralLogMessage]; otherwise it must be formatted manually. * * By calling this class it is possible to more easily detect cases where using * buffers to format the log message is not required. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/context/ContextDataProvider.kt b/logging/src/commonMain/kotlin/io/spine/logging/context/ContextDataProvider.kt index ae7e130ca..d1febd7db 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/context/ContextDataProvider.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/context/ContextDataProvider.kt @@ -82,11 +82,11 @@ public abstract class ContextDataProvider { /** * Returns whether the given logger should have logging forced at the specified level. * - * When logging is forced for a log statement, it will be emitted regardless or + * When logging is forced for a log statement, it will be emitted regardless of * the normal log level configuration of the logger and ignoring any rate limiting or * other filtering. * - * Implementations which do not support forced logging should not override this method; + * Implementations that do not support forced logging should not override this method; * the default implementation returns `false`. * * `loggerName` can be used to look up specific configuration, such as log level, @@ -131,7 +131,7 @@ public abstract class ContextDataProvider { * These tags can be used to provide additional contextual metadata * to log statements (e.g., request IDs). * - * Implementations which do not support scoped [Tags] should not override this method; + * Implementations that do not support scoped [Tags] should not override this method; * the default implementation returns [Tags.empty]. */ public open fun getTags(): Tags = Tags.empty() @@ -142,7 +142,7 @@ public abstract class ContextDataProvider { * Scoped metadata can be used to provide structured data to log statements or * control logging behaviour (in conjunction with a custom logger backend). * - * Implementations which do not support scoped [Metadata] should not override this + * Implementations that do not support scoped [Metadata] should not override this * method; the default implementation returns [Metadata.Companion.empty]. */ public open fun getMetadata(): Metadata = Metadata.Companion.empty() @@ -153,7 +153,7 @@ public abstract class ContextDataProvider { * * This method searches parent contexts as well. * - * Implementations which do not support scope types should return `null`, + * Implementations that do not support scope types should return `null`, * which can be achieved by using the default method. */ public open fun getScope(type: ScopeType): LoggingScope? = null @@ -174,7 +174,7 @@ public abstract class ContextDataProvider { /** * Returns the singleton no-op context data provider, which can be used by platform - * implementations which do not support `ScopedLoggingContext` for some reason. + * implementations that do not support `ScopedLoggingContext` for some reason. * * The returned provider has no effect and returns empty/default data in all cases. * diff --git a/logging/src/commonMain/kotlin/io/spine/logging/context/ContextMetadata.kt b/logging/src/commonMain/kotlin/io/spine/logging/context/ContextMetadata.kt index c7d0bfff7..b2eaf5c13 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/context/ContextMetadata.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/context/ContextMetadata.kt @@ -40,7 +40,7 @@ import org.jetbrains.annotations.NotNull * should not be considered a stable API. * * @see - * Original Java code> for historical context. + * Original Java code for historical context. */ public abstract class ContextMetadata protected constructor() : Metadata() { @@ -53,7 +53,7 @@ public abstract class ContextMetadata protected constructor() : Metadata() { ) /** - * A builder to collect metadata key/values pairs in order. + * A builder to collect metadata key/value pairs in order. * * This class is only expected to be needed by implementations of [ScopedLoggingContext] and * should not be considered a stable API. @@ -70,7 +70,7 @@ public abstract class ContextMetadata protected constructor() : Metadata() { private val entries = ArrayList>(2) /** - * Add a single metadata key/value pair to the builder. + * Adds a single metadata key/value pair to the builder. */ @CanIgnoreReturnValue public fun add(key: MetadataKey, value: T): Builder { @@ -127,7 +127,7 @@ public abstract class ContextMetadata protected constructor() : Metadata() { public fun builder(): Builder = Builder() /** - * Returns a space efficient [ContextMetadata] containing a single value. + * Returns a space-efficient [ContextMetadata] containing a single value. */ @JvmStatic public fun singleton(key: MetadataKey, value: T): ContextMetadata = diff --git a/logging/src/commonMain/kotlin/io/spine/logging/context/LogLevelMap.kt b/logging/src/commonMain/kotlin/io/spine/logging/context/LogLevelMap.kt index 7ce2a342f..e83e5bacb 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/context/LogLevelMap.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/context/LogLevelMap.kt @@ -85,7 +85,7 @@ public class LogLevelMap private constructor(map: Map, defaultLev } /** - * Builder for log level map which uses type safe class/package keys (but requires that they be + * Builder for log level map that uses type-safe class/package keys (but requires that they be * present in the JVM at the time the map is created). To set up a [LogLevelMap] with only * class/package names, use [LogLevelMap.create] with a map and level or just a map. */ @@ -163,7 +163,7 @@ public class LogLevelMap private constructor(map: Map, defaultLev public fun builder(): Builder = Builder() /** - * Returns an empty [LogLevelMap] with a single default level which + * Returns an empty [LogLevelMap] with a single default level that * will apply to all loggers. */ @JvmStatic @@ -214,7 +214,7 @@ public fun LogLevelMap.levelOf(cls: KClass<*>): Level = levelOf(cls.toLoggerName /** * Builds a new [LogLevelMap] by populating a newly created [LogLevelMap.Builder] - * using providing [builderAction]. + * using [builderAction]. */ public fun logLevelMap(builderAction: LogLevelMap.Builder.() -> Unit): LogLevelMap { val builder = LogLevelMap.builder() diff --git a/logging/src/commonMain/kotlin/io/spine/logging/context/NoOpContextDataProvider.kt b/logging/src/commonMain/kotlin/io/spine/logging/context/NoOpContextDataProvider.kt index 54930f5b8..a7d29d04c 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/context/NoOpContextDataProvider.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/context/NoOpContextDataProvider.kt @@ -48,7 +48,7 @@ internal class NoOpContextDataProvider private constructor() : ContextDataProvid /** * Returns a singleton "no op" instance of the context data provider - * API which logs a warning if used in code which attempts to set context + * API that logs a warning if used in code that attempts to set context * information or modify scopes. * * This is intended for use by platform implementations in cases @@ -64,7 +64,7 @@ internal class NoOpContextDataProvider private constructor() : ContextDataProvid private class NoOpScopedLoggingContext : ScopedLoggingContext(), AutoCloseable { - // Since the ContextDataProvider class is loaded during Platform initialization we must be very + // Since the ContextDataProvider class is loaded during Platform initialization, we must be very // careful to avoid any attempt to obtain a logger instance until we can be sure logging config // is complete. private object LazyLogger : WithLogging diff --git a/logging/src/commonMain/kotlin/io/spine/logging/context/ScopeType.kt b/logging/src/commonMain/kotlin/io/spine/logging/context/ScopeType.kt index e9aea63a8..b9836e28b 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/context/ScopeType.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/context/ScopeType.kt @@ -30,7 +30,7 @@ import io.spine.logging.LoggingScope import io.spine.logging.LoggingScopeProvider /** - * Singleton keys which identify different types of scopes which scoped contexts can be bound to. + * Singleton keys that identify different types of scopes that scoped contexts can be bound to. * * To bind a context to a scope type, create the context with that type: * diff --git a/logging/src/commonMain/kotlin/io/spine/logging/context/ScopedLoggingContext.kt b/logging/src/commonMain/kotlin/io/spine/logging/context/ScopedLoggingContext.kt index 06dd5a97e..9e5282e11 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/context/ScopedLoggingContext.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/context/ScopedLoggingContext.kt @@ -43,7 +43,7 @@ import io.spine.logging.context.ScopedLoggingContext.Companion.getInstance * - Forcing logging at a finer level for a specific request * (e.g., based on a URL debug parameter). * - * Contexts are nestable and new contexts can be added to provide additional metadata which will + * Contexts are nestable and new contexts can be added to provide additional metadata that will * be available to logging as long as the context is installed. * * Note that in the current API contexts are also modifiable after creation, but this usage is @@ -52,7 +52,7 @@ import io.spine.logging.context.ScopedLoggingContext.Companion.getInstance * added to a context when it is being used concurrently by multiple threads. * * Note that since logging contexts are designed to be modified by code in libraries and helper - * functions which do not know about each other, the data structures and behaviour of logging + * functions that do not know about each other, the data structures and behaviour of logging * contexts are carefully designed to avoid any accidental "undoing" of existing behaviour. * In particular: * @@ -76,7 +76,7 @@ import io.spine.logging.context.ScopedLoggingContext.Companion.getInstance * Context support and automatic propagation is heavily reliant on Java platform capabilities, * and precise behaviour is likely to differ between runtime environments or frameworks. Context * propagation may not behave the same everywhere, and in some situations logging contexts may not - * be supported at all. Methods which attempt to affect a context state may do nothing in some + * be supported at all. Methods that attempt to affect a context state may do nothing in some * environments or when called at some points in an application. If application code relies on * modifications to an existing, implicit logging context, it should always check the return values * of any modification methods called (e.g. [addTags]). @@ -216,7 +216,7 @@ public abstract class ScopedLoggingContext protected constructor() { /** * Calls a function directly within a new context installed from this builder, - * wrapping any thrown exception with a [IllegalStateException] + * wrapping any thrown exception with an [IllegalStateException] * if it's not a [RuntimeException]. */ @CanIgnoreReturnValue @@ -253,7 +253,7 @@ public abstract class ScopedLoggingContext protected constructor() { * context is opened, and restore the previous state when it terminates. * * Note that the returned [AutoCloseable] is not required to enforce the - * correct closure of nested contexts, and while it is permitted to throw a + * correct closure of nested contexts, and while it is permitted to throw an * [InvalidLoggingContextStateException] in the face of mismatched or invalid usage, * it is not required. */ @@ -291,7 +291,7 @@ public abstract class ScopedLoggingContext protected constructor() { * val result = ctx.newContext().withTags(Tags.of("my_tag", someValue)).call { MyClass.doFoo() } * ``` * - * Implementations of this API must return a subclass of [Builder] which can install + * Implementations of this API must return a subclass of [Builder] that can install * all necessary metadata into a new context from the builder's current state. * * Note for users: if you do not need an instance of `ScopedLoggingContext` for some @@ -313,7 +313,7 @@ public abstract class ScopedLoggingContext protected constructor() { * This method is the same as [newContext] except it additionally binds a new * [ScopeType] instance to the newly created context. * This allows log statements to control stateful logging operations (e.g., rate limiting) - * using [io.spine.logging.LoggingApi.per] method. + * using the [io.spine.logging.LoggingApi.per] method. * * Note for users: if you do not need an instance of `ScopedLoggingContext` for some * reason such as testability (injecting it, for example), consider using the static methods in @@ -362,7 +362,7 @@ public abstract class ScopedLoggingContext protected constructor() { * since that may create non-deterministic ordering. * * It is recommended (where possible) to add metadata when building - * a new context, rather than adding it to context visible to multiple threads. + * a new context, rather than adding it to a context visible to multiple threads. */ @CanIgnoreReturnValue public open fun addMetadata(key: MetadataKey, value: T): Boolean { @@ -399,7 +399,7 @@ public abstract class ScopedLoggingContext protected constructor() { * * This is a singleton value and need not be cached by callers. * If logging contexts are not supported, this method will return - * an empty context implementation which has no effect. + * an empty context implementation that has no effect. */ @JvmStatic public fun getInstance(): ScopedLoggingContext = @@ -419,7 +419,7 @@ public abstract class ScopedLoggingContext protected constructor() { try { context.close() } catch (e: RuntimeException) { - // This method is always called from a `finally` block which may + // This method is always called from a `finally` block that may // be about to rethrow a user exception, so ignore any errors // during `close()` if that's the case. if (!callerHasError) { diff --git a/logging/src/commonMain/kotlin/io/spine/logging/context/ScopedLoggingContexts.kt b/logging/src/commonMain/kotlin/io/spine/logging/context/ScopedLoggingContexts.kt index 468461afa..de3c74194 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/context/ScopedLoggingContexts.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/context/ScopedLoggingContexts.kt @@ -39,7 +39,7 @@ import kotlin.time.DurationUnit.MINUTES * [ScopedLoggingContext] that would be returned by * [ScopedLoggingContext.getInstance]. * - * @see * Original Java code for historical context. */ public object ScopedLoggingContexts : WithLogging { @@ -124,7 +124,7 @@ public object ScopedLoggingContexts : WithLogging { * * 1. Call or wrap a new context with metadata added to it. * 2. [ScopedLoggingContext.Builder.install] a new - * context and close it when you it exits (e.g., if you are using + * context and close it when it exits (e.g., if you are using * callbacks to listen to state changes in a task). * However, it is vital that the returned [AutoCloseable] is always closed. * 3. Call this method and check it succeeded (e.g., logging a warning if it fails). @@ -135,7 +135,7 @@ public object ScopedLoggingContexts : WithLogging { * values for the same metadata key from multiple threads, since that may * create non-deterministic ordering. It is recommended (where possible) * to add metadata when building a new context, rather than adding it to - * context visible to multiple threads. + * a context visible to multiple threads. * * @param T The type of the metadata value. * @param key The metadata key. @@ -157,7 +157,7 @@ public object ScopedLoggingContexts : WithLogging { * * 1. Call or wrap a new context with metadata added to it. * 2. [ScopedLoggingContext.Builder.install] a new - * context and close it when you it exits (e.g., if you are using + * context and close it when it exits (e.g., if you are using * callbacks to listen to state changes in a task). * However, it is vital that the returned [AutoCloseable] is always closed. * 3. Call this method and check that it succeeded (e.g., logging a warning if it fails). diff --git a/logging/src/commonMain/kotlin/io/spine/logging/context/SegmentTrie.kt b/logging/src/commonMain/kotlin/io/spine/logging/context/SegmentTrie.kt index b4d575435..fd8a0e2df 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/context/SegmentTrie.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/context/SegmentTrie.kt @@ -55,7 +55,7 @@ import kotlin.math.min internal abstract class SegmentTrie(private val defaultValue: T) { /** - * Returns the value of the entry which most closely matches the given key. + * Returns the value of the entry that most closely matches the given key. */ abstract fun find(key: String): T @@ -104,7 +104,7 @@ private class SingletonTrie( ) : SegmentTrie(defaultValue) { override fun find(key: String): T { - // Remember that just being a prefix isn't enough, it must match up to the end of a segment. + // Remember that just being a prefix isn't enough; it must match up to the end of a segment. return if (key.startsWith(this.key) && (key.length == this.key.length || key[this.key.length] == separator) ) { @@ -118,7 +118,7 @@ private class SingletonTrie( } /** - * General purpose implementation using a custom binary search to reduce + * General-purpose implementation using a custom binary search to reduce * repeated re-comparing of keys. * * Nothing in or called by the "find" method is allowed to allocate any memory. @@ -218,7 +218,7 @@ private class SortedTrie( * Determines if a given candidate value `p` is the parent of a key `k`. * * We know that `p < k` (lexicographically) and (importantly) `p != k`. - * We also know that `len` is common prefix length. + * We also know that `len` is the common prefix length. * * Thus, either: * - The common prefix is a strict prefix of k (i.e. `k.length() > len`). @@ -246,8 +246,8 @@ private class SortedTrie( * * By allowing a known existing lower bound for the prefix length to be provided, this method * can skip re-comparing the beginning of values repeatedly when used in a binary search. - * The given lower bound value is expected to be the result of previous calls this function (or - * `0`). + * The given lower bound value is expected to be the result of previous calls to this + * function (or `0`). * * @param lhs first value to compare. * @param rhs second value to compare. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/context/Tags.kt b/logging/src/commonMain/kotlin/io/spine/logging/context/Tags.kt index b7a7ece2a..6fdb0e513 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/context/Tags.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/context/Tags.kt @@ -35,7 +35,7 @@ import io.spine.logging.util.Checks.checkMetadataIdentifier private data class SimpleEntry(override val key: K, override val value: V) : Map.Entry /** - * Immutable tags which can be attached to log statements via + * Immutable tags that can be attached to log statements via * platform-specific injection mechanisms. * * A tag is either a "simple" tag, added via [Builder.addTag] or a tag with a @@ -46,7 +46,7 @@ private data class SimpleEntry(override val key: K, override val value: V) * `Tags` instance. In other words it never matters in which order two `Tags` instances * are merged. * - * When tags are merged, the result is the union of the values. This is easier to explain When + * When tags are merged, the result is the union of the values. This is easier to explain when * thinking of tags as a `Map>`, where "merging" means taking the union of * the `Set` associated with the tag name. In particular, for a given tag name: * @@ -200,7 +200,7 @@ public class Tags private constructor(private val map: LightweightTagMap) { } // Safe, even for a reused builder, because we never care // about the original value order. - // We/ could deduplicate here to guard against pathological use, + // We could deduplicate here to guard against pathological use, // but it should never matter. keyValuePairs.sort() return Tags(LightweightTagMap(keyValuePairs)) @@ -247,7 +247,7 @@ public class Tags private constructor(private val map: LightweightTagMap) { map.hashCode().inv() /** - * Returns human-readable representation of the tags. + * Returns a human-readable representation of the tags. * * This is not a stable representation and may change over time. * If you need to format tags reliably for logging, you should not @@ -281,7 +281,7 @@ private data class KeyValuePair( * Allowed types of tag values. * * This ensures that tag values have well-known semantics and can - * always be formatted in a clearly and unambiguously. + * always be formatted clearly and unambiguously. * * The ordering of elements in this enum should not change as it defines the sort order between * values of different types. New elements need not be added at the end though. @@ -464,7 +464,7 @@ private class LightweightTagMap : AbstractMap> { // ---- Helpers for making a tag map from the builder. ---- /** - * Count the unique keys for a sorted list of key-value pairs. + * Counts the unique keys for a sorted list of key-value pairs. */ private fun countMapEntries(sortedPairs: List): Int { var key: String? = null @@ -526,7 +526,7 @@ private class LightweightTagMap : AbstractMap> { ): Int { // Merge values starting at the first safe offset after the largest possible number of // entries. We may need to copy elements later to remove any gap due to duplicate keys. - // If the values are copied down we must remember to re-adjust the offsets as well. + // If the values are copied down, we must remember to re-adjust the offsets as well. var valueStart = maxEntryCount // The first offset is the start of the first values segment. offsets[0] = valueStart @@ -667,7 +667,7 @@ private class LightweightTagMap : AbstractMap> { } /** - * Resize the value array if necessary. + * Resizes the value array if necessary. */ private fun maybeResizeElementArray(array: Array, bestLength: Int): Array { return if (mustResize(array.size, bestLength)) { @@ -678,7 +678,7 @@ private class LightweightTagMap : AbstractMap> { } /** - * Resize the value array if necessary (separate since int[] and Object[] are not compatible). + * Resizes the value array if necessary (separate since int[] and Object[] are not compatible). */ private fun maybeResizeOffsetsArray(offsets: IntArray): IntArray { // Remember we must account for the extra final offset (the end of the final segment). @@ -691,7 +691,7 @@ private class LightweightTagMap : AbstractMap> { } /** - * Common logic to decide if we're wasting too much off an array and need to "right size" it. + * Common logic to decide if we're wasting too much of an array and need to "right size" it. * * @return `true` if more than 10% wasted in a non-trivial sized array. */ @@ -726,7 +726,7 @@ private class LightweightTagMap : AbstractMap> { get() = entrySet /** - * A lightweight set based on an range in an array. + * A lightweight set based on a range in an array. * * This assumes (but does not enforce) that the elements in the array are * ordered according to the comparator. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/util/Checks.kt b/logging/src/commonMain/kotlin/io/spine/logging/util/Checks.kt index a4921e963..2e4cd85c9 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/util/Checks.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/util/Checks.kt @@ -29,7 +29,7 @@ package io.spine.logging.util import com.google.errorprone.annotations.CanIgnoreReturnValue /** - * Preconditions for simple often used checks. + * Preconditions for simple often-used checks. * * @see * Original Java code for historical context. diff --git a/logging/src/commonMain/kotlin/io/spine/logging/util/RecursionDepth.kt b/logging/src/commonMain/kotlin/io/spine/logging/util/RecursionDepth.kt index 18b03b161..3abfed7bd 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/util/RecursionDepth.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/util/RecursionDepth.kt @@ -40,7 +40,7 @@ import kotlin.coroutines.EmptyCoroutineContext * of the core logging internals. * * API Note: This class is an internal detail and must not be used outside the core of - * the Logging library. Backends which need to know the recursion depth should call + * the Logging library. Backends that need to know the recursion depth should call * `io.spine.logging.backend.Platform.getCurrentRecursionDepth()`. */ public class RecursionDepth private constructor() : CoroutineContext.Element, AutoCloseable { @@ -50,7 +50,7 @@ public class RecursionDepth private constructor() : CoroutineContext.Element, Au private var value: Int = 0 /** - * Do not call this method directly, use `Platform.getCurrentRecursionDepth()`. + * Do not call this method directly; use `Platform.getCurrentRecursionDepth()`. */ @Internal public fun getValue(): Int = value @@ -67,8 +67,6 @@ public class RecursionDepth private constructor() : CoroutineContext.Element, Au error("Mismatched calls to `RecursionDepth`.") } - - /** * The `CoroutineContext.Key` for managing [RecursionDepth] in a `CoroutineContext`. */ @@ -87,14 +85,14 @@ public class RecursionDepth private constructor() : CoroutineContext.Element, Au } /** - * Do not call this method directly, use `Platform.getCurrentRecursionDepth()`. + * Do not call this method directly; use `Platform.getCurrentRecursionDepth()`. */ @Internal @JvmStatic public fun getCurrentDepth(): Int = CurrentContext.get()[Key]?.value ?: 0 /** - * Do not call this method directly, use `Platform.getCurrentRecursionDepth()`. + * Do not call this method directly; use `Platform.getCurrentRecursionDepth()`. */ @Internal @JvmStatic diff --git a/logging/src/commonTest/kotlin/io/spine/logging/AbstractLoggerSpec.kt b/logging/src/commonTest/kotlin/io/spine/logging/AbstractLoggerSpec.kt index c00e72972..b9f4e3dde 100644 --- a/logging/src/commonTest/kotlin/io/spine/logging/AbstractLoggerSpec.kt +++ b/logging/src/commonTest/kotlin/io/spine/logging/AbstractLoggerSpec.kt @@ -71,7 +71,7 @@ internal class AbstractLoggerSpec { /** * Matches ISO 8601 date/time format. * - * [DOT_MATCHES_ALL] option makes `.*` match line terminators as well. + * The [DOT_MATCHES_ALL] option makes `.*` match line terminators as well. * * @see SimpleDateFormat */ @@ -97,8 +97,8 @@ internal class AbstractLoggerSpec { } /** - * Tests a worst case scenario whereby object's `toString()` method throws - * an exception, which itself throws an exception on `toString()` call. + * Tests a worst-case scenario whereby an object's `toString()` method throws + * an exception, which itself throws an exception on a `toString()` call. */ @Test fun `report nested exceptions`() { diff --git a/logging/src/commonTest/kotlin/io/spine/logging/backend/KeyValueFormatterSpec.kt b/logging/src/commonTest/kotlin/io/spine/logging/backend/KeyValueFormatterSpec.kt index b956042a3..2be57056f 100644 --- a/logging/src/commonTest/kotlin/io/spine/logging/backend/KeyValueFormatterSpec.kt +++ b/logging/src/commonTest/kotlin/io/spine/logging/backend/KeyValueFormatterSpec.kt @@ -100,7 +100,7 @@ internal class KeyValueFormatterSpec { format("x", null) shouldBe "x=true" // Enums are currently quoted, but wouldn't need to be if the `name()` - // rather than `toString()` was used to generate to value. + // rather than `toString()` was used to generate the value. format("x", Foo.BAR) shouldBe "x=\"BAR\"" // Strings, characters and unknown types are quoted. @@ -127,7 +127,7 @@ internal class KeyValueFormatterSpec { /* Windows and Linux differently handle this replacement character. - So, the test relies on its HEX code instead of hard-coded literal. + So, the test relies on its HEX code instead of a hard-coded literal. */ val replacementChar = '\uFFFD' format("x", "Unsafe\u0000Chars") shouldBe "x=\"Unsafe" + replacementChar + "Chars\"" diff --git a/logging/src/commonTest/kotlin/io/spine/logging/backend/MetadataProcessorSpec.kt b/logging/src/commonTest/kotlin/io/spine/logging/backend/MetadataProcessorSpec.kt index 273802479..6d9b25950 100644 --- a/logging/src/commonTest/kotlin/io/spine/logging/backend/MetadataProcessorSpec.kt +++ b/logging/src/commonTest/kotlin/io/spine/logging/backend/MetadataProcessorSpec.kt @@ -145,7 +145,7 @@ internal abstract class MetadataProcessorSpec(private val factory: ProcessorFact @Test fun `withstand worst case performance scenario`() { // Since duplicated keys need to have their index looked up (linear scan), - // the worst case scenario for performance is 14 distinct keys, followed by + // the worst-case scenario for performance is 14 distinct keys, followed by // the same repeated key 14 times. This means (N/2)^2 key accesses. val scope = FakeMetadata() for (n in 0..13) { @@ -208,7 +208,7 @@ fun interface ProcessorFactory { } /** - * Processes the given [metadata], collecting the all formatted entries as strings. + * Processes the given [metadata], collecting all the formatted entries as strings. */ private fun entries(metadata: MetadataProcessor): List { val entries = arrayListOf() diff --git a/logging/src/commonTest/kotlin/io/spine/logging/backend/given/FakeLogData.kt b/logging/src/commonTest/kotlin/io/spine/logging/backend/given/FakeLogData.kt index d42b5d4df..9fc9c6dc1 100644 --- a/logging/src/commonTest/kotlin/io/spine/logging/backend/given/FakeLogData.kt +++ b/logging/src/commonTest/kotlin/io/spine/logging/backend/given/FakeLogData.kt @@ -35,7 +35,7 @@ import io.spine.logging.backend.LogData import io.spine.logging.given.FakeLogSite /** - * A mutable [LogData] fot testing backends and other log handling code. + * A mutable [LogData] for testing backends and other log handling code. * * @see Original Java code * for historical context. diff --git a/logging/src/commonTest/kotlin/io/spine/logging/backend/given/MetadataAssertions.kt b/logging/src/commonTest/kotlin/io/spine/logging/backend/given/MetadataAssertions.kt index 7fd880f5c..7902b96a0 100644 --- a/logging/src/commonTest/kotlin/io/spine/logging/backend/given/MetadataAssertions.kt +++ b/logging/src/commonTest/kotlin/io/spine/logging/backend/given/MetadataAssertions.kt @@ -81,7 +81,7 @@ internal infix fun Metadata.shouldNotContain(key: MetadataKey) { } /** - * Asserts that this [Metadata] has one or more values for the given [key] + * Asserts that this [Metadata] has one or more values for the given [key]. */ internal infix fun Metadata.shouldContain(key: MetadataKey) { findValue(key).shouldNotBeNull() diff --git a/logging/src/jvmMain/kotlin/io/spine/logging/LevelExts.kt b/logging/src/jvmMain/kotlin/io/spine/logging/LevelExts.kt index f8f378dda..7aa21f783 100644 --- a/logging/src/jvmMain/kotlin/io/spine/logging/LevelExts.kt +++ b/logging/src/jvmMain/kotlin/io/spine/logging/LevelExts.kt @@ -45,13 +45,13 @@ public fun Level.toJavaLogging(): JLevel = when (this) { } /** - * Opens the constructor of [JLevel] for creating converting instance. + * Opens the constructor of [JLevel] for creating a converted instance. */ @Suppress("serial") private class ConvertedLevel(level: Level) : JLevel(level.name, level.value) /** - * Converts Java logging level to [Level]. + * Converts a Java logging level to [Level]. * * @see [Level.toJavaLogging] */ diff --git a/logging/src/jvmMain/kotlin/io/spine/logging/LogSiteStackTrace.kt b/logging/src/jvmMain/kotlin/io/spine/logging/LogSiteStackTrace.kt index 8212cff35..988d13a51 100644 --- a/logging/src/jvmMain/kotlin/io/spine/logging/LogSiteStackTrace.kt +++ b/logging/src/jvmMain/kotlin/io/spine/logging/LogSiteStackTrace.kt @@ -29,7 +29,7 @@ package io.spine.logging import java.io.Serial /** - * A synthetic exception which can be attached to log statements when additional stack trace + * A synthetic exception that can be attached to log statements when additional stack trace * information is required in log files or via tools such as ECatcher. * * The name of this class may become relied upon implicitly by tools such as ECatcher. diff --git a/logging/src/jvmMain/kotlin/io/spine/logging/LoggingDomainClassValue.kt b/logging/src/jvmMain/kotlin/io/spine/logging/LoggingDomainClassValue.kt index 928ad7ff8..ad1571223 100644 --- a/logging/src/jvmMain/kotlin/io/spine/logging/LoggingDomainClassValue.kt +++ b/logging/src/jvmMain/kotlin/io/spine/logging/LoggingDomainClassValue.kt @@ -41,7 +41,7 @@ import kotlin.reflect.full.findAnnotation * 3. As a package annotation (of the type [JvmLoggingDomain]) for the package * of the given class, or "parent" packages from innermost to outermost. * - * When [JvmLoggingDomain] is found it is converted to [LoggingDomain] instance. + * When [JvmLoggingDomain] is found, it is converted to a [LoggingDomain] instance. */ internal object LoggingDomainClassValue: ClassValue() { @@ -75,7 +75,7 @@ internal object LoggingDomainClassValue: ClassValue() { private inline fun Class<*>.findWithNesting(): T? { // `kotlin.reflect.findAnnotation()` throws an error on an attempt - // to be called upon Java anonymous class. Anyway, the domain annotation + // to be called upon a Java anonymous class. Anyway, the domain annotation // can't be applied to local members. if (!isAnonymousClass) { kotlin.findAnnotation()?.let { @@ -95,6 +95,6 @@ private inline fun Class<*>.findWithNesting(): T? { } /** - * Converts this [JvmLoggingDomain] instance to [LoggingDomain] instance. + * Converts this [JvmLoggingDomain] instance to a [LoggingDomain] instance. */ private fun JvmLoggingDomain.toLoggingDomain(): LoggingDomain = LoggingDomain(value) diff --git a/logging/src/jvmTest/kotlin/io/spine/logging/CountingRateLimiterSpec.kt b/logging/src/jvmTest/kotlin/io/spine/logging/CountingRateLimiterSpec.kt index 6c5f4ece1..76d980451 100644 --- a/logging/src/jvmTest/kotlin/io/spine/logging/CountingRateLimiterSpec.kt +++ b/logging/src/jvmTest/kotlin/io/spine/logging/CountingRateLimiterSpec.kt @@ -52,7 +52,7 @@ internal class CountingRateLimiterSpec { @Test fun `return 'null' if the corresponding metadata key is not present`() { - // Not supplying `LOG_EVERY_N` metadata key ignores rate limiting by returning null. + // Not supplying the `LOG_EVERY_N` metadata key ignores rate limiting by returning null. val metadata = FakeMetadata() val logSite = FakeLogSite.unique() CountingRateLimiter.check(metadata, logSite).shouldBeNull() diff --git a/logging/src/jvmTest/kotlin/io/spine/logging/JvmLoggerSpec.kt b/logging/src/jvmTest/kotlin/io/spine/logging/JvmLoggerSpec.kt index ac8016657..f1b8f3302 100644 --- a/logging/src/jvmTest/kotlin/io/spine/logging/JvmLoggerSpec.kt +++ b/logging/src/jvmTest/kotlin/io/spine/logging/JvmLoggerSpec.kt @@ -298,7 +298,7 @@ internal class JvmLoggerSpec { var i = 1 (0..totalDuration step intervalMillis).forEach { _ -> // Count invocations eagerly: the message lambda is only - // evaluated for statements which actually log. + // evaluated for statements that actually log. val invocation = i++ logger.atInfo() .every(invocationLimit) @@ -370,7 +370,7 @@ internal class JvmLoggerSpec { val consoleOutput = tapConsole { for (millis in 0..totalDuration step intervalMillis) { // Count invocations eagerly: the message lambda is only - // evaluated for statements which actually log. + // evaluated for statements that actually log. val invocation = ++invoked logger.atInfo() .every(invocationLimit) diff --git a/platforms/jvm-default-platform/src/main/kotlin/io/spine/logging/backend/system/SystemClock.kt b/platforms/jvm-default-platform/src/main/kotlin/io/spine/logging/backend/system/SystemClock.kt index 261fdb3ed..c963e7ddb 100644 --- a/platforms/jvm-default-platform/src/main/kotlin/io/spine/logging/backend/system/SystemClock.kt +++ b/platforms/jvm-default-platform/src/main/kotlin/io/spine/logging/backend/system/SystemClock.kt @@ -30,7 +30,7 @@ import io.spine.logging.backend.Clock import java.util.concurrent.TimeUnit.MILLISECONDS /** - * Default millisecond precision clock. + * Default millisecond-precision clock. * * See class documentation in [Clock] for important implementation restrictions. * diff --git a/tests/fixtures/src/commonMain/kotlin/io/spine/logging/context/AbstractLogLevelMapTest.kt b/tests/fixtures/src/commonMain/kotlin/io/spine/logging/context/AbstractLogLevelMapTest.kt index 4bedb8f4e..a358883bd 100644 --- a/tests/fixtures/src/commonMain/kotlin/io/spine/logging/context/AbstractLogLevelMapTest.kt +++ b/tests/fixtures/src/commonMain/kotlin/io/spine/logging/context/AbstractLogLevelMapTest.kt @@ -52,7 +52,7 @@ public abstract class AbstractLogLevelMapTest( /** * Creates and populates the builder of a scoped logging context - * delegating the configuration of the builder to [configureBuilder] method. + * delegating the configuration of the builder to the [configureBuilder] method. */ private fun createContext(): ScopedLoggingContext.Builder { val map = LogLevelMap.builder().let { diff --git a/tests/fixtures/src/commonMain/kotlin/io/spine/logging/context/BaseLogLevelMapTest.kt b/tests/fixtures/src/commonMain/kotlin/io/spine/logging/context/BaseLogLevelMapTest.kt index 2797f42c5..69b44efd9 100644 --- a/tests/fixtures/src/commonMain/kotlin/io/spine/logging/context/BaseLogLevelMapTest.kt +++ b/tests/fixtures/src/commonMain/kotlin/io/spine/logging/context/BaseLogLevelMapTest.kt @@ -121,8 +121,8 @@ public abstract class BaseLogLevelMapTest: AbstractLogLevelMapTest() { message shouldContain "From fixture 1." } - // `L2Direct` is the class which is directly in the package mentioned in the map. - // The class has its own logging level. Logging at lower level should not occur. + // `L2Direct` is the class that is directly in the package mentioned in the map. + // The class has its own logging level. Logging at a lower level should not occur. val records2 = recorders[2].records val samePackageClass = fixtures[2] samePackageClass.logAt(TRACE, "Fixture 2 at TRACE.") @@ -138,7 +138,7 @@ public abstract class BaseLogLevelMapTest: AbstractLogLevelMapTest() { } /** - * The fixture which is not mentioned in log level map, and package of which + * The fixture that is not mentioned in the log level map, and the package of which * is outside the package hierarchy configured in the map. * * The class must be public so that Kotlin Reflection is able to call its constructor. diff --git a/tests/jvm-jul-backend-std-context/build.gradle.kts b/tests/jvm-jul-backend-std-context/build.gradle.kts index 160c33946..8f73d80ad 100644 --- a/tests/jvm-jul-backend-std-context/build.gradle.kts +++ b/tests/jvm-jul-backend-std-context/build.gradle.kts @@ -38,7 +38,7 @@ dependencies { * The logging `Platform` discovers backend and context implementations * automatically via Java's `ServiceLoader`. A user doesn't need to * interact with “hard” classes from these dependencies. So, they are - * usually added to [runtimeOnly] configuration. + * usually added to the [runtimeOnly] configuration. * * But for this test, it is important to make sure that the actually * discovered implementations match the test expectations. With a small diff --git a/tests/jvm-log4j2-backend-std-context/build.gradle.kts b/tests/jvm-log4j2-backend-std-context/build.gradle.kts index 1d0171998..b61a2b91a 100644 --- a/tests/jvm-log4j2-backend-std-context/build.gradle.kts +++ b/tests/jvm-log4j2-backend-std-context/build.gradle.kts @@ -62,12 +62,12 @@ dependencies { testImplementation(project(":fixtures")) /** - * Adds `log4j2` backend and the default context to the classpath. + * Adds the `log4j2` backend and the default context to the classpath. * * The logging `Platform` discovers backend and context implementations * automatically via Java's `ServiceLoader`. A user doesn't need to * interact with “hard” classes from these dependencies. So, they are - * usually added to [runtimeOnly] configuration. + * usually added to the [runtimeOnly] configuration. * * But for this test, it is important to make sure that the actually * discovered implementations match the test expectations. With a small diff --git a/tests/jvm-log4j2-backend-std-context/src/test/kotlin/LogLevelMapITest.kt b/tests/jvm-log4j2-backend-std-context/src/test/kotlin/LogLevelMapITest.kt index 877559f84..26e5199be 100644 --- a/tests/jvm-log4j2-backend-std-context/src/test/kotlin/LogLevelMapITest.kt +++ b/tests/jvm-log4j2-backend-std-context/src/test/kotlin/LogLevelMapITest.kt @@ -36,7 +36,7 @@ import org.junit.jupiter.api.Test /** * This is a non-abstract integration test of [LogLevelMap][io.spine.logging.context.LogLevelMap] - * executed in the project in which logging backend is based on Log4j2. + * executed in the project in which the logging backend is based on Log4j2. * * Please see `build.gradle.kts` of this module for the details. */ diff --git a/tests/smoke-test/README.md b/tests/smoke-test/README.md index f867ed544..b5fbab502 100644 --- a/tests/smoke-test/README.md +++ b/tests/smoke-test/README.md @@ -15,7 +15,7 @@ As of now, it is only applicable to JVM modules. It is because testing involves of JUL-based backend. This backend is default and allows easier interception of the logged text for further assertion. -Take a look at `AbstractLoggingSmokeTest` for usage example. +Take a look at `AbstractLoggingSmokeTest` for a usage example. Please note, the presence of `spine-logging` and `spine-logging-backend` is expected because the `jvm-module` script plugin, which configures Gradle, is applied to Spine JVM modules. diff --git a/tests/smoke-test/src/main/kotlin/io/spine/logging/AbstractLoggingSmokeTest.kt b/tests/smoke-test/src/main/kotlin/io/spine/logging/AbstractLoggingSmokeTest.kt index dcdc1ef7f..3075d68b0 100644 --- a/tests/smoke-test/src/main/kotlin/io/spine/logging/AbstractLoggingSmokeTest.kt +++ b/tests/smoke-test/src/main/kotlin/io/spine/logging/AbstractLoggingSmokeTest.kt @@ -32,7 +32,7 @@ import org.junit.jupiter.api.DisplayName import org.junit.jupiter.api.Test /** - * Tests the most fundamental functionality of `spine-logging` library. + * Tests the most fundamental functionality of the `spine-logging` library. * * This test suite is meant to be implemented in particular Spine modules * to verify the actual logging is happening in real conditions. @@ -46,7 +46,7 @@ import org.junit.jupiter.api.Test * class LoggingSmokeTest : AbstractLoggingSmokeTest() * ``` * - * Make sure, `spine-logging-smoke-test` library is on test classpath: + * Make sure, the `spine-logging-smoke-test` library is on the test classpath: * * ``` * testImplementation(Spine.Logging.smokeTest) @@ -55,7 +55,7 @@ import org.junit.jupiter.api.Test * ## Implementation details * * Tests assert the logged messages using [tapJavaLogging] util. This util writes - * a stream of the logged messages into a plain [String], which then makes possible + * a stream of the logged messages into a plain [String], which then makes it possible * to assert the result. * * The messages are captured by a custom Java Logging Handler. This approach is less diff --git a/tests/smoke-test/src/main/kotlin/io/spine/logging/MemoizingHandler.kt b/tests/smoke-test/src/main/kotlin/io/spine/logging/MemoizingHandler.kt index 6f4c3505c..203afe9c7 100644 --- a/tests/smoke-test/src/main/kotlin/io/spine/logging/MemoizingHandler.kt +++ b/tests/smoke-test/src/main/kotlin/io/spine/logging/MemoizingHandler.kt @@ -42,7 +42,7 @@ internal class MemoizingHandler( ) : StreamHandler(out, SimpleFormatter()) { /** - * Return the remembered messages concatenated to a single string. + * Returns the remembered messages concatenated to a single string. */ fun result(): String { flush() diff --git a/tests/smoke-test/src/main/kotlin/io/spine/logging/TapJavaLogging.kt b/tests/smoke-test/src/main/kotlin/io/spine/logging/TapJavaLogging.kt index 7f5458629..b98998d92 100644 --- a/tests/smoke-test/src/main/kotlin/io/spine/logging/TapJavaLogging.kt +++ b/tests/smoke-test/src/main/kotlin/io/spine/logging/TapJavaLogging.kt @@ -30,7 +30,7 @@ import java.util.logging.Logger /** * Executes the given [action] and returns the text logged with - * [Java Logging][Logger] backend. + * the [Java Logging][Logger] backend. */ internal fun tapJavaLogging(action: () -> Unit): String { val memoizingHandler = MemoizingHandler() diff --git a/version.gradle.kts b/version.gradle.kts index 1899d8ed3..c3bd036c9 100644 --- a/version.gradle.kts +++ b/version.gradle.kts @@ -24,4 +24,4 @@ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -extra.set("versionToPublish", "2.0.0-SNAPSHOT.422") +extra.set("versionToPublish", "2.0.0-SNAPSHOT.423")