Report KDoc comments that refer to non-public properties of a class

[VitalyVPinchuk]

New rule to address the issue (#4462) of breaking encapsulation principle when KDoc comments have references to non-public properties.
Clients do not need to know the implementation details.

Screenshot

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
detekt	❌ Failed (Inspect)		Apr 26, 2022 at 8:46PM (UTC)

[cortinico]

Thanks for adding this 👍

[vercel]

@VitalyVPinchuk is attempting to deploy a commit to the Detekt Team on Vercel.

A member of the Team first needs to authorize it.

[marschwar]

Just curious - Should this rule also check the KDoc of methods and properties to verify it is not leaking private information?

class C {
    private var a: Int = 0

    /**
     * Mentioning [a]
     */
    val b = "string"

    /**
     * Mentioning [a]
     */
    fun foo() {
        print("foo $a")
    }
}

[VitalyVPinchuk]

Just curious - Should this rule also check the KDoc of methods and properties to verify it is not leaking private information?

I think it's a good idea!
Should I add these checks?

[marschwar]

Should I add these checks?

If you think they are valid, you could do so. I am just afraid that the rule will become overly complicated and hard to maintain.

To be absolutely honest, I am not the biggest fan of documentation rules to begin with. Since you brought up the issue, you seem to have a clear use case.

[codecov]

Codecov Report

Merging #4768 (4679ae2) into main (7960453) will increase coverage by 0.06%.
The diff coverage is 100.00%.

@@             Coverage Diff              @@
##               main    #4768      +/-   ##
============================================
+ Coverage     84.69%   84.76%   +0.06%     
- Complexity     3418     3447      +29     
============================================
  Files           490      492       +2     
  Lines         11235    11302      +67     
  Branches       2068     2080      +12     
============================================
+ Hits           9516     9580      +64     
+ Misses          675      673       -2     
- Partials       1044     1049       +5     

Impacted Files	Coverage Δ
...etekt/generator/printer/defaultconfig/Exclusion.kt	96.77% <100.00%> (+0.10%)	⬆️
...detekt/rules/documentation/CommentSmellProvider.kt	100.00% <100.00%> (ø)
...s/documentation/KDocReferencesNonPublicProperty.kt	100.00% <100.00%> (ø)
...coroutines/SuspendFunWithCoroutineScopeReceiver.kt	80.00% <0.00%> (-3.34%)	⬇️
...gitlab/arturbosch/detekt/rules/style/UseOrEmpty.kt	74.07% <0.00%> (-3.01%)	⬇️
...lab/arturbosch/detekt/rules/style/VarCouldBeVal.kt	80.39% <0.00%> (-0.03%)	⬇️
...arturbosch/detekt/generator/printer/RulePrinter.kt	100.00% <0.00%> (ø)
...rturbosch/detekt/rules/style/StyleGuideProvider.kt	100.00% <0.00%> (ø)
...urbosch/detekt/rules/style/UnnecessaryBackticks.kt	85.00% <0.00%> (ø)
...n/io/github/detekt/report/html/HtmlOutputReport.kt	95.65% <0.00%> (+0.14%)	⬆️
... and 4 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7960453...4679ae2. Read the comment docs.

[cortinico]

If you think they are valid, you could do so. I am just afraid that the rule will become overly complicated and hard to maintain.

Agree here. I would not add those extra checks unless we have a real use case or a user need for them

[cortinico]

Code looks good to me. Just left minor comments to address