saveourtool/diktat

A generic type parameter in Kdoc should not be reported

Open

#1,929 opened on Apr 8, 2024

View on GitHub
 (4 comments) (2 reactions) (0 assignees)Kotlin (40 forks)github user discovery
buggood first issue

Repository metrics

Stars
 (571 stars)
PR merge metrics
 (PR metrics pending)

Description

Describe the bug

When documenting a type parameter in Kdoc, the only correct way to do it is using the @param tag, for example:

/**
 * @param T the target type to return
 */
fun <T> genericFunc(): T

Unfortunately Diktat reports:

[KDOC_WITHOUT_PARAM_TAG] all methods which take arguments should have @param tags in KDoc: T param isn't present in argument list

Which I believe is a wrong behavior, given that it's taking into consideration the formal parameters only.

Expected behavior

Diktat should not report a violation for the above example.

Observed behavior

Diktat reports a KDOC_WITHOUT_PARAM_TAG

Environment information

  • diktat version: 2.0.0
  • build tool (maven/gradle): gradle
  • how is diktat run (CLI, plugin, etc.): plugin
  • kotlin version: 1.9.23
  • operating system: MacOS 14.3.1

Contributor guide

Research direction
Investigate the KDOC WITHOUT PARAM TAG rule to understand how it counts parameters. The issue is that it incorrectly includes generic type parameters (e.g., <T>) as method parameters. The fix should exclude type parameters from the check.
Tech stack
kotlin
Domain
devtools
Issue type
Bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Kotlin
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70