Improve documentation about incremental processing

micronaut-projects · Sep 20, 2024 · 7e6276b · 7e6276b
1 parent 067fd50
commit 7e6276b
Show file tree

Hide file tree

Showing 6 changed files with 37 additions and 6 deletions.
diff --git a/src/main/docs/guide/configuration/propertiesFileConfiguration.adoc b/src/main/docs/guide/configuration/propertiesFileConfiguration.adoc
@@ -62,11 +62,14 @@ info:
   version: "v1.1"
 ----
 
-NOTE: So, `micronaut-openapi` expanded properties is old solution, now you can also use any properties for placeholders. For example, if you set properties without prefix `micronaut.openapi.expand` micronaut-openapi will process them as with this prefix.
+[NOTE]
+====
+So, `micronaut-openapi` expanded properties is old solution, now you can also use any properties for placeholders. For example, if you set properties without prefix `micronaut.openapi.expand` micronaut-openapi will process them as with this prefix.
 
 .openapi.properties Property Resolution without prefix
 [source,properties]
 ----
 api.version=v1.1
 openapi.description=A nice API
 ----
+====
diff --git a/src/main/docs/guide/customSerializers.adoc b/src/main/docs/guide/customSerializers.adoc
@@ -87,5 +87,7 @@ micronaut:
       io.micronaut.openapi.JAXBElement<test.mypackage.XmlElement3>: io.micronaut.openapi.MyJaxbElement3
 ----
 
-NOTE: Important!
+[IMPORTANT]
+====
 After changing these settings, a complete recompilation of the project is necessary to ensure that the new settings are applied correctly.
+====
diff --git a/src/main/docs/guide/gettingStarted.adoc b/src/main/docs/guide/gettingStarted.adoc
@@ -2,13 +2,28 @@ To get started add Micronaut's `openapi` to the annotation processor scope of yo
 
 dependency:micronaut-openapi[scope="annotationProcessor", groupId="io.micronaut.openapi"]
 
-NOTE: For Kotlin the `openapi` dependency should be in the `kapt` scope and for Groovy in the `compileOnly` scope.
+[NOTE]
+====
+For Kotlin the `openapi` dependency should be in the `kapt` or `ksp` scope and for Groovy in the `compileOnly` scope.
+====
+
+[IMPORTANT]
+====
+If you use KSP need to disable incremental processing:
+[properties]
+----
+ksp.incremental=false
+----
+====
+
 
 To use the https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations[Swagger Annotations] or Micronaut OpenAPI annotations add them to compile classpath
 
 dependency:micronaut-openapi-annotations[scope="compileOnly", groupId="io.micronaut.openapi"]
 
-NOTE: Also, do not forget that for the correct operation of the annotation processor, the correct parameter
+[NOTE]
+====
+Also, do not forget that for the correct operation of the annotation processor, the correct parameter
 names in the controllers are required, therefore it is recommended that all libraries from which you plan
 to add controllers be compiled with the `-parameters` flag. For example like this (with gradle build):
 [source,groovy]
@@ -19,3 +34,4 @@ tasks.withType(JavaCompile).configureEach {
     ]
 }
 ----
+====
diff --git a/src/main/docs/guide/kotlin.adoc b/src/main/docs/guide/kotlin.adoc
@@ -10,3 +10,12 @@ kapt {
     }
 }
 ----
+
+[IMPORTANT]
+====
+If you use KSP need to disable incremental processing:
+[properties]
+----
+ksp.incremental=false
+----
+====
diff --git a/src/main/docs/guide/openApiViews/viewsGenerationWithSystemProperties.adoc b/src/main/docs/guide/openApiViews/viewsGenerationWithSystemProperties.adoc
@@ -33,7 +33,6 @@ kapt {
         arg("micronaut.openapi.views.spec", "redoc.enabled=true,rapidoc.enabled=true,openapi-explorer.enabled=true,swagger-ui.enabled=true,swagger-ui.theme=flattop")
     }
 }
-
 ----
 or in Gradle for Java projects:
 

diff --git a/src/main/docs/guide/schemaDecorators.adoc b/src/main/docs/guide/schemaDecorators.adoc
@@ -24,5 +24,7 @@ micronaut.openapi.schema-postfix.org.api.v1_0_0=1_0_0
 micronaut.openapi.schema-postfix.org.api.v2_0_0=2_0_0
 ----
 
-NOTE: Important!
+[IMPORTANT]
+====
 After changing these settings, a complete recompilation of the project is necessary to ensure that the new settings are applied correctly.
+====