Swiftlint: valid_docs should suggest a fix

[ZevEisenberg]

I have some older Swift code that I yoinkned from an internal project, and it looks like the doc comments are out of date. SwiftLint puts "Valid Docs Violation: Documented declarations should be valid. (valid_docs)" at the beginning of the two static func lines in this snippet:

enum APIResult<T> {
    case Success(T)
    case Failure(ErrorType)

    /**
     Create an `APIResult` indicating success.

     :param: value The API request's return value.

     :returns: A successful `APIResult` value.
     */
    static func success(value: T) -> APIResult<T> {
        return .Success(value)
    }

    /**
     Create an `APIResult` indicating failure.

     :param: error The `NSError` object describing the failure.

     :returns: An `APIResult` failure state.
     */
    static func failure(error: ErrorType) -> APIResult<T> {
        return .Failure(error)
    }

}

I haven't brushed up on Swift doc comment syntax, so for all I know, this is old-school Swift 1.2 or even Obj-C format, but that's not the point. SwiftLint should give me some kind of indication as to what's wrong with the docs, so I know what to do to fix them.

Here are other cases where it's throwing warnings:

    /**
     Perform an API request against an endpoint.

     :param: endpoint   API endpoint details.
     :param: parameters Optional API parameters.
     :param: headers    optional request headers

     :returns: An `Alamofire.Request` object.
     */
    func request(endpoint: APIEndpoint, parameters: APIParameter? = nil, headers: [String : String]? = nil) -> Alamofire.Request {

    /**
     Validate that the deserialized JSON represents an object.

     :param: JSONResponse The deserialized JSON.
     :param: completion   A completion closure that accepts a `JSONObjectResult`.
     */
    func validateJSONResponseIsObject(JSONResponse: AnyObject, completion: JSONObjectCompletion) {

    /**
     Validate that the deserialized JSON represents an array.

     :param: JSONResponse The deserialized JSON.
     :param: completion   A completion closure that accepts a `JSONArrayResult`.
     */
    func validateJSONResponseIsArray(JSONResponse: AnyObject, completion: JSONArrayCompletion) {

extension NSError {

    /**
    Create an `NSError` object that encapsulates a network error.

    :param: errorCode       ProjectName-specific error code.
    :param: description     A description of the error.
    :param: underlyingError The underlying `NSError` object, if one exists.

    :returns: An initialized `NSError` object.
    */
    convenience init(errorCode: MyProjectAPIError, description: String?, underlyingError: NSError?) {
        var userInfo = [String: AnyObject]()

        if let desc = description {
            userInfo[NSLocalizedDescriptionKey] = desc
        }

        if let e = underlyingError {
            userInfo[NSUnderlyingErrorKey] = e
        }

        self.init(domain: kAmazingAPIErrorDomain, code: errorCode.rawValue, userInfo: userInfo)
    }

}

[ZevEisenberg]

This is with SwiftLint 0.7.2

[jpsim]

We should definitely say _why_ a doc comment is invalid rather than just say it's wrong and leave you guessing.

Unrelated to making this improvement, SwiftLint considers the doc comments in your examples invalid because they're in the Swift 1.x format. The Swift 2.x format replaces :param: foo with - parameter foo: and :returns: with - returns:. Erica Sadun has an awesome blog post and book on Swift 2 documentation formatting that explains all of this quite well.

[soffes]

@jpsim that would be super great. Erica's blog post was really helpful! Thanks! :)

[Tableau-David-Potter]

I'd like to +1 this request. I'm getting a valid_docs warning and I'm struggling to figure it out. (I'll create a separate issue for it.)

[jpsim]

yeah, it's tricky right now. sorry 😬

[marcelofabri]

Closing this since we removed this rule.