From 994f361caf57693305acf561f1a3e19a5cce2a68 Mon Sep 17 00:00:00 2001 From: Evan Husted Date: Thu, 14 Sep 2023 20:08:52 -0500 Subject: [PATCH 1/5] Update member-naming.md --- docs/topics/member-naming.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/topics/member-naming.md b/docs/topics/member-naming.md index 1c6d8d5..0e66285 100644 --- a/docs/topics/member-naming.md +++ b/docs/topics/member-naming.md @@ -1,12 +1,11 @@ # Member naming -> This example uses `ParameterSpec`s, but everything can be translated 1:1 for `PropertySpec`s +> This example uses `ParameterSpec`s, but everything can be translated 1:1 for `PropertySpec`s. > {style="note"} -One of the most important things in programming is naming, and this isn't different in Code generation, however, there -often are cases in which names become magic values in different places, for example, here all we want to do is to return -a parameter of a function +One of the most important things in programming is naming, and this isn't different in code generation; but there often are cases in which names become magic values in different places. +For example, here all we want to do is to return a parameter of a function: ```kotlin FunSpec("returnString") { @@ -15,10 +14,9 @@ FunSpec("returnString") { addCode("return·%L", "text") } ``` - -however, even in this basic use case, we already have to put the name twice, so if we change it for whatever reason -or make a mistake copying the name, we have to fix it in two places, another way is to use the `%N` placeholder, - however, this requires us to store the parameter spec somewhere. +However, even in this basic use case, we already have to put the name twice. If we change it for whatever reason +or make a mistake copying the name, we have to fix it in two places. +Another way is to use the `%N` placeholder, but, this requires us to store the `ParameterSpec` somewhere. ```kotlin val parameterSpec = ParameterSpec("text") @@ -29,8 +27,9 @@ FunSpec("returnString") { } ``` -This is already better, because now we only write the name once, however, now we have this ugly `parameterSpec` variable. -Luckily, the DSL allows us to use the return value of the addParameter function instead +This is already better, because now we only write the name once. +Just one issue: now we have this ugly `parameterSpec` variable. +Luckily, the DSL allows us to use the return value of the addParameter function instead! ```kotlin FunSpec("returnString") { @@ -40,9 +39,8 @@ FunSpec("returnString") { } ``` -So this is looking already a lot better. However, in a lot of instances, you can end up writing the name twice. If the -parameter name and the variable name is identical, you can use property delegation -[similar to the Gradle Kotlin DSL](https://docs.gradle.org/current/userguide/kotlin_dsl.html#using_kotlin_delegated_properties) +So this is looking already a lot better. In a lot of instances, you can end up writing the name twice, but if the parameter & variable names are identical, you can use property delegation +[similar to the Gradle Kotlin DSL](https://docs.gradle.org/current/userguide/kotlin_dsl.html#using_kotlin_delegated_properties). ```kotlin FunSpec("returnString") { From 6b06d9fd4752863068239571917c095d88cecb7f Mon Sep 17 00:00:00 2001 From: Evan Husted Date: Thu, 14 Sep 2023 20:17:15 -0500 Subject: [PATCH 2/5] Update kotlinpoet.md --- docs/topics/kotlinpoet.md | 40 +++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/topics/kotlinpoet.md b/docs/topics/kotlinpoet.md index 6e928bf..8a3cb05 100644 --- a/docs/topics/kotlinpoet.md +++ b/docs/topics/kotlinpoet.md @@ -7,14 +7,14 @@ ## DSL types -The entire KotlinPoet DSL is generated from the normal KotlinPoet source code, therefore, there are certain types of -generated DSL functions, which also allows you to know what code you can migrate to the DSL and what stays the same +The entire KotlinPoet DSL is generated from the normal KotlinPoet source code. Therefore, there are certain types of +generated DSL functions which also allow you to know what code you can migrate to the DSL and what stays the same. ### Factory functions {id="factory_functions"} -Almost everything in KotlinPoet is represented by an immutable "spec-class" and one or more corresponding constructor -functions in its companion object, which return a builder, these will simply be replaced by a top-level factory function -which takes the name of the spec class and takes a builder +Almost everything in KotlinPoet is represented by an immutable specification class (Spec) and one or more corresponding constructor +functions in its companion object, which return a builder. These will simply be replaced by a top-level factory function +which takes the name of the spec class and takes a builder lambda: ```kotlin FunSpec.builder("func") @@ -33,9 +33,10 @@ CodeBlock { } ``` -However, these builder functions are not always called builder — for example; the TypeSpec builder has different types -like TypeSpec.classBuilder() or TypeSpec.interfaceBuilder, in this case a top_level factory function, with the name -of the builder type (the part of the function name before the `Builder` part) +However, these builder functions are not always called builder; for example, the TypeSpec builder has different types +like `TypeSpec.classBuilder()` or `TypeSpec.interfaceBuilder()`. +In this DSL, these are a top-level factory function, with the name +of the builder type (the part of the function name before the `Builder` part). ```kotlin TypeSpec.classBuilder("name") @@ -46,8 +47,7 @@ TypeSpec.classBuilder("name") } ``` -Another option is a factory function, which directly returns the constructed class directly, which -is usually called `get` +Another option is a factory function, which directly returns the constructed class directly, which is usually called `get`. ```kotlin AnnotationSpec.get(Suppress("UNUSED")) @@ -56,8 +56,8 @@ AnnotationSpec(Suppress("UNUSED")) ``` ### Scoping functions -Some functions in KotlinPoet allow you to `begin` and `end` some sort of scope like a control flow in a CodeBlock or -similar, these are what we refer to as scoping functions in the generator +Some functions in KotlinPoet allow you to `begin` and `end` some sort of scope like a control flow in a `CodeBlock` or +similar, these are what we refer to as scoping functions in the generator. ```kotlin buildCodeBlock { @@ -67,7 +67,7 @@ buildCodeBlock { } ``` -In this case we generate a `withScope` function which begins the scope, calls some lambda and ends the scope +In this case we generate a `withScope` function which begins the scope, calls some lambda and ends the scope: ```kotlin CodeBlock { withControlFlow("if (1 == 2)") { @@ -77,10 +77,10 @@ CodeBlock { ``` ### Constructor inlining -The KotlinPoet API always allows you to add "spec-types" to other "spec-types" (e.g. TypeSpec.addType() is for adding -classes, interfaces, etc.), however in most cases you only construct that spec type to immediately add it to another -spec, therefore we do something we call "constructor-inlining", where we take the [Factory function](#factory_functions) -and generate a version of the "addSpec" function to directly call the constructor +The KotlinPoet API always allows you to add `Spec`s to other `Spec`s (e.g. TypeSpec.addType() is for adding +classes, interfaces, etc.). However, in most cases you only construct that spec type to immediately add it to another +spec, therefore we do something we call "constructor inlining", where we take the [factory function](#factory_functions) +and generate a version of the "addSpec" function to directly call the constructor. ```kotlin FileSpec("dev.kord", "CoolClass") { @@ -97,9 +97,9 @@ FileSpec("dev.kord", "CoolClass") { ### Reification Kotlin has the ability to retain type parameters using -[reification](https://kotlinlang.org/docs/inline-functions.html#reified-type-parameters), which can be useful, if you -want to specify types names as a literal (e.g. the type of a property), therefore the DSL generates a reified version -of any function which takes either a `TypeName`, `ClassName` or `KClass` +[reification](https://kotlinlang.org/docs/inline-functions.html#reified-type-parameters), which can be useful if you +want to specify types names as a literal (e.g. the type of a property). +Therefore, the DSL generates a reified version of any function which takes either a `TypeName`, `ClassName` or `KClass`: ```kotlin addFunction("sayHello") { From 1300249f70d1ffcaca2ca1b4321f58786888a4ed Mon Sep 17 00:00:00 2001 From: Evan Husted Date: Thu, 14 Sep 2023 20:18:10 -0500 Subject: [PATCH 3/5] Update Annotation-Argument-API.md --- docs/topics/Annotation-Argument-API.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/topics/Annotation-Argument-API.md b/docs/topics/Annotation-Argument-API.md index ad8ffa7..ad7255d 100644 --- a/docs/topics/Annotation-Argument-API.md +++ b/docs/topics/Annotation-Argument-API.md @@ -1,9 +1,9 @@ # Annotation Argument API -Codegen.kt offers a type safe way to access annotation arguments from an `KSAnnotation` instance +Codegen.kt offers a type safe way to access annotation arguments from an `KSAnnotation` instance. > Please note that all of these types are nullable by default because of -> [google/ksp#885](https://github.com/google/ksp/issues/885), if you don't target KMP use the `notNull` function +> [google/ksp#885](https://github.com/google/ksp/issues/885), if you don't target KMP use the `notNull` function. ```kotlin annotation class TestAnnotation( From cd1e021a6c8d0cc6af44519eac0bb39522c37f01 Mon Sep 17 00:00:00 2001 From: Evan Husted Date: Thu, 14 Sep 2023 20:19:03 -0500 Subject: [PATCH 4/5] Update utility-functions.md --- docs/topics/utility-functions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/topics/utility-functions.md b/docs/topics/utility-functions.md index 91fdaab..1efae75 100644 --- a/docs/topics/utility-functions.md +++ b/docs/topics/utility-functions.md @@ -10,7 +10,7 @@ Returns an empty code block public fun emptyCodeBlock(): CodeBlock ``` -## indentWithSpaces +## indentWithSpaces() Indents the file with the specified amount of spaces @@ -18,7 +18,7 @@ Indents the file with the specified amount of spaces public fun FileSpec.Builder.indentWithSpaces(width: Int = 4) ``` -## withNameAllocator +## withNameAllocator() Allows for usage of the name allocator like this @@ -29,7 +29,7 @@ withNameAllocator { } ``` -## ClassName.parameterizedBy +## ClassName.parameterizedBy() Allows parameterizing a ClassName by a generic type. From f13bf8873874393fedc21b0767b8f119e50ad36e Mon Sep 17 00:00:00 2001 From: Evan Husted Date: Thu, 14 Sep 2023 20:24:50 -0500 Subject: [PATCH 5/5] further tweaks --- docs/topics/kotlinpoet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/topics/kotlinpoet.md b/docs/topics/kotlinpoet.md index 8a3cb05..efeaefd 100644 --- a/docs/topics/kotlinpoet.md +++ b/docs/topics/kotlinpoet.md @@ -35,8 +35,8 @@ CodeBlock { However, these builder functions are not always called builder; for example, the TypeSpec builder has different types like `TypeSpec.classBuilder()` or `TypeSpec.interfaceBuilder()`. -In this DSL, these are a top-level factory function, with the name -of the builder type (the part of the function name before the `Builder` part). +In this DSL, these are top-level factory functions, with the name +of the builder type (the part of the function name before `Builder`). ```kotlin TypeSpec.classBuilder("name")