Improve phrasing in docstrings

Author: hermannm

README.md

@@ -203,11 +203,11 @@ For more configuration options, see:
 
 ### Performance
 
-- All the methods on `Logger` take a lambda argument to build the log, which is only called if the
-  log level is enabled - so you only pay for message string concatenation and log field
-  serialization if it's actually logged.
+- All the methods on `Logger` take a lambda to build the log, which is only called if the log level
+  is enabled - so you only pay for message string concatenation and log field serialization if it's
+  actually logged.
 - `Logger`'s methods are also `inline`, so we avoid the cost of allocating a function object for the
-  lambda argument.
+  lambda parameter.
 - Elsewhere in the library, we use inline value classes when wrapping SLF4J/Logback APIs, to get as
   close as possible to a zero-cost abstraction.
 

src/commonMain/kotlin/dev/hermannm/devlog/ExceptionWithLogFields.kt

@@ -68,7 +68,7 @@ package dev.hermannm.devlog
  *       exception
  * - `(message: String?, vararg logFields: LogField, cause: Throwable?)`
  *     - Takes log fields as varargs, so you don't have to wrap them in a list
- *     - To pass `cause`, use a named parameter
+ *     - To pass `cause`, use a named argument
  * - `(logFields: List<LogField>, cause: Throwable?)`
  *     - Defaults `message` to `cause.message`. This lets you:
  *         - Wrap a cause exception with log fields, and use the cause exception's message

src/commonMain/kotlin/dev/hermannm/devlog/LogBuilder.kt

@@ -9,9 +9,9 @@ import kotlinx.serialization.SerializationStrategy
  * Class used in the logging methods on [Logger], allowing you to add structured key-value data to
  * the log by calling the [field] and [rawJsonField] methods.
  *
- * This class is given as a receiver to the lambda arguments on `Logger`'s methods, which lets you
- * call its methods directly in the scope of that lambda. This is a common technique for creating
- * _type-safe builders_ in Kotlin (see the
+ * This class is provided as a receiver for the `buildLog` lambda parameter on `Logger`'s methods,
+ * which lets you call its methods directly in the scope of the lambda. This is a common pattern for
+ * creating _type-safe builders_ in Kotlin (see the
  * [Kotlin docs](https://kotlinlang.org/docs/lambdas.html#function-literals-with-receiver) for more
  * on this).
  *
@@ -49,7 +49,7 @@ internal constructor(
    *
    * If you want to specify the serializer for the value explicitly, you can call the overload of
    * this method that takes a [SerializationStrategy][kotlinx.serialization.SerializationStrategy]
-   * as a third argument. That is also useful for cases where you can't call this method with a
+   * as a third parameter. That is also useful for cases where you can't call this method with a
    * reified type parameter.
    *
    * If you have a value that is already serialized, you should use [rawJsonField] instead.
@@ -125,7 +125,7 @@ internal constructor(
    *
    * If you want to specify the serializer for the value explicitly, you can call the overload of
    * this method that takes a [SerializationStrategy][kotlinx.serialization.SerializationStrategy]
-   * as a third argument. That is also useful for cases where you can't call this method with a
+   * as a third parameter. That is also useful for cases where you can't call this method with a
    * reified type parameter.
    *
    * If you have a value that is already serialized, you should use [rawJsonField] instead.

src/commonMain/kotlin/dev/hermannm/devlog/LogField.kt

@@ -156,7 +156,7 @@ internal open class JsonLogField(
  *
  * If you want to specify the serializer for the value explicitly, you can call the overload of this
  * function that takes a [SerializationStrategy][kotlinx.serialization.SerializationStrategy] as a
- * third argument. That is also useful for cases where you can't call this function with a reified
+ * third parameter. That is also useful for cases where you can't call this function with a reified
  * type parameter.
  *
  * If you have a value that is already serialized, you should use [rawJsonField] instead.
@@ -192,7 +192,7 @@ public inline fun <reified ValueT> field(key: String, value: ValueT): LogField {
  *
  * If you want to specify the serializer for the value explicitly, you can call the overload of this
  * function that takes a [SerializationStrategy][kotlinx.serialization.SerializationStrategy] as a
- * third argument. That is also useful for cases where you can't call this function with a reified
+ * third parameter. That is also useful for cases where you can't call this function with a reified
  * type parameter.
  *
  * If you have a value that is already serialized, you should use [rawJsonField] instead.

src/commonMain/kotlin/dev/hermannm/devlog/LogLevel.kt

@@ -99,14 +99,14 @@ public class LogLevel private constructor() {
    * will always be unreachable as long as we check all the levels defined on the companion object
    * here - since the constructor is private, there will be no other instances. To keep this logic
    * in one place, we provide this method to emulate a `when` expression on a log level:
-   * - We take a lambda argument for each log level, to ensure that all cases are covered
+   * - We take a lambda parameter for each log level, to ensure that all cases are covered
    *     - We make the method `inline`, so we don't pay a cost for the lambdas
    * - In the unreachable else branch, we throw an exception
    *
    * We may be able to use an enum/sealed class instead if
    * [this issue moves along](https://youtrack.jetbrains.com/issue/KT-38750/Support-declaration-site-nonexhaustiveness-for-enums-and-sealed-classes).
    */
-  @Suppress("LocalVariableName") // We want the argument names here to be the same as the constants
+  @Suppress("LocalVariableName") // We want the parameter names here to be the same as the constants
   internal inline fun <ReturnT> match(
       crossinline ERROR: () -> ReturnT,
       crossinline WARN: () -> ReturnT,

src/commonMain/kotlin/dev/hermannm/devlog/Logger.kt

@@ -12,9 +12,9 @@ import kotlin.reflect.KClass
  * enable/disable log levels for loggers based on their package names, or query for logs from a
  * specific class.
  *
- * The easiest way to construct a logger is by calling [getLogger] with an empty lambda argument.
- * This automatically gives the logger the name of its containing class (or file, if defined at the
- * top level).
+ * The easiest way to construct a logger is by calling [getLogger] with zero arguments. This
+ * automatically gives the logger the name of its containing class (or file, if defined at the top
+ * level). See the "Implementation" section on [getLogger]'s docstring for how this works.
  *
  * ```
  * // In file Example.kt
@@ -494,7 +494,7 @@ public expect inline fun getLogger(): Logger
  * The logger name is included in the log output, and can be used to enable/disable log levels for
  * loggers based on their package names, or query for logs from a specific class.
  *
- * In most cases, you should prefer the zero-argument `getLogger()` overload, to automatically get
+ * In most cases, you should prefer the zero-parameter `getLogger()` overload, to automatically get
  * the name of the containing class (or file). But if you want more control over which class to use
  * for the logger name, you can use this overload.
  *
@@ -526,14 +526,16 @@ public expect fun getLogger(forClass: KClass<*>): Logger
  * loggers based on their package names, or query for logs from a specific class. Because of this,
  * the name given here should follow fully qualified class name format, like `com.example.Example`.
  *
- * To set the name automatically from the containing class/file, you can use the zero-argument
+ * To set the name automatically from the containing class/file, you can use the zero-parameter
  * `getLogger()` overload instead.
  *
  * ### Example
  *
  * ```
  * private val log = getLogger(name = "com.example.Example")
  * ```
+ *
+ * @param name Should follow fully qualified class name format, like `com.example.Example`.
  */
 public expect fun getLogger(name: String): Logger