Improve documentation about incremental processing

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

Hide file tree

Showing 6 changed files with 47 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,33 @@ 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]
+====
+Unfortunately, this annotation processor may not work correctly with incremental processing. Therefore, we recommend disabling incremental processing for KSP or KAPT:
+
+[properties]
+----
+# for KAPT
+kotlin.incremental=false
+
+# for KSP
+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 +39,4 @@ tasks.withType(JavaCompile).configureEach {
     ]
 }
 ----
+====
diff --git a/src/main/docs/guide/kotlin.adoc b/src/main/docs/guide/kotlin.adoc
@@ -10,3 +10,17 @@ kapt {
     }
 }
 ----
+
+[IMPORTANT]
+====
+Unfortunately, this annotation processor may not work correctly with incremental processing. Therefore, we recommend disabling incremental processing for KSP or KAPT:
+
+[properties]
+----
+# for KAPT
+kotlin.incremental=false
+
+# for KSP
+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.
+====