valid_docs rule shouldn't be enforced for common UIKit method overrides

[litso]

For example if I override shouldAutoroate I shouldn't have to document the return type.

        override func shouldAutorotate() -> Bool {
            return false
        }

[keith]

I brought this up somewhere but IMO we should ignore everything that is an override

[proth]

I think so too

[jpsim]

The missing_docs rule actually skips all overridden declarations, but the valid_docs rule validates all documentation-style comments (/// and /** */).

So what's the motivating factor for writing documentation-style comments for an overridden declaration without those docs being fully valid? If it's a note on the implementation to developers (e.g. not users of the API), then why not use a regular style comment? If it is for users of the API, the docs should be complete, no?

[Sega-Zero]

I have slightly different case with the same warning. Having this protocol and implementation:

/// test proto description
public protocol TestProto {
    /// - Returns: some string
    /// - Parameter sampleParam: yet another parameter
    func sampleFunc(sampleParam: String) -> String
}

/// Sample proto documentation
public struct SampleStruct: TestProto {
    /// - seealso: `TestProto`
    public func sampleFunc(sampleParam: String) -> String {
        return ""
    }
}

I use jazzy for doc generation, SampleStruct is the part of my public API and should be documented. Why do I get a warning on SampleStruct.sampleFunc(_:) implementation?

[jpsim]

Why do I get a warning on SampleStruct.sampleFunc(_:) implementation?

Because it is only partially documented.

[Sega-Zero]

Ok, what should be added to make it go away?

[Sega-Zero]

I don't mind to duplicate the description from the protocol, but that's as weird as documenting the method override, i think.

[norio-nomura]

Ok, what should be added to make it go away?

@Sega-Zero Current valid_docs rules implementation is case sensitive and expecting lower case keywords such as parameter or returns.
It seems that Xcode ignores case of them, so we need to fixing SwiftLint.

[pcantrell]

Note that Swiftlint insisting on parameter and returns sections to match the method signature is contrary to Apple’s API design guidelines:

(This is under “Make documentation comments tool-friendly.”)

[jpsim]

Thanks for sharing that link @pcantrell. I've been struggling with this since originally writing the rule, where it's not always appropriate to follow the Swift documentation syntax exactly. Of course, it's always possible to just disable a rule, either locally or globally, but I'm open to loosening the constraints on the valid docs rule to reduce the number of false violations.

[pcantrell]

It’s the inherent problem of linting tools: the rules that are truly absolute tend to be fairly mindless. Most fall into a nuanced area that requires some human judgement, and deciding where to draw the linter line is a tricky call!

[marcelofabri]

Closing this since we removed this rule.