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:
parent
a238fc0a2e
commit
64804a05c2
1 changed files with 1106 additions and 507 deletions
|
|
@ -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
|
||||
Loading…
Reference in a new issue