refactor: explicit locked detekt config (#729)

Migrate detekt to a convention plugin in `buildSrc`, switch the project
to a fully explicit YAML config (`buildUponDefaultConfig = false`), fix
the real findings that this stricter setup revealed, and remove
`@Suppress` annotations that became unnecessary after the rule changes.

## Motivation and Context
- Explicit visibility into the rule set
- Lock against detekt version upgrades

## Breaking Changes
None

## Types of changes
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update

## Checklist
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed
This commit is contained in:
Pavel Gorgulov 2026-04-29 12:31:49 +02:00 • committed by GitHub
commit 64804a05c2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -5,40 +5,62 @@ description: "Add KDoc documentation to Kotlin public API. Use whenever the user
# KDoc Generator
Add KDoc comments to public Kotlin API declarations.
Add KDoc to all public Kotlin declarations (classes, interfaces, objects, functions, properties, enums, type aliases, annotations — including `@Deprecated`). Read the implementation, not just the signature, to write accurate descriptions.
## What to document
## Tag placement
All public declarations (no explicit `private`/`internal`/`protected`):
- Classes, interfaces, objects, sealed classes/interfaces
- Functions, extension functions
- Properties
- Enum classes and entries
- Type aliases, annotation classes
| Where the declaration lives | Tag |
|---|---|
| Primary-ctor `val` / `var` (public, internal, or protected) | `@property` in class KDoc |
| Primary-ctor `name: Type` (no `val`/`var`) | `@param` in class KDoc |
| Primary-ctor `private val` / `private var` | `@param` in class KDoc |
| Body of class/object/interface/sealed interface | inline `/** */` above the declaration |
| Function parameter | `@param` |
| Non-Unit return type | `@return` |
Include `@Deprecated` elements.
## Style
## Context
- Summary: one concise sentence, third-person verb ("Creates", "Returns", "Represents"). Expand to 2-3 sentences only when genuinely complex.
- **Example block**: mandatory for DSL builders (show full receiver-scope usage); add for complex functions or non-obvious extension functions; skip for one-liners and simple getters.
- KDoc links (`[ClassName]`, `[methodName]`) only where they add navigational value.
- Don't write `@throws` or "suspend" notes.
- Rewrite existing KDoc if incomplete or low quality.
Read the implementation, not just the signature, to write accurate descriptions. Understanding what the code actually does prevents superficial or misleading documentation.
## Examples
## KDoc format
**Class/interface example:**
**Class with mixed primary-constructor parameters:**
````kotlin
/**
* Manages active client sessions and their lifecycle.
*
* Sessions are created on first connection and cleaned up
* when the transport closes.
*
* @property maxSessions upper limit on concurrent sessions
* @property timeout idle timeout before a session is evicted
* @param scope coroutine scope for session lifecycle tasks
* @param secret used internally for session token signing
*/
public class SessionManager(
public val maxSessions: Int, // public val → @property
scope: CoroutineScope, // no val/var → @param
private val secret: ByteArray, // private val → @param
)
````
**Function example:**
**Body and interface properties (inline `/** */`):**
````kotlin
/** Represents an entity that includes additional metadata. */
public interface WithMeta {
/** Optional metadata attached to this entity. */
public val meta: JsonObject?
}
public class Connection(public val id: String) {
/** Capabilities negotiated during the handshake, or `null` before initialize completes. */
public val capabilities: ServerCapabilities? get() = ...
}
````
**Function with Example block:**
````kotlin
/**
@ -46,10 +68,7 @@ Read the implementation, not just the signature, to write accurate descriptions.
*
* Example:
* ```kotlin
* server.addTool(
* name = "echo",
* description = "Echoes input back",
* ) { request ->
* server.addTool(name = "echo", description = "Echoes input back") { request ->
* CallToolResult(content = listOf(TextContent("Echo: ${request.arguments}")))
* }
* ```
@ -60,15 +79,3 @@ Read the implementation, not just the signature, to write accurate descriptions.
* @return the registered tool definition
*/
````
## Rules
- Summary: concise first sentence starting with a third-person verb ("Creates", "Returns", "Represents"). Expand to 2-3 sentences only when genuinely complex
- **@property** in class-level KDoc for all public properties (never as individual KDoc on the property); **@param** for function parameters
- **@return** for non-Unit return types
- **Example block**: add for DSL builders, complex functions, extension functions with non-obvious usage. Skip for trivial one-liners and simple getters
- **DSL builders**: always include an Example showing full usage with the receiver scope — this is critical for discoverability
- KDoc links (`[ClassName]`, `[methodName]`): only where it adds clear navigational value
- No **@throws** — don't document exceptions
- No **suspend** notes — coroutine nature is visible from the signature
- **Existing KDoc**: rewrite if incomplete (missing @param/@return/@property) or low quality