Skip to content

Commit

Permalink
Merge pull request #1 from GreemDev/main
Browse files Browse the repository at this point in the history
Documentation grammar improvements
  • Loading branch information
DRSchlaubi authored Sep 15, 2023
2 parents dcd1b13 + f13bf88 commit 3ba861f
Show file tree
Hide file tree
Showing 4 changed files with 36 additions and 38 deletions.
4 changes: 2 additions & 2 deletions docs/topics/Annotation-Argument-API.md
Original file line number Diff line number Diff line change
@@ -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(
Expand Down
40 changes: 20 additions & 20 deletions docs/topics/kotlinpoet.md
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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")
Expand All @@ -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"))
Expand All @@ -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 {
Expand All @@ -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)") {
Expand All @@ -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") {
Expand All @@ -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") {
Expand Down
24 changes: 11 additions & 13 deletions docs/topics/member-naming.md
Original file line number Diff line number Diff line change
@@ -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") {
Expand All @@ -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")
Expand All @@ -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") {
Expand All @@ -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") {
Expand Down
6 changes: 3 additions & 3 deletions docs/topics/utility-functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -29,7 +29,7 @@ withNameAllocator {
}
```

## ClassName.parameterizedBy
## ClassName.parameterizedBy()

Allows parameterizing a ClassName by a generic type.

Expand Down

0 comments on commit 3ba861f

Please sign in to comment.