@@ -8,15 +8,14 @@
 import java.util.Objects;
 
 /**
- * Accumulator that deduplicates SCIP {@link Occurrence} entries by their {@code (symbol, range,
- * roles)} key. Variants that differ only in whether {@code enclosing_range} is set are collapsed,
- * preferring the one that carries the enclosing range.
+ * Accumulator that deduplicates SCIP {@link Occurrence} entries by {@code (symbol, range, roles)}.
+ * Variants differing only in whether {@code enclosing_range} is set are collapsed, preferring the
+ * one that carries it.
  */
 final class ScipOccurrences {
 
   private final LinkedHashMap<Key, Occurrence> out = new LinkedHashMap<>();
 
-  /** Adds {@code occ}, collapsing it into any existing entry with the same {@link Key}. */
   void add(Occurrence occ) {
     Key key = Key.of(occ);
     Occurrence existing = out.get(key);
@@ -29,12 +28,10 @@ void add(Occurrence occ) {
     }
   }
 
-  /** Adds every occurrence in {@code occs}. */
   void addAll(Iterable<Occurrence> occs) {
     for (Occurrence occ : occs) add(occ);
   }
 
-  /** Returns the deduplicated occurrences in insertion order. */
   Collection<Occurrence> values() {
     return out.values();
   }
 
@@ -16,21 +16,13 @@
 import java.util.Map;
 
 /**
- * Writes and merges per-source SCIP shards produced by the compiler plugin.
- *
- * <p>Each source file produces a self-contained {@link Index} shard containing a single {@link
- * Document}. When a shard already exists on disk (e.g. during annotation processing rounds), the
- * new document is merged into the existing one, deduplicating occurrences, symbols and
- * relationships.
+ * Writes a per-source SCIP shard, merging it with any pre-existing shard at the same path (e.g. one
+ * written by a prior annotation-processing round).
  */
 public final class ScipShardWriter {
 
   private ScipShardWriter() {}
 
-  /**
-   * Writes the given {@code shard} to {@code output}, creating parent directories as needed. If
-   * {@code output} already exists, the existing shard is parsed and merged with the new one.
-   */
   public static void writeOrMerge(Path output, Index shard) throws IOException {
     Files.createDirectories(output.getParent());
     if (Files.exists(output)) {
@@ -43,10 +35,7 @@ public static void writeOrMerge(Path output, Index shard) throws IOException {
     Files.write(output, shard.toByteArray());
   }
 
-  /**
-   * Merges two SCIP shards by combining their document lists. Documents that share a {@code
-   * relative_path} have their occurrences, symbols and external symbols deduplicated.
-   */
+  /** Merges two shards: documents sharing a {@code relative_path} are dedup-merged. */
   static Index merge(Index a, Index b) {
     Index.Builder builder = Index.newBuilder();
     if (b.hasMetadata()) {
@@ -69,7 +58,7 @@ static Index merge(Index a, Index b) {
     }
     builder.addAllDocuments(byPath.values());
 
-    // External symbols: deduplicate by symbol string. Last writer wins to keep latest data.
+    // External symbols: last writer wins to keep the most recent data.
     LinkedHashMap<String, SymbolInformation> externals = new LinkedHashMap<>();
     for (SymbolInformation s : a.getExternalSymbolsList()) externals.put(s.getSymbol(), s);
     for (SymbolInformation s : b.getExternalSymbolsList()) externals.put(s.getSymbol(), s);
@@ -79,18 +68,15 @@ static Index merge(Index a, Index b) {
   }
 
   private static Document mergeDocuments(Document a, Document b) {
+    // b.toBuilder() carries forward the most recent language/relative_path/text/encoding.
     Document.Builder builder = b.toBuilder().clearOccurrences().clearSymbols();
-    // Use the most recent metadata for language/relative_path/text/encoding which already
-    // come from b via toBuilder().
 
-    // Deduplicate occurrences by (range, symbol, roles). Variants that differ only in
-    // enclosing_range get collapsed, preferring the one that carries the enclosing range.
     ScipOccurrences occurrences = new ScipOccurrences();
     occurrences.addAll(a.getOccurrencesList());
     occurrences.addAll(b.getOccurrencesList());
     builder.addAllOccurrences(occurrences.values());
 
-    // Deduplicate symbols by symbol string; merge relationships and documentation.
+    // Dedup symbols by symbol string; merge relationships and documentation.
     Map<String, SymbolInformation> bySymbol = new LinkedHashMap<>();
     for (SymbolInformation info : a.getSymbolsList()) bySymbol.put(info.getSymbol(), info);
     for (SymbolInformation info : b.getSymbolsList()) {
@@ -104,12 +90,12 @@ private static Document mergeDocuments(Document a, Document b) {
 
   private static SymbolInformation mergeSymbol(SymbolInformation a, SymbolInformation b) {
     SymbolInformation.Builder builder = b.toBuilder();
-    // Merge relationships, deduplicating by structural equality with deterministic ordering.
+    // Dedup relationships by structural equality; preserve insertion order.
     LinkedHashSet<Relationship> rels = new LinkedHashSet<>(a.getRelationshipsList());
     rels.addAll(b.getRelationshipsList());
     builder.clearRelationships().addAllRelationships(rels);
 
-    // Merge documentation, preserving order and avoiding duplicates.
+    // Dedup documentation; preserve insertion order.
     List<String> docs = new ArrayList<>(a.getDocumentationList());
     for (String d : b.getDocumentationList()) {
       if (!docs.contains(d)) docs.add(d);
 
@@ -53,11 +53,9 @@
 import javax.tools.Diagnostic;
 
 /**
- * Walks the AST of a typechecked compilation unit and generates a {@link Document} directly.
- *
- * <p>Symbols are produced through {@link GlobalSymbolsCache} and then translated to the placeholder
- * SCIP form via {@link ScipSymbols#fromSemanticdbSymbol(String)}. Signature documentation is
- * produced by {@link ScipSignatureFormatter} directly from javac's element model.
+ * Walks a typechecked compilation unit and builds a {@link Document}. Symbols come from {@link
+ * GlobalSymbolsCache} via {@link ScipSymbols#fromSemanticdbSymbol(String)} and signatures from
+ * {@link ScipSignatureFormatter}.
  */
 public final class ScipVisitor extends TreePathScanner<Void, Void> {
 
@@ -111,12 +109,7 @@ public Index buildShard() {
     return Index.newBuilder().addDocuments(document).build();
   }
 
-  /** SCIP {@code Document.language} value for Java sources. */
-  static final String LANGUAGE_JAVA = "java";
-
-  // ==========================
-  // Symbol/occurrence emission
-  // ==========================
+  private static final String LANGUAGE_JAVA = "java";
 
   private Optional<ScipRange> emitSymbolOccurrence(
       Element sym, Tree tree, Name name, int roles, CompilerRange kind) {
@@ -243,10 +236,6 @@ private static boolean supportsReferenceRelationship(Element sym) {
     }
   }
 
-  // =================================================
-  // Kind translation for SCIP emission.
-  // =================================================
-
   private static SymbolInformation.Kind scipKind(Element sym) {
     Set<Modifier> modifiers = sym.getModifiers();
     boolean isStatic = modifiers.contains(Modifier.STATIC);
@@ -288,10 +277,6 @@ private static SymbolInformation.Kind scipKind(Element sym) {
     }
   }
 
-  // ===========================================
-  // Node resolution and traversal
-  // ===========================================
-
   void resolveNodes() {
     HashSet<Tree> ignoreNodes = new HashSet<>();
     for (Tree node : nodes.keySet()) {
@@ -476,10 +461,6 @@ private void resolveNewClassTree(NewClassTree node, TreePath treePath) {
     }
   }
 
-  // =================================================
-  // Symbol / range helpers used by the SCIP emission path.
-  // =================================================
-
   private String semanticdbSymbol(Element sym) {
     return globals.semanticdbSymbol(sym, locals);
   }
 
@@ -16,10 +16,7 @@ import org.jetbrains.kotlin.config.CommonConfigurationKeys
 import org.jetbrains.kotlin.config.CompilerConfiguration
 import org.jetbrains.kotlin.ir.declarations.IrModuleFragment
 
-/**
- * IR generation extension that runs after FIR analysis to write the per-source SCIP shards
- * collected by [SemanticdbVisitor]. The legacy SemanticDB protobuf output has been removed.
- */
+/** Writes the per-source SCIP shards collected by [SemanticdbVisitor] after FIR analysis. */
 class PostAnalysisExtension(
     private val sourceRoot: Path,
     private val targetRoot: Path,
 
@@ -3,16 +3,14 @@ package com.sourcegraph.semanticdb_kotlinc
 import org.scip_code.scip.Occurrence
 
 /**
- * Accumulator that deduplicates SCIP [Occurrence] entries by their `(symbol, range, roles)` key.
- * Variants that differ only in whether `enclosing_range` is set are collapsed, preferring the one
- * that carries the enclosing range. Mirrors the Java `ScipOccurrences` accumulator used by the
- * javac plug-in.
+ * Accumulator that deduplicates SCIP [Occurrence] entries by `(symbol, range, roles)`. Variants
+ * differing only in whether `enclosing_range` is set are collapsed, preferring the one that
+ * carries it. Mirrors the Java `ScipOccurrences` accumulator.
  */
 internal class ScipOccurrences {
 
     private val out = LinkedHashMap<Key, Occurrence>()
 
-    /** Adds [occ], collapsing it into any existing entry with the same [Key]. */
     fun add(occ: Occurrence) {
         val key = Key.of(occ)
         val existing = out[key]
@@ -25,7 +23,6 @@ internal class ScipOccurrences {
         }
     }
 
-    /** Returns the deduplicated occurrences in insertion order. */
     fun values(): Collection<Occurrence> = out.values
 
     private data class Key(val symbol: String, val range: List<Int>, val roles: Int) {
 
@@ -1,34 +1,15 @@
 package com.sourcegraph.semanticdb_kotlinc
 
 /**
- * Helpers for emitting SCIP symbol strings from the Kotlin compiler plug-in.
- *
- * Mirrors the Java `ScipSymbols` helper. Because the compiler plug-in does not know the final
- * Maven coordinates (`groupId:artifactId:version`) at compile time, it emits global symbols using
- * a sentinel placeholder scheme that is rewritten by the aggregator to its final form:
- *
- *   `. . . . ` + <semanticdb-style descriptor path>
- *      ->  "scip-java maven <groupId> <artifactId> <version> <descriptor path>"
- *
- * Local symbols are emitted using the canonical SCIP `local N` form (with the space) and are NOT
- * rewritten by the aggregator.
+ * Converts SemanticDB-style symbol strings into the placeholder SCIP form expected by the
+ * aggregator: globals are prefixed with [PLACEHOLDER_PREFIX] (rewritten to
+ * `scip-java maven <g> <a> <v> <descriptor>` once coordinates are known), locals use the canonical
+ * `local N` form and pass through unchanged. Mirrors the Java `ScipSymbols` helper.
  */
 object ScipSymbols {
 
-    /**
-     * Prefix marking a global symbol whose package coordinates must be filled in by the aggregator.
-     * The trailing space matches the SCIP grammar requirement of separating the scheme from the
-     * package fields.
-     */
     const val PLACEHOLDER_PREFIX: String = ". . . . "
 
-    /**
-     * Converts a SemanticDB-style [Symbol] into the SCIP symbol form expected by the aggregator.
-     *
-     *   - [Symbol.NONE] becomes the empty string.
-     *   - Local symbols of the form `local42` become `local 42`.
-     *   - Everything else is prefixed with [PLACEHOLDER_PREFIX].
-     */
     fun fromSemanticdbSymbol(symbol: Symbol): String {
         if (symbol == Symbol.NONE) return ""
         val raw = symbol.toString()
 
@@ -22,15 +22,9 @@ import org.jetbrains.kotlin.lexer.KtTokens
 import org.jetbrains.kotlin.text
 
 /**
- * Builds a single-document [Index] shard for one Kotlin source file from per-element callbacks
- * fired by [SemanticdbVisitor].
- *
- * Symbols are emitted using the placeholder scheme [ScipSymbols.PLACEHOLDER_PREFIX]; the
- * `scip-aggregator` rewrites them into final `scip-java maven g a v ...` form once Maven
- * coordinates are resolved.
- *
- * Signature documentation is rendered directly via [FirRenderer] (Kotlin's built-in declaration
- * renderer) and assigned to `SymbolInformation.signature_documentation.text` as raw Kotlin source.
+ * Builds a single-document [Index] shard for one Kotlin source from callbacks fired by
+ * [SemanticdbVisitor]. Symbols use the [ScipSymbols.PLACEHOLDER_PREFIX] scheme; signature
+ * documentation is rendered via [FirRenderer] as raw Kotlin source.
  */
 @ExperimentalContracts
 class ScipTextDocumentBuilder(
@@ -39,8 +33,7 @@ class ScipTextDocumentBuilder(
     private val relativePath: String,
 ) {
     private val occurrences = ScipOccurrences()
-    // Keyed by symbol string so re-encounters of the same definition (multi-round compilation,
-    // synthetic accessors) do not produce duplicate entries.
+    // Keyed by symbol so re-encounters (multi-round compilation, synthetic accessors) don't dup.
     private val symbols = LinkedHashMap<String, SymbolInformation>()
 
     fun buildIndex(): Index =
@@ -125,7 +118,7 @@ class ScipTextDocumentBuilder(
                     .setIsReference(supportsRefRel))
         }
 
-        // Last write wins so newly discovered metadata takes precedence.
+        // Last write wins: newly discovered metadata takes precedence.
         symbols[scipSymbolStr] = builder.build()
     }
 
@@ -161,8 +154,7 @@ class ScipTextDocumentBuilder(
         val startLine = lineMap.lineNumber(element) - 1
         val startCharacter = lineMap.startCharacter(element)
         val endCharacter = lineMap.endCharacter(element)
-        // SemanticDB visitor only emits single-line ranges, so the SCIP compact 3-int range
-        // form is sufficient here.
+        // SemanticdbVisitor only emits single-line ranges, so 3 ints suffice.
         return listOf(startLine, startCharacter, endCharacter)
     }
 
@@ -195,11 +187,7 @@ class ScipTextDocumentBuilder(
         return stripKDocAsterisks(kdoc)
     }
 
-    /**
-     * Returns the kdoc string with all leading and trailing slash/asterisk tokens removed. Naive
-     * implementation that can be replaced with a utility method from the compiler in the future,
-     * if one exists.
-     */
+    /** Strips leading/trailing slash and asterisk tokens from each line of a kdoc string. */
     private fun stripKDocAsterisks(kdoc: String): String {
         if (kdoc.isEmpty()) return kdoc
         val out = StringBuilder()
@@ -236,9 +224,7 @@ class ScipTextDocumentBuilder(
     }
 
     companion object {
-        // SCIP `Document.language` value; lowercased to match the SCIP convention used by
-        // existing aggregator code.
-        const val LANGUAGE_KOTLIN: String = "kotlin"
+        private const val LANGUAGE_KOTLIN: String = "kotlin"
 
         @OptIn(SymbolInternals::class)
         private fun displayName(
@@ -286,8 +272,7 @@ class ScipTextDocumentBuilder(
                 else -> SymbolInformation.Kind.UnspecifiedKind
             }
 
-        // Renders declarations as Kotlin source text — no markdown fence — and puts them into
-        // SymbolInformation.signature_documentation.text.
+        // Renders declarations as raw Kotlin source for SymbolInformation.signature_documentation.
         private val renderer: FirRenderer
             get() =
                 FirRenderer(
 
@@ -16,9 +16,8 @@ import org.jetbrains.kotlin.fir.symbols.impl.FirClassLikeSymbol
 import org.jetbrains.kotlin.name.FqName
 
 /**
- * Walks the FIR analysis tree for a single Kotlin source file and builds a self-contained
- * `Index` shard via [ScipTextDocumentBuilder]. The legacy SemanticDB protobuf path has been
- * removed; the visitor only emits SCIP.
+ * Walks the FIR analysis tree of a Kotlin source and builds a self-contained `Index` shard via
+ * [ScipTextDocumentBuilder].
  */
 @ExperimentalContracts
 class SemanticdbVisitor(