IDE highlighting ✨

.gitignore

@@ -26,3 +26,4 @@ hs_err_pid*
 /build/
 /.idea/
 /doc-processor-gradle-plugin/src/functionalTest/resources/dataframe/
+.intellijPlatform

doc-processor-common/src/main/kotlin/nl/jolanrensen/docProcessor/CompletionInfo.kt

@@ -0,0 +1,26 @@
+package nl.jolanrensen.docProcessor
+
+/**
+ * Completion info for a tag. Shows up in the completion popup.
+ *
+ * @param tag The tag name this completion info belongs to.
+ * @param blockText The text that will be inserted when the completion is performed at the start of a line.
+ * @param presentableBlockText The text that will be shown in the completion popup when the completion is performed
+ *   at the start of a line.
+ * @param moveCaretOffsetBlock The offset to move the caret to after the completion is performed at the start of a line.
+ * @param inlineText The text that will be inserted when the completion is performed in the middle of a line.
+ * @param presentableInlineText The text that will be shown in the completion popup when the completion is performed
+ *   in the middle of a line.
+ * @param moveCaretOffsetInline The offset to move the caret to after the completion is performed in the middle of a line.
+ * @param tailText The text that will be shown alongside the presentable text in the completion popup.
+ */
+class CompletionInfo(
+    val tag: String,
+    val blockText: String? = "@$tag ",
+    val presentableBlockText: String? = "@$tag",
+    val moveCaretOffsetBlock: Int? = 0,
+    val inlineText: String? = "{@$tag }",
+    val presentableInlineText: String? = "{@$tag }",
+    val moveCaretOffsetInline: Int? = -1,
+    val tailText: String = "",
+)

doc-processor-common/src/main/kotlin/nl/jolanrensen/docProcessor/DocProcessor.kt

@@ -16,7 +16,7 @@ import java.util.ServiceLoader
  */
 abstract class DocProcessor : Serializable {
 
-    protected val name: String = this::class.simpleName ?: "DocProcessor"
+    val name: String = this::class.simpleName ?: "DocProcessor"
 
     /** Main logging access point. */
     val logger: KLogger = KotlinLogging.logger(name)
@@ -58,6 +58,49 @@ abstract class DocProcessor : Serializable {
             hasRun = true
         }
     }
+
+    /**
+     * An optional list of [CompletionInfo] information to display
+     * in the autocomplete of the IDE.
+     */
+    open val completionInfos: List<CompletionInfo>
+        get() = emptyList()
+
+    /**
+     * Can be overridden to provide custom highlighting for doc content given by [docContent].
+     *
+     * NOTE: this can contain '*' characters and indents, so make sure to handle that.
+     */
+    open fun getHighlightsFor(docContent: DocContent): List<HighlightInfo> = emptyList()
+
+    /**
+     * Builds a [HighlightInfo] object with the given parameters in the context of this processor.
+     * Fills in [HighlightInfo.tagProcessorName] with the name of this processor.
+     * Builds [HighlightInfo.description] from the [completionInfos] of this processor.
+     */
+    protected fun buildHighlightInfo(
+        range: IntRange,
+        type: HighlightType,
+        tag: String,
+        description: String = completionInfos // get the description from the completion infos
+            .find { it.tag == tag }
+            ?.let {
+                "${
+                    (it.presentableBlockText ?: it.presentableInlineText)
+                        ?.surroundWith("\"")
+                        ?.plus(": ")
+                        ?: ""
+                }${it.tailText}"
+            } ?: "",
+        related: List<HighlightInfo> = emptyList(),
+    ): HighlightInfo =
+        HighlightInfo(
+            range = range,
+            type = type,
+            related = related,
+            description = description,
+            tagProcessorName = name,
+        )
 }
 
 fun findProcessors(fullyQualifiedNames: List<String>, arguments: Map<String, Any?>): List<DocProcessor> {