completed-docs should not require documentation on the implementation of function overloads

[UselessPickles]

Bug Report

• TSLint version: 5.13.1
• TypeScript version: 3.3.3333
• Running TSLint via: CLI

TypeScript code being linted

/**
 * Documentation    
 * @param x - A parameter
 * @returns A value
 */
export function foo(x: number): number;
/**
 * Documentation
 * @param x - A parameter
 * @returns A value
 */
export function foo(x: string): string;
export function foo(x: number | string): number | string {
    return x;
}

with tslint.json configuration (excerpt of relevant rule config):

{
    "rules": {
        "completed-docs": [
            true, {
                "functions": {
                    "locations": ["all"]
                }
            }
        ]
    }
}

Actual behavior

completed-docs fails on the signature of the implementation of overloaded function foo.

Expected behavior

When a function is overloaded, the signature of the implementation is not a callable signature. It's simply a common signature compatible with all overload signatures so that a single implementation can be written that works with all overload signatures. It is not very useful/necessary to have documentation on the overload implementation, because all usages of the function in code will resolve to one of the overload signatures, and IDEs will present the documentation of the appropriately matched overload signature (and/or will allow the user to toggle between all overload signatures and their documentation). The signature of the implementation itself is never useful to present to the user, because it is not callable.

When a function has multiple signatures (is overloaded), the signature of the implementation itself should not require documentation.

Somewhat related to #4416, yet still probably independent of it.

[JoshuaKGoldberg]

Agreed. I think once #4563 goes in, TSLint should consider these to be overloads under the same option.

[UselessPickles]

Note that this would similarly be applicable to methods of classes with overload signatures.

[JoshuaKGoldberg]

💀 It's time! 💀

TSLint is deprecated and no longer accepting pull requests other than security fixes. See #4534. ☠️
We recommend you instead use typescript-eslint to lint your TypeScript code with ESLint. ✅

👋 It was a pleasure open sourcing with you!

[JoshuaKGoldberg]

🤖 Beep boop! 👉 TSLint is deprecated 👈 (#4534) and you should switch to typescript-eslint! 🤖

🔒 This issue is being locked to prevent further unnecessary discussions. Thank you! 👋