Update: improve annotations.md introduction#5361
Conversation
docs/topics/annotations.md
Outdated
| [//]: # (title: Annotations) | ||
|
|
||
| Annotations are a means of attaching metadata to code. To declare an annotation, put the `annotation` modifier in front of a class: | ||
| Annotations are tags used to attach metadata to code. They provide additional information about tagged code elements without altering the program's execution. |
There was a problem hiding this comment.
without altering the program's execution
This is not strictly true. Some annotations are required, for example, to specify how to serialize a value into a JSON. If that annotation is not present, the program would behave differently.
There was a problem hiding this comment.
Other important examples are Dependency Injection frameworks.
docs/topics/annotations.md
Outdated
| Annotations are a means of attaching metadata to code. To declare an annotation, put the `annotation` modifier in front of a class: | ||
| Annotations are tags used to attach metadata to code. They provide additional information about tagged code elements without altering the program's execution. | ||
|
|
||
| Annotations are used by the compiler and runtime processors to simplify and automate common tasks, such as generating boilerplate code, enforcing coding standards or writing documentation. |
There was a problem hiding this comment.
Same as before: some annotations are also visible during runtime (there's a specific retention for this), and they are widely used in the JVM world.
serras
left a comment
serras
left a comment
There was a problem hiding this comment.
The current text make it seem like annotations are a compile-only thing, when in fact they are also very important at runtime.
sarahhaggarty
left a comment
sarahhaggarty
left a comment
There was a problem hiding this comment.
Nice start! I made some suggestions to make the text more active, simplify some of the wording, and connect the first two parts a bit better. Ping me if anything is unclear or you have questions! :)
docs/topics/annotations.md
Outdated
| [//]: # (title: Annotations) | ||
|
|
||
| Annotations are a means of attaching metadata to code. To declare an annotation, put the `annotation` modifier in front of a class: | ||
| Annotations are tags used to attach metadata to source code. |
There was a problem hiding this comment.
You use some passive constructions. Can you make it more active by making it clear what the active subject is? For example, here it could be: "Annotations are tags that you can use to attach metadata to your code."
docs/topics/annotations.md
Outdated
| Annotations are a means of attaching metadata to code. To declare an annotation, put the `annotation` modifier in front of a class: | ||
| Annotations are tags used to attach metadata to source code. | ||
|
|
||
| During compilation and runtime, annotations are processed by different tools and frameworks to simplify and automate common tasks, such as generating boilerplate code, enforcing coding standards or writing documentation. |
There was a problem hiding this comment.
Can you combine this with the first sentence? The first sentence explains about how annotations add metadata so it would be nice to understand how that metadata is used in the following sentence. For example, by a processor to generate additional code.
This sentence is also quite long so please break it into two :)
docs/topics/annotations.md
Outdated
|
|
||
| During compilation and runtime, annotations are processed by different tools and frameworks to simplify and automate common tasks, such as generating boilerplate code, enforcing coding standards or writing documentation. | ||
|
|
||
| > To learn more about annotation processing in Kotlin, see [KSP](ksp-overview.md) |
There was a problem hiding this comment.
Can you introduce KSP as an acronym here? :)
Also, "annotation processing" isn't easy for a beginner to understand so could it be explained more simply like "If you want to generate code from annotations, Kotlin provides Kotlin Symbol Processing (KSP)."?
There was a problem hiding this comment.
Here I am in doubt because beginners reading about annotations are likely to be using external annotation processors, and therefore not need KSP at all. They will just need to annotate their code in the way the processor they want to use tells them to, and if they set up the processor the code will be generated.
KSP is mostly relevant to people who want to develop their own processor, and for whom the phrase "annotation processor" is clear. So I think if the specific phrase is not there they might not realize that KSP is what they need to develop those processors. I would expect a beginner to understand that this note is related to a more advanced subject and skip it. I'll try to make that more explicit. How about "when you're ready to develop your own annotation processors, you can use the Kotlin Symbol Processing (KSP) API"?
docs/topics/annotations.md
Outdated
|
|
||
| ## Declaration | ||
|
|
||
| To declare an annotation, put the `annotation` modifier in front of a class: |
There was a problem hiding this comment.
| To declare an annotation, put the `annotation` modifier in front of a class: | |
| Annotations are a special type of class. To declare an annotation, use the `annotation` keyword before the class declaration: |
Outside of the scope I shared. But since we're here!
sarahhaggarty
left a comment
sarahhaggarty
left a comment
There was a problem hiding this comment.
Nice! Just one last suggestion but then LGTM!
Co-authored-by: Sarah Haggarty <81160244+sarahhaggarty@users.noreply.github.com>
3 participants
Re: KT-84121