Rule Request: [ValidDocs] (bring it back)

New Issue Checklist

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

New rule request

Please describe the rule idea, format
this issue's title as Rule Request: [Rule Name] and describe:

1. Why should this rule be added? Share links to existing discussion about what
   the community thinks about this.

It would be possible to lint the documentation. This rule was added back in 2015 https://github.com/realm/SwiftLint/pull/225 and removed in 2017 https://github.com/realm/SwiftLint/pull/1455. Would it be possible to have it back?

2. Provide several examples of what would and wouldn't trigger violations.

wouldn't:

    /// This is a function
    ///
    /// - Parameters:
    ///   - parameter1: this is parameter1
    ///   - parameter2: this is parameter2
    static func function(parameter1: String, parameter2: String) {
        print("Hello world")
    }

would:

• Function with documentation, where the parameter names do not match the function parameter names:

    /// This is a function
    ///
    /// - Parameters:
    ///   - parameter1: this is parameter1
    ///   - parameter2: this is parameter2
    static func function(parameter1: String, otherParameterName: String) {
        print("Hello world")
    }

• Function with documentation, where the documented parameters do not match the function parameters, or the order does not match:

    /// This is a function
    ///
    /// - Parameters:
    ///   - parameter1: this is parameter1
    ///   - parameter2: this is parameter2
    static func function(parameter1: String) {
        print("Hello world")
    }

3. Should the rule be configurable, if so what parameters should be configurable?

I do not think so.

4. Should the rule be opt-in or enabled by default? Why?
   See README.md for guidelines on when to mark a rule as opt-in.

Seems to me that it will be good to have it enabled by default.

Start by reviewing README.md's opt-in-rule guidance and the linked historical pull requests (#225 and #1455) to understand the previous implementation and removal. The work is done when documentation parameter names, sets, and ordering are checked against function parameters, with the examples in this issue covered by tests.