fix: clarifications and language polishing

Author: zamulla

libraries/tools/kotlin-compose-compiler/src/common/kotlin/org/jetbrains/kotlin/compose/compiler/gradle/ComposeCompilerGradlePluginExtension.kt

@@ -29,7 +29,7 @@ import javax.inject.Inject
 /**
  * Provides DSL to configure Compose compiler plugin options.
  *
- * It is available in the build scripts under "composeCompiler" name:
+ * It is available in the build scripts as the `composeCompiler {}` block:
  * ```
  * composeCompiler {
  *    ...
@@ -38,7 +38,7 @@ import javax.inject.Inject
  */
 abstract class ComposeCompilerGradlePluginExtension @Inject internal constructor(objectFactory: ObjectFactory) {
     /**
-     * Generate function key meta classes with annotations indicating the functions and their group keys.
+     * Generate function key metaclasses with annotations indicating the functions and their group keys.
      *
      * Generally used for tooling.
      */
@@ -48,15 +48,15 @@ abstract class ComposeCompilerGradlePluginExtension @Inject internal constructor
      * Include source information in generated code.
      *
      * Records source information that can be used for tooling to determine the source location of the corresponding composable function.
-     * By default, this function is declared as having no side-effects. It is safe for code shrinking tools (such as R8 or ProGuard) to
+     * By default, this function is declared as having no side effects. It is safe for code shrinking tools (such as R8 or ProGuard) to
      * remove it. This option does NOT impact the presence of symbols or line information normally added by the Kotlin compiler; this option
-     * controls additional source information added by the Compose Compiler.
+     * controls only additional source information added by the Compose Compiler.
      */
     val includeSourceInformation: Property<Boolean> = objectFactory.property(Boolean::class.java).convention(false)
 
     /**
-     * Save compose build metrics to this folder.
-     * When specified, the Compose Compiler will dump metrics about the current module which can be useful when manually optimizing your
+     * Save Compose build metrics to this folder.
+     * When specified, the Compose compiler will dump metrics about the current module, which can be useful when manually optimizing your
      * application's runtime performance. The module.json will include the statistics about processed composables and classes, including
      * number of stable classes/parameters, skippable functions, etc.
      *
@@ -67,10 +67,10 @@ abstract class ComposeCompilerGradlePluginExtension @Inject internal constructor
     abstract val metricsDestination: DirectoryProperty
 
     /**
-     * Save compose build reports to this folder.
+     * Save Compose build reports to this folder.
      *
-     * When specified, the Compose Compiler will dump reports about the compilation which can be useful when manually optimizing
-     * your application's runtime performance. These reports include information about which of your composable functions are skippable,
+     * When specified, the Compose compiler will dump reports about the compilation, which can be useful when manually optimizing
+     * your application's runtime performance. These reports include information on which of your composable functions are skippable,
      * which are restartable, which are readonly, etc.
      *
      * For more information, see these links:
@@ -134,7 +134,7 @@ abstract class ComposeCompilerGradlePluginExtension @Inject internal constructor
     abstract val stabilityConfigurationFile: RegularFileProperty
 
     /**
-     * List of paths to the stability configuration file.
+     * List of paths to stability configuration files.
      *
      * For more information, see this link:
      *  - [AndroidX stability configuration file](https://developer.android.com/develop/ui/compose/performance/stability/fix#configuration-file)
@@ -154,7 +154,7 @@ abstract class ComposeCompilerGradlePluginExtension @Inject internal constructor
     /**
      * Include composition trace markers in the generated code.
      *
-     * When `true`, this flag tells the compose compiler to inject additional tracing information into the bytecode, which allows showing
+     * When `true`, this flag tells the Compose compiler to inject additional tracing information into the bytecode, which allows showing
      * composable functions in the Android Studio system trace profiler.
      *
      * For more information, see this link:
@@ -163,7 +163,7 @@ abstract class ComposeCompilerGradlePluginExtension @Inject internal constructor
     val includeTraceMarkers: Property<Boolean> = objectFactory.property(Boolean::class.java).convention(true)
 
     /**
-     * A set of Kotlin platforms to which the Compose plugin will be applied.
+     * A set of Kotlin platforms to which the Compose compiler plugin will be applied.
      *
      * By default, all Kotlin platforms are enabled.
      *
@@ -192,9 +192,9 @@ abstract class ComposeCompilerGradlePluginExtension @Inject internal constructor
         .convention(KotlinPlatformType.values().asIterable())
 
     /**
-     * A set of feature flags to enable. A feature requires a feature flags when it is in the process of becoming the default
-     * behavior of the Compose compiler. Features in this set will eventually be removed and disabling will no longer be
-     * supported. See [ComposeFeatureFlag] for the list of features currently recognized by the plugin.
+     * A set of feature flags to enable. A feature requires a feature flag when it is in the process of becoming the default
+     * behavior of the Compose compiler. Features in this set will eventually be removed and integrated as baseline behavior;
+     * after that, disabling them will no longer be supported. See [ComposeFeatureFlag] for the list of features currently recognized by the plugin.
      *
      * @see ComposeFeatureFlag
      */

libraries/tools/kotlin-compose-compiler/src/common/kotlin/org/jetbrains/kotlin/compose/compiler/gradle/ComposeFeatureFlags.kt

@@ -77,7 +77,7 @@ sealed interface ComposeFeatureFlag : Named, Serializable {
          * Enable strong skipping.
          *
          * Strong Skipping is a mode that improves the runtime performance of your application by skipping unnecessary
-         * invocations of composable functions for which the parameters have not changed. In particular, when enabled, Composable functions
+         * invocations of composable functions for which the parameters have not changed. In particular, when enabled, composable functions
          * with unstable parameters become skippable and lambdas with unstable captures will be memoized.
          *
          * For more information, see this link:
@@ -116,10 +116,11 @@ sealed interface ComposeFeatureFlag : Named, Serializable {
          * Removing groups around non-skipping composable function is an experimental mode which improves the runtime performance of your
          * application by skipping unnecessary groups around composable functions which do not skip (and thus do not require a group). This
          * optimization will remove the groups around functions that are not skippable such as explicitly marked as
-         * `@NonSkippableComposable` and functions that are implicitly not skippable such inline functions and functions that return a
-         * non-Unit value such as remember.
+         * `@NonSkippableComposable` and functions that are implicitly not skippable, such as inline functions and functions that return a
+         * non-`Unit` value such as `remember`.
          *
-         * This feature is still considered experimental and is thus disabled by default. To enable,
+         * This feature is still considered experimental and is thus disabled by default. To enable, add this line
+         * to the `composeCompiler {}` block:
          * ```
          * composeCompiler {
          *     featureFlags = setOf(ComposeFeatureFlag.OptimizeNonSkippingGroups)
@@ -130,13 +131,14 @@ sealed interface ComposeFeatureFlag : Named, Serializable {
         val OptimizeNonSkippingGroups: ComposeFeatureFlag = Enabled(Feature.OptimizeNonSkippingGroups)
 
         /**
-         * Change the code generation of composable function to enable pausing when part of pausable composition.
+         * Change the code generation of composable functions to enable pausing when a composable function is part of a pausable composition.
          *
          * Pausable composition is an experimental runtime feature. Experiments with this feature can be run by enabling this feature flag
          * and using a runtime version that supports pausable composition. If the runtime used does not support pausable composition, no
          * change is made to the code generation.
          *
-         * This feature is still considered experimental and is thus disabled by default. It can be enabled by adding,
+         * This feature is still considered experimental and is thus disabled by default. To enable, add this line
+         * to the `composeCompiler {}` block:
          *```
          * composeCompiler {
          *   featureFlag = setOf(ComposeFeatureFlag.PausableComposition)