False positive with orphaned_doc_comment

[michaelpeternell]

New Issue Checklist

• Updated SwiftLint to the latest version
• I searched for existing GitHub issues

Describe the bug

Starting with Swiftlint 0.50.0 I am getting false positives from the orphaned_doc_comment rule

The following code triggers a rule violation:

func hello() {
    /// the text
    let text = "Swift"
    print("The text is \(text)")
}

This should not trigger, because it is perfectly valid to document a local variable or local let declaration.

Environment

• SwiftLint version 0.50.0
• Installation method used: Homebrew

[jpsim]

This is by design, but perhaps that design is flawed? What does a documentation comment provide you here over a regular comment? Does Xcode even render rich quick help documentation for this and even if it does, why is that helpful when the only usage is local?

[NachoSoto]

I just ran into the same for internal declarations:

internal class C {
  /// I want to document this method for other developers of this SDK, even if it's not exposed publically
  internal static func f() {}
}

This is still very useful, and they're visible within Xcode:

[jpsim]

@NachoSoto your issue is completely different and I agree a valid false positive.

[NachoSoto]

Do you want me to open a separate ticket for it?

[michaelpeternell]

I rarely use doc-comments on local variables, but in large codebases it sometimes happens. Like when the purpose of a variable is a little bit confusing, or in code that is very complex.

Also, Xcode does render it when autocompleting or when option-clicking.

If you don't agree that this is a false positive, then I would just disable the orphaned_doc_comment rule altogether for my projects. Because I don't want to change doc-comments to ordinary comments, and I also don't want to delete valid doc comments.

[awein]

Same here: Using doc-comments on variables is not something I use a lot but it helps to make complex code more easy to read and follow when used.
Would be nice to keep using it while keeping the (otherwise very useful) rule active.

[jpsim]

I'll split out the local doc comment validation into a separate local_scope_doc_comment rule.

I'll also make it opt-in so it's not enabled by default.

@michaelpeternell thanks for letting me know that Xcode renders quick help for local scope docstrings, I was able to confirm that in my testing too:

Naturally, this doesn't work for references, only declarations.

[jpsim]

Splitting the rule in #4581

[jpsim]

@NachoSoto please file a new issue with complete repro steps. I'm not sure what you're seeing, but tests pass for me when I add your code sample to the non-triggering examples for orphaned_doc_comment.

--- a/Source/SwiftLintFramework/Rules/Lint/OrphanedDocCommentRule.swift
+++ b/Source/SwiftLintFramework/Rules/Lint/OrphanedDocCommentRule.swift
@@ -31,6 +31,12 @@ struct OrphanedDocCommentRule: SourceKitFreeRule, ConfigurationProviderRule {
             /// Look here for more info:
             /// https://github.com.
             var myGreatProperty: String!
+            """),
+            Example("""
+            internal class C {
+              /// Some internal docs.
+              internal static func f() {}
+            }
             """)
         ],
         triggeringExamples: [

[michaelpeternell]

I've just installed Swiftlint 0.50.1

Shouldn't the following example trigger the orphaned_doc_comment rule?

struct Bar {
    var foo = 2
    func sayHello() {
        if foo == 1 {
            /// foo is 1, we therefore have to print!
            print("foo is 1!!!!")
        }
    }
}

this is clearly an invalid doc-comment, because it is not attached to a declaration.

But when I enable local_doc_comment it triggers on all doc comments in local scopes, even the ones that are valid.

Here an example of what I think should trigger and should not trigger a rule violation:

struct FooBar {
    var foo = 2
    func sayHello() {
        if foo == 1 {
            /// foo is 1, we therefore have to print! (this should trigger orphaned_doc_comment)
            print("foo is 1!!!!")
        }
        /// That doesn't need any explanation (this should NOT trigger orphaned_doc_comment)
        var someVar = foo + 1
    }
}