diff --git a/buildSrc/src/main/kotlin/io/spine/gradle/Runtime.kt b/buildSrc/src/main/kotlin/io/spine/gradle/Runtime.kt index c5b5f5464..0e67c108a 100644 --- a/buildSrc/src/main/kotlin/io/spine/gradle/Runtime.kt +++ b/buildSrc/src/main/kotlin/io/spine/gradle/Runtime.kt @@ -46,15 +46,15 @@ private const val ABOUT = "" class Cli(private val workingFolder: File) { /** - * Executes the given terminal command and retrieves the command output. + * Executes the given terminal command and returns its output. * - *

{@link Runtime#exec(String[], String[], File) Executes} the given {@code String} array as - * a CLI command. If the execution is successful, returns the command output. Throws - * an {@link IllegalStateException} otherwise. + *

Internally calls {@link Runtime#exec(String[], String[], File)} to run the given + * {@code String} array as a CLI command. If the execution is successful, the command output + * is returned; otherwise an {@link IllegalStateException} is thrown. * * @param command the command to execute * @return the command line output - * @throws IllegalStateException upon an execution error + * @throws IllegalStateException if the execution fails */ fun execute(vararg command: String): String { val outWriter = StringWriter() @@ -87,7 +87,7 @@ class Cli(private val workingFolder: File) { /** * Asynchronously reads all lines from this [InputStream] and appends them - * to the passed [StringWriter]. + * to the given [StringWriter]. */ fun InputStream.pourTo(dest: StringWriter) { Thread { diff --git a/buildSrc/src/main/kotlin/io/spine/gradle/report/pom/PomXmlWriter.kt b/buildSrc/src/main/kotlin/io/spine/gradle/report/pom/PomXmlWriter.kt index 53122196a..21394a7f5 100644 --- a/buildSrc/src/main/kotlin/io/spine/gradle/report/pom/PomXmlWriter.kt +++ b/buildSrc/src/main/kotlin/io/spine/gradle/report/pom/PomXmlWriter.kt @@ -35,9 +35,9 @@ import java.io.StringWriter /** * Writes the dependencies of a Gradle project and its subprojects as a `pom.xml` file. * - * The resulting file is not usable for `maven` build tasks, but serves rather as a description - * of the first-level dependencies for each project/subproject. Their transitive dependencies - * are not included into the result. + * The resulting file is not usable for `maven` build tasks but serves as a description + * of the first-level dependencies for each project or subproject. Their transitive dependencies + * are not included in the result. */ internal class PomXmlWriter internal constructor( @@ -48,10 +48,10 @@ internal constructor( * Writes the `pom.xml` file containing dependencies of this project * and its subprojects to the specified location. * - *

If a file with the specified location exists, its contents will be substituted + *

If a file with the specified location exists, its contents are replaced * with a new `pom.xml`. * - * @param file a file to write `pom.xml` contents to + * @param file a file to write the `pom.xml` contents to */ fun writeTo(file: File) { val fileWriter = FileWriter(file) @@ -74,7 +74,7 @@ internal constructor( /** * Obtains a string that contains project dependencies as XML. * - *

Obtained string also contains a closing project tag. + *

The returned string also contains the closing project tag. */ private fun projectDependencies(): String { val destination = StringWriter() diff --git a/logging/src/commonMain/kotlin/io/spine/logging/LoggingFactory.kt b/logging/src/commonMain/kotlin/io/spine/logging/LoggingFactory.kt index 6fa1ca3f1..5bf9ebc0b 100644 --- a/logging/src/commonMain/kotlin/io/spine/logging/LoggingFactory.kt +++ b/logging/src/commonMain/kotlin/io/spine/logging/LoggingFactory.kt @@ -36,14 +36,14 @@ public expect object LoggingFactory { /** * Obtains the logger for the enclosing class. * - * Implementation should provide the same logger instance for the same class. + * The implementation should return the same logger instance for the same class. */ public fun > forEnclosingClass(): Logger /** * Obtains the logger for the given class. * - * Implementation should provide the same logger instance for the same class. + * The implementation should return the same logger instance for the same class. */ public fun > loggerFor(cls: KClass<*>): Logger @@ -56,8 +56,8 @@ public expect object LoggingFactory { /** * Creates a key for a single piece of metadata. If metadata is set more than once - * using this key for the same log statement, the last set value will be the one used, and - * other values will be ignored (although callers should never rely on this behavior). + * with this key for the same log statement, only the last value is used and + * other values are ignored (although callers should never rely on this behavior). * * Key instances behave like singletons, and two key instances with the same label will still * be considered distinct. The recommended approach is to always assign [MetadataKey] @@ -69,7 +69,7 @@ public expect object LoggingFactory { /** * Creates a key for a repeated piece of metadata. If metadata is added more than once - * using this key for a log statement, all values will be retained as key/value pairs in + * with this key for a log statement, all values are retained as key/value pairs in * the order they were added. * * Key instances behave like singletons, and two key instances with the same label will still diff --git a/platforms/jvm-default-platform/src/main/java/io/spine/logging/backend/system/package-info.java b/platforms/jvm-default-platform/src/main/java/io/spine/logging/backend/system/package-info.java index e88808768..aa5d027eb 100644 --- a/platforms/jvm-default-platform/src/main/java/io/spine/logging/backend/system/package-info.java +++ b/platforms/jvm-default-platform/src/main/java/io/spine/logging/backend/system/package-info.java @@ -28,9 +28,8 @@ * Contains the default logger platform implementation for a server-side * Java environment. * - *

Although, {@code system} is not the best name for this package. - * The better option is {@code default}, but it is reserved by Java - * and cannot be used here. + *

Although {@code system} is not the best name for this package, + * the better option, {@code default}, is reserved by Java and cannot be used here. * * @see Original Java code of Google Flogger */