From 86925cbfa6d02b5d80a40ae548e80b47901e462c Mon Sep 17 00:00:00 2001
From: Eduardo Fonseca <edrd.fons@gmail.com>
Date: Sat, 20 Feb 2021 12:26:34 -0300
Subject: [PATCH] Update docs regarding SymbolProcessorProvider

---
 README.md                                     | 30 ++++++++++++++-----
 .../ksp/processing/SymbolProcessorProvider.kt | 23 ++++++++++----
 docs/quickstart.md                            | 12 ++++----
 3 files changed, 45 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 2956487e12..0cb201b4dc 100644
--- a/README.md
+++ b/README.md
@@ -93,18 +93,28 @@ KSFile
 This view lists common things that are declared in the file--classes,
 functions, properties, and so on.
 
-## SymbolProcessor: The entry point
+## SymbolProcessorProvider: The entry point
 
-Every processor in KSP implements `SymbolProcessor`:
+KSP expects an implementation of the `SymbolProcessorProvider` interface to instantiate `SymbolProcessor`:
+
+```kotlin
+interface SymbolProcessorProvider {
+    fun create(
+        options: Map<String, String>,
+        kotlinVersion: KotlinVersion,
+        codeGenerator: CodeGenerator,
+        logger: KSPLogger
+    ): SymbolProcessor
+}
+```
+
+While `SymbolProcessor` is defined as:
 
 ```kotlin
 interface SymbolProcessor {
-    fun init(options: Map<String, String>,
-             kotlinVersion: KotlinVersion,
-             codeGenerator: CodeGenerator,
-             logger: KSPLogger)
-    fun process(resolver: Resolver) // Let's focus on this
-    fun finish()
+    fun process(resolver: Resolver): List<KSAnnotated> // Let's focus on this
+    fun finish() {}
+    fun onError() {}
 }
 ```
 
@@ -136,6 +146,10 @@ class HelloFunctionFinderProcessor : SymbolProcessor() {
         }
     }
     ...
+    
+    class Provider : SymbolProcessorProvider {
+        override fun create(...): SymbolProcessor = ...
+    }
 }
 ```
 ## Resources
diff --git a/api/src/main/kotlin/com/google/devtools/ksp/processing/SymbolProcessorProvider.kt b/api/src/main/kotlin/com/google/devtools/ksp/processing/SymbolProcessorProvider.kt
index 6cbf3b0858..0e2ede24b3 100644
--- a/api/src/main/kotlin/com/google/devtools/ksp/processing/SymbolProcessorProvider.kt
+++ b/api/src/main/kotlin/com/google/devtools/ksp/processing/SymbolProcessorProvider.kt
@@ -1,10 +1,21 @@
 package com.google.devtools.ksp.processing
 
+/**
+ * [SymbolProcessorProvider] is the interface used by plugins to integrate into Kotlin Symbol Processing.
+ */
 interface SymbolProcessorProvider {
-  fun create(
-    options: Map<String, String>,
-    kotlinVersion: KotlinVersion,
-    codeGenerator: CodeGenerator,
-    logger: KSPLogger
-  ): SymbolProcessor
+    /**
+    * Called by Kotlin Symbol Processing to create the processor.
+    *
+    * @param options passed from command line, Gradle, etc.
+    * @param kotlinVersion language version of compilation environment.
+    * @param codeGenerator creates managed files.
+    * @param logger for logging to build output.
+    */
+    fun create(
+        options: Map<String, String>,
+        kotlinVersion: KotlinVersion,
+        codeGenerator: CodeGenerator,
+        logger: KSPLogger
+    ): SymbolProcessor
 }
diff --git a/docs/quickstart.md b/docs/quickstart.md
index ea622cbada..94684ef93d 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -40,17 +40,17 @@
   }
   ```
 
-* The processor you're writing needs to implement [`com.google.devtools.ksp.processing.SymbolProcessor`](../api/src/main/kotlin/com/google/devtools/ksp/processing/SymbolProcessor.kt).
+* The processor you're writing needs to implement [`com.google.devtools.ksp.processing.SymbolProcessorProvider`](../api/src/main/kotlin/com/google/devtools/ksp/processing/SymbolProcessorProvider.kt).
   Note the following:
-  * Your main logic should be in the `process()` method.
-  * Use `CodeGenerator` in the `init()` method for code generation. You can also save
-    the `CodeGenerator` instance for later use in either `process()` or `finish()`.
+  * Your main logic should be in the `SymbolProcessor#process()` method.
+  * Capture any dependencies your processor needs (e.g. `CodeGenerator`) by passing
+    them to your implementation of `SymbolProcessor` through `SymbolProcessorProvider#create()`.
   * Use `resolver.getSymbolsWithAnnotation()` to get the symbols you want to process, given
     the fully-qualified name of an annotation.
   * A common use case for KSP is to implement a customized visitor (interface
     `com.google.devtools.ksp.symbol.KSVisitor`) for operating on symbols. A simple template
     visitor is `com.google.devtools.ksp.symbol.KSDefaultVisitor`.
-  * For sample implementations of the `SymbolProcessor` interface, see the following files
+  * For sample implementations of the `SymbolProcessorProvider` and `SymbolProcessor` interfaces, see the following files
     in the sample project.
     * `src/main/kotlin/BuilderProcessor.kt`
     * `src/main/kotlin/TestProcessor.kt`
@@ -144,7 +144,7 @@
 </details>
 
 ## Pass Options to Processors
-Processor options in `SymbolProcessor.init(options: Map<String, String>, ...)` are specified in gradle build scripts:
+Processor options in `SymbolProcessorProvider.create(options: Map<String, String>, ...)` are specified in gradle build scripts:
 ```
   ksp {
     arg("option1", "value1")