Merge pull request #1 from GreemDev/main

Documentation grammar improvements

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(

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 top-level factory functions, with the name
+of the builder type (the part of the function name before `Builder`).
 
 ```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<String>("sayHello") {

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<String>("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") {

docs/topics/utility-functions.md

@@ -10,15 +10,15 @@ Returns an empty code block
 public fun emptyCodeBlock(): CodeBlock
 ```
 
-## indentWithSpaces
+## indentWithSpaces()
 
 Indents the file with the specified amount of spaces
 
 ```kotlin
 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.