[ABI Validation] Fix grammar and style in KDoc for ABI validation API
diff --git a/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/AbiValidationToolchain.kt b/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/AbiValidationToolchain.kt index 9514ad7..7ea97dc 100644 --- a/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/AbiValidationToolchain.kt +++ b/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/AbiValidationToolchain.kt
@@ -29,7 +29,7 @@ /** * Prints an ABI dump for JVM from [inputFiles] into the specified [appendable]. * - * @param inputFiles Paths to the files used to extract its ABI. The files can be class-files or jar-files. Directories are not supported. + * @param inputFiles Paths to the files used to extract its ABI. The files can be class files or JAR files. Directories are not supported. * * @since 2.4.0 */ @@ -52,7 +52,7 @@ /** * Compares two files line-by-line. * - * If files are equal, nothing is written to [diff]. + * If the files are the same, nothing is written to the [diff]. * * @since 2.4.0 */ @@ -79,9 +79,9 @@ /** * Prints an ABI dump for JVM from [inputFiles] into the specified [appendable] with options configured by [builderAction]. - * It is possible to pass class-files or jar files in [inputFiles]. + * It is possible to pass class files or JAR files in [inputFiles]. * - * To control which declarations are passed to the dump, the option [DumpJvmAbiToStringOperation.PATTERN_FILTERS] could be used. By default, no filters will be applied. + * To control which declarations are passed to the dump, the option [DumpJvmAbiToStringOperation.PATTERN_FILTERS] can be used. By default, no filters are applied. * * @since 2.4.0 */ @@ -99,18 +99,18 @@ } /** - * Prints an ABI dump for klib targets from [klibs] into the specified [appendable] with options configured by [builderAction]. + * Prints an ABI dump for klib targets from [klibs] into the specified [appendable] with options configured by [builderAction]. * Compressed and unpacked klibs are supported. * - * If option [DumpKlibAbiToStringOperation.TARGETS_TO_INFER] is specified and not empty, for the specified targets the ABI will be inferred from the option [DumpKlibAbiToStringOperation.REFERENCE_DUMP_FILE]. + * If the [DumpKlibAbiToStringOperation.TARGETS_TO_INFER] option is specified and not empty, for the specified targets the ABI is inferred from the [DumpKlibAbiToStringOperation.REFERENCE_DUMP_FILE] option. * The inference works as follows: - * - for each target from [DumpKlibAbiToStringOperation.TARGETS_TO_INFER], the ABI is inferred from the [DumpKlibAbiToStringOperation.REFERENCE_DUMP_FILE], if it exists, not empty, and this target is present in it - * - all the non-inferred targets that belong to the group that this target belongs to are found. Then all declarations are added that are present in all of them. + * - For each target from [DumpKlibAbiToStringOperation.TARGETS_TO_INFER], the ABI is inferred from the [DumpKlibAbiToStringOperation.REFERENCE_DUMP_FILE], if it exists, is not empty, and this target is present in it. + * - If all the non-inferred targets that belong to the group that this target belongs to are found, all the declarations are added that are present in all of them. * - * The inference is used in cases where the host compiler cannot compile some targets, but there is a need to build an ABI dump, - * even if with some inaccuracies. + * Inference is used in cases where the host compiler can't compile some targets, but there is a need to build an ABI dump, + * even if it has some inaccuracies. * - * To control which declarations are passed to the dump, the option [DumpKlibAbiToStringOperation.PATTERN_FILTERS] could be used. By default, no filters will be applied. + * To control which declarations are passed to the dump, the [DumpKlibAbiToStringOperation.PATTERN_FILTERS] option can be used. By default, no filters are applied. * * @since 2.4.0 */ @@ -130,7 +130,7 @@ /** * Compares two files line-by-line. * - * If files are equal, nothing is written to [diff]. + * If the files are the same, nothing is written to the [diff]. * * @since 2.4.0 */
diff --git a/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/AbiValidationTypes.kt b/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/AbiValidationTypes.kt index ca47364..7ca14e8 100644 --- a/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/AbiValidationTypes.kt +++ b/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/AbiValidationTypes.kt
@@ -10,16 +10,16 @@ import java.io.Serializable /** - * Set of filtering rules that restrict ABI declarations included in a dump. + * A set of filtering rules that restrict ABI declarations included in a dump. * - * The rules combine inclusion and exclusion of declarations. + * The rules combine inclusions and exclusions of declarations. * Each filter can be written as a filter for the class name (see [INCLUDE_NAMED] or [EXCLUDE_NAMED]), or an annotation filter (see [INCLUDE_ANNOTATED_WITH] or [EXCLUDE_ANNOTATED_WITH]). * * In order for a declaration (class, field, property, or function) to get into the dump, it must pass the inclusion **and** exclusion filters. * - * A declaration passes the exclusion filters if it does not match any class names (see [EXCLUDE_NAMED]) or annotation (see [EXCLUDE_ANNOTATED_WITH]) filter rules. + * A declaration passes the exclusion filters if it does not match any class names (see [EXCLUDE_NAMED]) or annotation (see [EXCLUDE_ANNOTATED_WITH]) filter rules. * - * A declaration passes the inclusion filters if there are no inclusion rules, or it matches any inclusion rule, or at least one of its members (actual for class declaration) matches any inclusion rule. + * A declaration passes the inclusion filters if there are no inclusion rules, or it matches any inclusion rule, or at least one of its members (relevant for class declaration) matches any inclusion rule. * * @since 2.4.0 */ @@ -35,7 +35,7 @@ public interface Builder { /** - * Get the value for option specified by [key] if it was previously [set] or if it has a default value. + * Gets the value for the option specified by [key] if it was previously [set] or if it has a default value. * * @return the previously set value for an option * @throws IllegalStateException if the option was not set and has no default value @@ -45,7 +45,7 @@ public operator fun <V> get(key: Option<V>): V /** - * Set the [value] for option specified by [key], overriding any previous value for that option. + * Sets the [value] for the option specified by [key], overriding any previous value for that option. * * @since 2.4.0 */ @@ -71,7 +71,7 @@ public class Option<V> internal constructor(id: String) : BaseOption<V>(id) /** - * Get the value for option specified by [key] if it was previously [set] or if it has a default value. + * Gets the value for the option specified by [key] if it was previously [set] or if it has a default value. * * @return the previously set value for an option * @throws IllegalStateException if the option was not set and has no default value @@ -82,7 +82,7 @@ public companion object { /** - * Include a class, file-level property, or file-level function in a dump by its name. + * Includes a class, file-level property, or file-level function in a dump by its name. * Declarations that do not match the specified names, that do not have an annotation from [INCLUDE_ANNOTATED_WITH] * and do not have members marked with an annotation from [INCLUDE_ANNOTATED_WITH] are excluded from the dump. * @@ -90,14 +90,14 @@ * * - For Kotlin declarations, fully qualified names are used. * It is important to keep in mind that dots are used everywhere as separators, even in the case of a nested class. - * E.g. for qualified name `foo.bar.Container.Value`, here `Value` is a class nested in `Container`. + * For example, for the qualified name `foo.bar.Container.Value`, `Value` is a class nested in `Container`. * * - For classes from Java sources, canonical names are used. * The main motivation is a similar approach to writing the class name - dots are used everywhere as delimiters. * * Name templates are allowed, with support for wildcards such as `**`, `*`, and `?`: - * - `**` - zero or any number of characters - * - `*` - zero or any number of characters excluding dot. Using to specify simple class name. + * - `**` - zero or any number of characters. + * - `*` - zero or any number of characters, excluding dots. Specifies a simple class name. * - `?` - any single character. * * @since 2.4.0 @@ -112,14 +112,14 @@ * * - For Kotlin declarations, fully qualified names are used. * It is important to keep in mind that dots are used everywhere as separators, even in the case of a nested class. - * E.g. for qualified name `foo.bar.Container.Value`, here `Value` is a class nested in `Container`. + * For example, for the qualified name `foo.bar.Container.Value`, `Value` is a class nested in `Container`. * * - For classes from Java sources, canonical names are used. * The main motivation is a similar approach to writing the class name - dots are used everywhere as delimiters. * * Name templates are allowed, with support for wildcards such as `**`, `*`, and `?`: - * - `**` - zero or any number of characters - * - `*` - zero or any number of characters excluding dot. Using to specify simple class name. + * - `**` - zero or any number of characters. + * - `*` - zero or any number of characters, excluding dots. Specifies a simple class name. * - `?` - any single character. * * @since 2.4.0 @@ -135,11 +135,11 @@ * The declaration can be a class, a class member (function or property), a top-level function or a top-level property. * * Name templates are allowed, with support for wildcards such as `**`, `*`, and `?`: - * - `**` - zero or any number of characters - * - `*` - zero or any number of characters excluding dot. Using to specify simple class name. + * - `**` - zero or any number of characters. + * - `*` - zero or any number of characters, excluding dots. Specifies a simple class name. * - `?` - any single character. * - * The annotation should not have [Retention] equal to [AnnotationRetention.SOURCE], otherwise, filtering by it will not work. + * The annotation should not have [Retention] equal to [AnnotationRetention.SOURCE], otherwise, filtering by it does not work. * * @since 2.4.0 */ @@ -153,11 +153,11 @@ * marked by a specific annotation will be excluded from the dump. * * Name templates are allowed, with support for wildcards such as `**`, `*`, and `?`: - * - `**` - zero or any number of characters - * - `*` - zero or any number of characters excluding dot. Using to specify simple class name. + * - `**` - zero or any number of characters. + * - `*` - zero or any number of characters, excluding dots. Specifies a simple class name. * - `?` - any single character. * - * The annotation should not have [Retention] equal to [AnnotationRetention.SOURCE], otherwise, filtering by it will not work. + * The annotation should not have [Retention] equal to [AnnotationRetention.SOURCE], otherwise, filtering by it does not work. * * @since 2.4.0 */ @@ -167,19 +167,19 @@ } /** - * Target name consisting of two parts: a [customizedName] that could be configured by a user, and a [targetType] - * that specifies a target platform and could not be configured by a user. + * The target name consisting of two parts: a [customizedName] that could be configured by a user, and a [targetType] + * that specifies a target platform and can't be configured by a user. * * @since 2.4.0 */ @ExperimentalBuildToolsApi public class KlibTargetId( /** - * A type of klib target. + * The klib target type. */ public val targetType: KlibTargetType, /** - * A name of a target that could be configured by a user. + * The target name that can be configured by the user. * Usually, it's the same name as [KlibTargetType.canonicalName] from [targetType]. */ public val customizedName: String @@ -203,7 +203,7 @@ /** - * A type of Kotlin target. + * The Kotlin target type. * Specifies the platform or native architecture. * * @since 2.4.0
diff --git a/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/CompareAbiTextFilesOperation.kt b/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/CompareAbiTextFilesOperation.kt index e2bc87f..e8bcc48 100644 --- a/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/CompareAbiTextFilesOperation.kt +++ b/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/CompareAbiTextFilesOperation.kt
@@ -12,7 +12,7 @@ /** * Compares two files line-by-line and writes the comparison result into the [Appendable] provided via [org.jetbrains.kotlin.buildtools.api.abi.AbiValidationToolchain.compareAbiTextFilesOperationBuilder]. * - * If files are equal, nothing is written to diff. + * If the files are the same, nothing is written to the diff. * * @since 2.4.0 */
diff --git a/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/DumpJvmAbiToStringOperation.kt b/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/DumpJvmAbiToStringOperation.kt index 9369da4..ae95f083 100644 --- a/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/DumpJvmAbiToStringOperation.kt +++ b/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/DumpJvmAbiToStringOperation.kt
@@ -16,10 +16,10 @@ import kotlin.contracts.contract /** - * Prints an ABI dump for JVM from [Builder.inputFiles] into the provided via [AbiValidationToolchain.dumpJvmAbiToStringOperationBuilder] appendable. - * It is possible to pass class-files or jar files in [Builder.inputFiles]. + * Prints an ABI dump for the JVM from [Builder.inputFiles] into the appendable provided via [AbiValidationToolchain.dumpJvmAbiToStringOperationBuilder]. + * It is possible to pass class files or JAR files in [Builder.inputFiles]. * - * To control which declarations are passed to the dump, the option [DumpJvmAbiToStringOperation.PATTERN_FILTERS] could be used. By default, no filters will be applied. + * To control which declarations are passed to the dump, the [DumpJvmAbiToStringOperation.PATTERN_FILTERS] option can be used. By default, no filters are applied. * * @since 2.4.0 */ @@ -44,7 +44,7 @@ public fun filtersBuilder(): AbiFilters.Builder /** - * Get the value for option specified by [key] if it was previously [set] or if it has a default value. + * Gets the value for the option specified by [key] if it was previously [set] or if it has a default value. * * @return the previously set value for an option * @throws IllegalStateException if the option was not set and has no default value @@ -54,7 +54,7 @@ public operator fun <V> get(key: Option<V>): V /** - * Set the [value] for option specified by [key], overriding any previous value for that option. + * Sets the [value] for the option specified by [key], overriding any previous value for that option. * * @since 2.4.0 */ @@ -70,7 +70,7 @@ public companion object { /** - * Set of filtering rules that restrict ABI declarations included in a dump. + * A set of filtering rules that restrict the ABI declarations included in a dump. * See [AbiFilters] for details. * * @since 2.4.0 @@ -80,7 +80,7 @@ } /** - * Get the value for option specified by [key] if it was previously [set] or if it has a default value. + * Gets the value for option specified by [key] if it was previously [set] or if it has a default value. * * @return the previously set value for an option * @throws IllegalStateException if the option was not set and has no default value
diff --git a/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/DumpKlibAbiToStringOperation.kt b/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/DumpKlibAbiToStringOperation.kt index 2c86246..c75904e 100644 --- a/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/DumpKlibAbiToStringOperation.kt +++ b/compiler/build-tools/kotlin-build-tools-api/src/main/kotlin/org/jetbrains/kotlin/buildtools/api/abi/operations/DumpKlibAbiToStringOperation.kt
@@ -20,19 +20,19 @@ /** - * Prints an ABI dump for klib targets from [Builder.klibs] into the provided via [AbiValidationToolchain.dumpKlibAbiToStringOperationBuilder] appendable. + * Prints an ABI dump for klib targets from [Builder.klibs] into the appendable provided via [AbiValidationToolchain.dumpKlibAbiToStringOperationBuilder]. * Compressed and unpacked klibs are supported. * - * If option [TARGETS_TO_INFER] is specified and not empty, for the specified targets the ABI will be inferred from the value of the option [REFERENCE_DUMP_FILE]. + * If option [TARGETS_TO_INFER] is specified and not empty, for the specified targets the ABI are inferred from the value of the option [REFERENCE_DUMP_FILE]. * The inference works as follows: - * - for each target from [TARGETS_TO_INFER], the ABI is inferred from the [REFERENCE_DUMP_FILE], if it exists, not empty, and this target is present in it. - * - all the non-inferred targets that belong to the group that this target belongs to are found. Then all declarations are added that are present in all of them. - * - if some target specified in [TARGETS_TO_INFER] and present in the [klibs], then the error is thrown. + * - For each target from [TARGETS_TO_INFER], the ABI is inferred from the [REFERENCE_DUMP_FILE], if it exists, is not empty, and this target is present in it. + * - If all the non-inferred targets that belong to the group that this target belongs to are found, all declarations are added that are present in all of them. + * - If some target is specified in [TARGETS_TO_INFER] and is present in [klibs], then an error is thrown. * - * The inference is used in cases where the host compiler cannot compile some targets, but there is a need to build an ABI dump, - * even if with some inaccuracies. + * Inference is used in cases where the host compiler can't compile some targets, but there is a need to build an ABI dump, + * even if it has some inaccuracies. * - * To control which declarations are passed to the dump, the option [DumpKlibAbiToStringOperation.PATTERN_FILTERS] could be used. By default, no filters will be applied. + * To control which declarations are passed to the dump, the option [DumpKlibAbiToStringOperation.PATTERN_FILTERS] can be used. By default, no filters will be applied. * * @since 2.4.0 */ @@ -57,7 +57,7 @@ public fun filtersBuilder(): AbiFilters.Builder /** - * Get the value for option specified by [key] if it was previously [set] or if it has a default value. + * Gets the value for the option specified by [key] if it was previously [set] or if it has a default value. * * @return the previously set value for an option * @throws IllegalStateException if the option was not set and has no default value @@ -67,7 +67,7 @@ public operator fun <V> get(key: Option<V>): V /** - * Set the [value] for option specified by [key], overriding any previous value for that option. + * Sets the [value] for the option specified by [key], overriding any previous value for that option. * * @since 2.4.0 */ @@ -83,7 +83,7 @@ public companion object { /** - * Set of filtering rules that restrict ABI declarations included in a dump. + * A set of filtering rules that restrict ABI declarations included in a dump. * See [AbiFilters] for details. * * @since 2.4.0 @@ -92,7 +92,7 @@ public val PATTERN_FILTERS: Option<AbiFilters?> = Option("PATTERN_FILTERS") /** - * Set of targets for which the ABI will be inferred from the [REFERENCE_DUMP_FILE]. + * The set of targets for which the ABI are inferred from the [REFERENCE_DUMP_FILE]. * * Refer to the documentation of [DumpKlibAbiToStringOperation] for more details about the inference process. * @@ -102,7 +102,7 @@ public val TARGETS_TO_INFER: Option<Set<KlibTargetId>> = Option("TARGETS_TO_INFER") /** - * Path to the file containing the reference ABI dump for the previous ABI. + * The path to the file containing the reference ABI dump for the previous ABI. * Should be used only if [TARGETS_TO_INFER] is specified and not empty. * * Refer to the documentation of [DumpKlibAbiToStringOperation] for more details about the inference process. @@ -114,7 +114,7 @@ } /** - * Get the value for option specified by [key] if it was previously [set] or if it has a default value. + * Get the value for the option specified by [key] if it was previously [set] or if it has a default value. * * @return the previously set value for an option * @throws IllegalStateException if the option was not set and has no default value
diff --git a/libraries/tools/abi-validation/abi-tools-api/src/main/kotlin/org/jetbrains/kotlin/abi/tools/AbiFilters.kt b/libraries/tools/abi-validation/abi-tools-api/src/main/kotlin/org/jetbrains/kotlin/abi/tools/AbiFilters.kt index 92988c4..dbfc7a8 100644 --- a/libraries/tools/abi-validation/abi-tools-api/src/main/kotlin/org/jetbrains/kotlin/abi/tools/AbiFilters.kt +++ b/libraries/tools/abi-validation/abi-tools-api/src/main/kotlin/org/jetbrains/kotlin/abi/tools/AbiFilters.kt
@@ -6,22 +6,22 @@ package org.jetbrains.kotlin.abi.tools /** - * Set of filtering rules that restrict ABI declarations included into a dump. + * A set of filtering rules that restrict ABI declarations included in a dump. * - * The rules combine inclusion and exclusion of declarations. + * The rules combine inclusions and exclusions of declarations. * Each filter can be written as a filter for the class name (see [includedClasses] or [excludedClasses]), or an annotation filter (see [includedAnnotatedWith] or [excludedAnnotatedWith]). * - * In order for a declaration (class, field, property or function) to get into the dump, it must pass the inclusion **and** exclusion filters. + * In order for a declaration (class, field, property, or function) to get into the dump, it must pass the inclusion **and** exclusion filters. * - * A declaration passes the exclusion filters if it does not match any class names (see [excludedClasses]) or annotation (see [excludedAnnotatedWith]) filter rules. + * A declaration passes the exclusion filters if it does not match any class names (see [excludedClasses]) or annotation (see [excludedAnnotatedWith]) filter rules. * - * A declaration passes the inclusion filters if there is no inclusion rules, or it matches any inclusion rule, or at least one of its members (actual for class declaration) matches any inclusion rule. + * A declaration passes the inclusion filters if there are no inclusion rules, or it matches any inclusion rule, or at least one of its members (relevant for class declaration) matches any inclusion rule. * * @since 2.3.20 */ public class AbiFilters( /** - * Include a class, file-level property, or file-level function in a dump by its name. + * Includes a class, file-level property, or file-level function in a dump by its name. * Declarations that do not match the specified names, that do not have an annotation from [includedAnnotatedWith] * and do not have members marked with an annotation from [includedAnnotatedWith] are excluded from the dump. * @@ -29,14 +29,14 @@ * * For Kotlin declarations, fully qualified names are used. * It is important to keep in mind that dots are used everywhere as separators, even in the case of a nested class. - * E.g. for qualified name `foo.bar.Container.Value`, here `Value` is a class nested in `Container`. + * For example, for the qualified name `foo.bar.Container.Value`, `Value` is a class nested in `Container`. * * For classes from Java sources, canonical names are used. * The main motivation is a similar approach to writing the class name - dots are used everywhere as delimiters. * * Name templates are allowed, with support for wildcards such as `**`, `*`, and `?`: - * - `**` - zero or any number of characters - * - `*` - zero or any number of characters excluding dot. Using to specify simple class name. + * - `**` - zero or any number of characters. + * - `*` - zero or any number of characters, excluding dots. Specifies a simple class name. * - `?` - any single character. */ public val includedClasses: Set<String>, @@ -48,14 +48,14 @@ * * For Kotlin declarations, fully qualified names are used. * It is important to keep in mind that dots are used everywhere as separators, even in the case of a nested class. - * E.g. for qualified name `foo.bar.Container.Value`, here `Value` is a class nested in `Container`. + * For example, for the qualified name `foo.bar.Container.Value`, `Value` is a class nested in `Container`. * * For classes from Java sources, canonical names are used. * The main motivation is a similar approach to writing the class name - dots are used everywhere as delimiters. * * Name templates are allowed, with support for wildcards such as `**`, `*`, and `?`: - * - `**` - zero or any number of characters - * - `*` - zero or any number of characters excluding dot. Using to specify simple class name. + * - `**` - zero or any number of characters. + * - `*` - zero or any number of characters, excluding dots. Specifies a simple class name. * - `?` - any single character. */ public val excludedClasses: Set<String>, @@ -63,13 +63,13 @@ /** * Includes a declaration by annotations placed on it. * - * Any declaration that is not marked with one of the these annotations and does not match the [includedClasses] is excluded from the dump. + * Any declaration that is not marked with one of these annotations and does not match the [includedClasses] is excluded from the dump. * * The declaration can be a class, a class member (function or property), a top-level function or a top-level property. * * Name templates are allowed, with support for wildcards such as `**`, `*`, and `?`: - * - `**` - zero or any number of characters - * - `*` - zero or any number of characters excluding dot. Using to specify simple class name. + * - `**` - zero or any number of characters. + * - `*` - zero or any number of characters, excluding dots. Specifies a simple class name. * - `?` - any single character. * * The annotation should not have [Retention] equal to [AnnotationRetention.SOURCE], otherwise, filtering by it will not work. @@ -83,11 +83,11 @@ * marked by a specific annotation will be excluded from the dump. * * Name templates are allowed, with support for wildcards such as `**`, `*`, and `?`: - * - `**` - zero or any number of characters - * - `*` - zero or any number of characters excluding dot. Using to specify simple class name. + * - `**` - zero or any number of characters. + * - `*` - zero or any number of characters, excluding dots. Specifies a simple class name. * - `?` - any single character. * - * The annotation should not have [Retention] equal to [AnnotationRetention.SOURCE], otherwise, filtering by it will not work. + * The annotation should not have [Retention] equal to [AnnotationRetention.SOURCE], otherwise, filtering by it does not work. */ public val excludedAnnotatedWith: Set<String>, ) {
diff --git a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinTopLevelExtension.kt b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinTopLevelExtension.kt index cc9fb3a..1a9c623 100644 --- a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinTopLevelExtension.kt +++ b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinTopLevelExtension.kt
@@ -34,16 +34,16 @@ interface KotlinTopLevelExtension : KotlinTopLevelExtensionConfig, KotlinSourceSetContainer { /** - * Configures [Java toolchain](https://docs.gradle.org/current/userguide/toolchains.html) - * both for Kotlin JVM and Java tasks in the project. + * Configures the [Java toolchain](https://docs.gradle.org/current/userguide/toolchains.html) + * both for Kotlin/JVM and Java tasks in the project. * * @param action - action to configure [JavaToolchainSpec] */ fun jvmToolchain(action: Action<JavaToolchainSpec>) /** - * Configures [Java toolchain](https://docs.gradle.org/current/userguide/toolchains.html) - * both for Kotlin JVM and Java tasks in the project. + * Configures the [Java toolchain](https://docs.gradle.org/current/userguide/toolchains.html) + * both for Kotlin/JVM and Java tasks in the project. * * @param jdkVersion - JDK version as number. For example, 17 for Java 17. */ @@ -52,8 +52,8 @@ /** * Configures Kotlin daemon JVM arguments for all tasks in this project. * - * **Note**: In case other projects are using different JVM arguments, - * a new instance of Kotlin daemon will be started. + * **Note**: If other projects are using different JVM arguments, + * a new instance of Kotlin daemon is started. */ @ExperimentalKotlinGradlePluginApi @get:JvmSynthetic @@ -66,17 +66,17 @@ * * Be careful with reading the property's value as eager reading will finalize the value and prevent it from being configured. * - * Note: Currently only has an effect if the `kotlin.compiler.runViaBuildToolsApi` Gradle property is set to `true`. + * Note: This value only has an effect if the `kotlin.compiler.runViaBuildToolsApi` Gradle property is set to `true`. */ @ExperimentalKotlinGradlePluginApi @ExperimentalBuildToolsApi val compilerVersion: Property<String> /** - * Can be used to configure objects that are not yet created, or will be created in + * This function can be used to configure objects that are not yet created, or are created by * 'afterEvaluate' (for example, typically for Android source sets containing flavors and buildTypes). * - * Will fail project evaluation if the domain object is not created before 'afterEvaluate' listeners in the buildscript. + * Project evaluation will fail if the domain object is not created before 'afterEvaluate' listeners in the buildscript. * * @param configure Called inline if the value is already present. Called once the domain object is created. */ @@ -102,7 +102,7 @@ * } * ``` * - * Accessing this property causes ABI validation to be enabled and corresponding tasks to be created. + * Accessing this property causes ABI validation to be enabled and the corresponding tasks to be created. * * Note that this DSL is experimental, and it will likely change in future versions until it is stable. * @@ -148,4 +148,4 @@ */ @ExperimentalAbiValidation fun abiValidation() -} \ No newline at end of file +}
diff --git a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/abi/AbiFiltersSpec.kt b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/abi/AbiFiltersSpec.kt index c532f23..18c8608 100644 --- a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/abi/AbiFiltersSpec.kt +++ b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/abi/AbiFiltersSpec.kt
@@ -10,7 +10,7 @@ import org.jetbrains.kotlin.gradle.dsl.KotlinGradlePluginDsl /** - * A set of filtering rules that restrict Application Binary Interface (ABI) declarations from being included in a dump. + * A set of filtering rules that restrict Application Binary Interface (ABI) declarations from being included in a dump. * * The rules combine inclusion and exclusion of declarations. * Each filter can be written as either a class name filter (see [AbiFilterSetSpec.byNames]) or an annotation filter (see [AbiFilterSetSpec.annotatedWith]). @@ -31,7 +31,7 @@ * * In order for a declaration (class, field, property, or function) to be included in the dump, it must pass **all** inclusion and exclusion filters. * - * A declaration successfully passes the exclusion filter if it does not match any of the class name (see [AbiFilterSetSpec.byNames]) or annotation (see [AbiFilterSetSpec.annotatedWith]) filter rules. + * A declaration successfully passes the exclusion filter if it does not match any of the class name (see [AbiFilterSetSpec.byNames]) or annotation (see [AbiFilterSetSpec.annotatedWith]) filter rules. * * A declaration successfully passes the inclusion filter if no inclusion rules exist, if it matches any inclusion rule, or if at least one of its members (relevant for class declaration) matches any inclusion rule. * @@ -41,7 +41,7 @@ @ExperimentalAbiValidation interface AbiFiltersSpec { /** - * A set of filtering rules that restrict ABI declarations from being included in a dump. + * A set of filtering rules that restrict ABI declarations from being included in a dump. * * The rules combine inclusion and exclusion of declarations. * Each filter can be written as either a class name filter (see [AbiFilterSetSpec.byNames]) or an annotation filter (see [AbiFilterSetSpec.annotatedWith]). @@ -191,6 +191,7 @@ * annotatedWith.add("foo.PublicApi") * } * } + * ``` * * Exclusion filters: * @@ -209,7 +210,7 @@ @ExperimentalAbiValidation interface AbiFilterSetSpec { /** - * Filter by a name. + * Filters declarations by name. * * The name filter compares the symbol qualified name with the value in the filter: * @@ -235,7 +236,7 @@ * * Name templates are allowed, with support for wildcards such as `**`, `*`, and `?`: * - `**` - Matches zero or more characters, including periods. - * - `*` - Matches zero or more characters excluding periods. Use this to specify a single class name. + * - `*` - Matches zero or more characters, excluding periods. Specifies a single class name. * - `?` - Matches exactly one character. * * ```kotlin @@ -249,7 +250,7 @@ val byNames: SetProperty<String> /** - * Filter by annotations placed on the declaration. + * Filters declarations by annotations placed on them. * * If a class, top-level function or property, or class member (a property or a function) is annotated with one of the specified annotations, then this declaration matches the filter. * @@ -260,7 +261,7 @@ * * Name templates are allowed, with support for wildcards such as `**`, `*`, and `?`: * - `**` - Matches zero or more characters, including periods. - * - `*` - Matches zero or more characters excluding periods. Use this to specify a single class name. + * - `*` - Matches zero or more characters, excluding periods. Specifies a single class name. * - `?` - Matches exactly one character. * * Example: @@ -275,7 +276,7 @@ * * **Important**: * The annotation **must** have a [Retention] of [BINARY][AnnotationRetention.BINARY] or [RUNTIME][AnnotationRetention.RUNTIME] type. - * Annotations with [SOURCE][AnnotationRetention.SOURCE] retention cannot be analyzed and will be ignored. + * Annotations with [SOURCE][AnnotationRetention.SOURCE] retention cannot be analyzed and are ignored. * */ val annotatedWith: SetProperty<String>
diff --git a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/abi/AbiValidationExtension.kt b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/abi/AbiValidationExtension.kt index 00cd87f..77453cd 100644 --- a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/abi/AbiValidationExtension.kt +++ b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/abi/AbiValidationExtension.kt
@@ -68,7 +68,7 @@ * } * ``` * - * In order for a declaration (class, field, property or function) to get into the dump, it must pass the inclusion **and** exclusion filters. + * In order for a declaration (class, field, property, or function) to get into the dump, it must pass the inclusion **and** exclusion filters. * * A declaration successfully passes the exclusion filter if it does not match any of the class name (see [AbiFilterSetSpec.byNames]) or annotation (see [AbiFilterSetSpec.annotatedWith]) filter rules. * @@ -91,7 +91,7 @@ val referenceDumpDir: DirectoryProperty /** - * A provider for the task that compares actual dumps from the current with dumps from [referenceDumpDir]. + * A provider for the task that compares actual dumps from the current code with dumps from [referenceDumpDir]. * * This task fails if any differences are found between the files. * @@ -107,38 +107,38 @@ val updateTaskProvider: TaskProvider<Task> /** - * Whether to include the declarations for targets which are not supported by the host in the generated dump. - * Targets which are not supported by the host in two cases: - * - cross-compilation is disabled and some targets can't be compiled on the host machine - * - c-interop being used and some targets can't be compiled on the host machine + * Determines whether to include the declarations for targets which are not supported by the host in the generated dump. + * A target is not supported by the host in two cases: + * - Cross-compilation is disabled and some targets can't be compiled on the host machine. + * - C-interop is being used, and some targets can't be compiled on the host machine. * * These declarations are taken from the reference dump, if available. * * If possible, unsupported targets are supplemented with common declarations that are already present in the supported targets. * * However, this does not provide a complete guarantee, so it should be used with caution. - * This mode is intended to improve the "local" development experience only, and it is crucial to double-check ABI dumps on a host supporting corresponding compilation targets. + * This mode is intended to improve the "local" development experience only, and it is crucial to double-check ABI dumps on a host supporting the corresponding compilation targets. * * If the option is set to `false` and the compiler does not support some of the Kotlin targets used in the current project, the dump generation fails with an error. * * #### Example * * There are two targets in the project `iosX64`, `androidNativeX64` and `linuxX64`. - * Current dump contains class `my.Utils` which present in all targets, `my.IosUtils` only in iosX64. + * The current dump contains the `my.Utils` class which is present in all targets. The `my.IosUtils` class is only present in iosX64. * - * Suppose we make such changes: - * - added `my.Utils2` in all targets - * - added `my.LinuxUtils` in linuxX64 - * - added `my.NonAppleUtils` in linuxX64 and androidNativeX64 - * - added `my.IosUtils2` in iosX64 + * Suppose we make these changes: + * - Added `my.Utils2` in all targets + * - Added `my.LinuxUtils` in linuxX64 + * - Added `my.NonAppleUtils` in linuxX64 and androidNativeX64 + * - Added `my.IosUtils2` in iosX64 * - * On a host that lacks iosX64 support, and this mode is enabled, there will be such changes in the dump: - * - `my.Utils` will stay present in all targets of the new dump (correct inference) - * - `my.IosUtils` will stay present in iosX64 target of the new dump (correct inference) - * - `my.Utils2` will be present in all targets of the new dump (correct inference) - * - `my.LinuxUtils` will be present in linuxX64 target of the new dump (correct inference) - * - `my.NonAppleUtils` will be present in all targets of the new dump (incorrect inference - because usually if it is added to everything, then there is a high chance that the symbol is added to an unsupported target) - * - `my.IosUtils2` won't be present in iosX64 targets of the new dump (incorrect inference - because we can't compile the target and see what appeared individually in it) + * On a host that lacks iosX64 support, when this mode is enabled, there are these changes in the dump: + * - `my.Utils` stays present in all targets of the new dump (correct inference) + * - `my.IosUtils` stays present in iosX64 target of the new dump (correct inference) + * - `my.Utils2` are present in all targets of the new dump (correct inference) + * - `my.LinuxUtils` are present in linuxX64 target of the new dump (correct inference) + * - `my.NonAppleUtils` are present in all targets of the new dump (incorrect inference - because usually if it is added to everything, then there is a high chance that the symbol is added to an unsupported target) + * - `my.IosUtils2` aren't be present in iosX64 targets of the new dump (incorrect inference - because we can't compile the target and see what appeared individually in it) * * * Default value: `true` @@ -308,7 +308,7 @@ enum class BinariesSource { /** * The binaries are taken from the Maven publications of the project. - * To do this, the `maven-publish` plugin must be applied, the Maven publications must be created and configured correctly. + * The `maven-publish` plugin must be applied and the Maven publications must be created and configured correctly. * * Only publishable artifacts for which no classifier is specified (is null) are taken into account. */ @@ -320,7 +320,7 @@ MAIN_COMPILATION, /** - * The binaries are taken from the output of the Kotlin compilation tasks which do not contain the word `test` in the name in any case. + * The binaries are taken from the output of the Kotlin compilation tasks whose names do not contain the word `test`, regardless of the case. */ NON_TEST_COMPILATIONS }
diff --git a/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/diagnostics/KotlinToolingDiagnostics.kt b/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/diagnostics/KotlinToolingDiagnostics.kt index 3df2dda..1cdfc10 100644 --- a/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/diagnostics/KotlinToolingDiagnostics.kt +++ b/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/diagnostics/KotlinToolingDiagnostics.kt
@@ -1995,10 +1995,10 @@ operator fun invoke(): ToolingDiagnostic = build { title("ABI Validation: no Maven publishing plugin") .description { - "Source of binaries is set to Maven publications, but maven publishing plugin is not applied." + "The binaries source is set to Maven publications, but the Maven publishing plugin is not applied." } .solution { - "Apply `maven-publish` plugin and create Maven publication, or specify `kotlin.abiValidation { binariesSource = MAIN_COMPILATION }` to use output of the main compilation tasks" + "Apply the `maven-publish` plugin and create a Maven publication, or specify `kotlin.abiValidation { binariesSource = MAIN_COMPILATION }` to use the output of the main compilation tasks." } } } @@ -2007,10 +2007,10 @@ operator fun invoke(): ToolingDiagnostic = build { title("ABI Validation: Android target unsupported with Maven binary sources mode") .description { - "Android targets are not supported by ABI validation when Maven binary sources mode is enabled" + "Android targets are not supported by ABI validation when the Maven binary sources mode is enabled" } .solution { - "Specify `kotlin.abiValidation { binariesSource = MAIN_COMPILATION }` to use output of the main compilation tasks" + "Specify `kotlin.abiValidation { binariesSource = MAIN_COMPILATION }` to use the output of the main compilation tasks." } } }