Merge pull request #17 from micronaut-projects/add-docs

docs: Add some docs

gradle.properties

@@ -1,8 +1,8 @@
 projectVersion=1.0.0-SNAPSHOT
 projectGroup=io.micronaut.sourcegen
 
-title=Micronaut Sourcegen
-projectDesc=Compilation time source code generators
+title=Compilation time source code generators
+projectDesc=Micronaut SourceGen exposes a language-neutral API for source code generation.
 projectUrl=https://micronaut.io
 githubSlug=micronaut-projects/micronaut-sourcegen
 developers=Denis Stepanov

src/main/docs/guide/annotations.adoc

@@ -0,0 +1,32 @@
+The module Micronaut SourceGen annotations ships with annotations which you can use in your projects:
+
+To use them, you need the following dependency:
+
+dependency:micronaut-sourcegen-annotations[groupId=io.micronaut.sourcegen]
+
+dependency:micronaut-sourcegen-annotations[groupId=io.micronaut.sourcegen,scope=annotationProcessor]
+
+[options="header"]
+|===
+| Annotation | Description
+
+| api:sourcegen.annotations.Builder[]
+| Create a builder of the annotated type.
+|===
+
+
+If you annotate a Java Record with `@Builder`, a `PersonBuilder` class is generated at compliation-time.
+
+[source,java]
+----
+include::test-suite-java/src/main/java/io/micronaut/sourcegen/example/Person.java[tags=clazz,indent=0]
+----
+
+You can use a https://blogs.oracle.com/javamagazine/post/exploring-joshua-blochs-builder-design-pattern-in-java[builder pattern] to create a `Person` instance:
+
+[source,java]
+----
+include::test-suite-java/src/test/java/io/micronaut/sourcegen/example/PersonBuilderTest.java[tags=test,indent=0]
+----
+
+NOTE: The https://github.com/micronaut-projects/micronaut-sourcegen/blob/master/sourcegen-generator/src/main/java/io/micronaut/sourcegen/generator/visitors/BuilderAnnotationVisitor.java[BuilderAnnotationVisitor] is an example of how to use the Micronaut SourceGen API.

src/main/docs/guide/introduction.adoc

@@ -1 +1 @@
-TODO
+Micronaut SourceGen exposes a language-neutral API for source code generation. It uses https://github.com/square/javapoet[JavaPoet] internally.

src/main/docs/guide/toc.yml

@@ -1,7 +1,6 @@
 introduction:
   title: Introduction
 releaseHistory: Release History
-quickStart:
-  title: Quick Start
+annotations: Annotations
 repository: Repository
 

test-suite-java/src/main/java/io/micronaut/sourcegen/example/Person.java

@@ -16,8 +16,10 @@
 package io.micronaut.sourcegen.example;
 
 
+//tag::clazz[]
 import io.micronaut.sourcegen.annotations.Builder;
 
 @Builder
 public record Person(Long id, String name) {
 }
+//end::clazz[]

test-suite-java/src/test/java/io/micronaut/sourcegen/example/PersonBuilderTest.java

@@ -20,6 +20,8 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
 class PersonBuilderTest {
+
+//tag::test[]
     @Test
     public void buildsPerson() {
         var person = PersonBuilder.builder()
@@ -29,4 +31,5 @@ public void buildsPerson() {
         assertEquals("Cédric", person.name());
         assertEquals(123L, person.id());
     }
+//end::test[]
 }