Optionally allow adding `- returns:` docs to initializers

[mohpor]

Hi,
I use VVDocumenter to help me document my codes.
init() functions return an objects, although not explicitly defined in their syntax. For this particular reason, SwiftLint-ing them complains that their documentations are invalid.

example:

 /**
   Generates the view programatically to avoid giving out informations about the alert's views.   
   - parameter frame: A frame. Will be ignored.   
   - returns: An instance of UIView.
   */
  override init(frame: CGRect) {...}

(Disclaimer: This is just an example)

Swift lint will complain and say:

warning: Valid Docs Violation: Documented declarations should be valid. (valid_docs)

Although it is perfectly valid. You might argue that we don't need to document the return part, but I have many cases that it helps clarify the resulted instance, especially in case of failable initializers.

UPDATE:
Just to be clear, removing - returns from documentation does actually solve the validation problem.

[mohpor]

I'm more than happy to submit a PR but I jus don't know how to check if the kind is a constructor.

func delcarationReturns(declaration: String, kind: SwiftDeclarationKind? = nil) -> Bool {
    if let kind = kind where SwiftDeclarationKind.variableKinds().contains(kind) {
        return true
    }

    guard let outsideBracesMatch = matchOutsideBraces(declaration) else {
        return false
    }

    return outsideBracesMatch.containsString("->")
}

in ValidDocsRule.swift should return true in case kind is FunctionConstructor but no matter what, it never detects init functions as one!

To sum it up I felt pretty stupid trying to contribute to this repo. I couldn't find a way to extract function name from SourceKitten and .... (sigh)

[thebarndog]

There's another thing it misses too:

func myFunction(closure: (firstInt: Int, secondInt: Int) throws -> Void) { 
}

If a closure argument can throw an error, valid_docs complains because - throws: isn't in the documentation. In this example though, the function itself doesn't throw, the closure parameter does.

[chadmoone]

Dupe of #439?

[Grubas7]

I have same issue.

[jpsim]

this is a good "starter bug" if anyone is interested in contributing to SwiftLint.

[mohpor]

@startupthekid

If a closure argument can throw an error, valid_docs complains because - throws: isn't in the documentation. In this example though, the function itself doesn't through, the closure parameter does.

It seems like a separate issue.
Care to open a new issue?

[jpsim]

Fixed in #739.