swift-format でキチンと書いているつもりの Doc Comment に「パラメータがマッチしてない」警告がでる謎を追う

func open(with url: URL) { }

swift test --filter ValidateDocumentationCommentsTests

// swift-tools-version:5.1
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2019 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//

import PackageDescription
import Foundation

let rpath = "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/macosx"

let package = Package(
  name: "swift-format",
  products: [
    .executable(name: "swift-format", targets: ["swift-format"]),
    .library(name: "SwiftFormat", targets: ["SwiftFormat", "SwiftFormatConfiguration"]),
    .library(name: "SwiftFormatConfiguration", targets: ["SwiftFormatConfiguration"]),
  ],
  dependencies: [
  ],
  targets: [
    .target(
      name: "SwiftFormat",
      dependencies: [
        "SwiftFormatConfiguration",
        "SwiftFormatCore",
        "SwiftFormatPrettyPrint",
        "SwiftFormatRules",
        "SwiftFormatWhitespaceLinter",
        "SwiftSyntax",
      ]
    ),
    .target(name: "SwiftFormatConfiguration"),
    .target(name: "SwiftFormatCore", dependencies: ["SwiftFormatConfiguration", "SwiftSyntax"]),
    .target(
      name: "SwiftFormatRules",
      dependencies: ["SwiftFormatCore", "SwiftFormatConfiguration"]
    ),
    .target(
      name: "SwiftFormatPrettyPrint",
      dependencies: ["SwiftFormatCore", "SwiftFormatConfiguration"]
    ),
    .target(
      name: "SwiftFormatTestSupport",
      dependencies: [
        "SwiftFormatCore",
        "SwiftFormatRules",
        "SwiftFormatConfiguration",
      ]
    ),
    .target(
      name: "SwiftFormatWhitespaceLinter",
      dependencies: [
        "SwiftFormatCore",
        "SwiftSyntax",
      ]
    ),
    .target(
      name: "generate-pipeline",
      dependencies: [
        "SwiftFormatCore",
        "SwiftFormatRules",
        "SwiftSyntax",
      ]
    ),
    .target(
      name: "swift-format",
      dependencies: [
        "ArgumentParser",
        "SwiftFormat",
        "SwiftFormatConfiguration",
        "SwiftFormatCore",
        "SwiftSyntax",
      ],
      linkerSettings: [
          .unsafeFlags(["-rpath", rpath])
      ]
    ),
    .testTarget(
      name: "SwiftFormatTests",
      dependencies: [
        "SwiftFormat",
      ],
      linkerSettings: [
          .unsafeFlags(["-rpath", rpath])
      ]
    ),
    .testTarget(
      name: "SwiftFormatConfigurationTests",
      dependencies: ["SwiftFormatConfiguration"],
      linkerSettings: [
          .unsafeFlags(["-rpath", rpath])
      ]
    ),
    .testTarget(
      name: "SwiftFormatRulesTests",
      dependencies: [
        "SwiftFormatConfiguration",
        "SwiftFormatCore",
        "SwiftFormatPrettyPrint",
        "SwiftFormatRules",
        "SwiftFormatTestSupport",
        "SwiftSyntax",
      ],
      linkerSettings: [
          .unsafeFlags(["-rpath", rpath])
      ]
    ),
    .testTarget(
      name: "SwiftFormatCoreTests",
      dependencies: [
        "SwiftFormatConfiguration",
        "SwiftFormatCore",
        "SwiftSyntax",
      ],
      linkerSettings: [
          .unsafeFlags(["-rpath", rpath])
      ]
    ),
    .testTarget(
      name: "SwiftFormatPerformanceTests",
      dependencies: [
        "SwiftFormatTestSupport",
        "SwiftFormatWhitespaceLinter",
        "SwiftSyntax",
      ],
      linkerSettings: [
          .unsafeFlags(["-rpath", rpath])
      ]
    ),
    .testTarget(
      name: "SwiftFormatPrettyPrintTests",
      dependencies: [
        "SwiftFormatConfiguration",
        "SwiftFormatCore",
        "SwiftFormatPrettyPrint",
        "SwiftFormatRules",
        "SwiftFormatTestSupport",
        "SwiftSyntax",
      ],
      linkerSettings: [
          .unsafeFlags(["-rpath", rpath])
      ]
    ),
    .testTarget(
      name: "SwiftFormatWhitespaceLinterTests",
      dependencies: [
        "SwiftFormatConfiguration",
        "SwiftFormatCore",
        "SwiftFormatTestSupport",
        "SwiftFormatWhitespaceLinter",
        "SwiftSyntax",
      ],
      linkerSettings: [
          .unsafeFlags(["-rpath", rpath])
      ]
    ),
  ]
)


if ProcessInfo.processInfo.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
  // Building standalone.
  package.dependencies += [
    .package(url: "https://github.com/apple/swift-syntax", .upToNextMinor(from: "0.50500.0")),
    .package(url: "https://github.com/apple/swift-argument-parser.git", .upToNextMinor(from: "1.0.1")),
  ]
} else {
  package.dependencies += [
    .package(path: "../swift-syntax"),
    .package(path: "../swift-argument-parser"),
  ]
}

lint --recursive <lintをかけたいソースコードディレクトリへのフルパス>

  private func checkFunctionLikeDocumentation(
    _ node: DeclSyntax,
    name: String,
    parameters: FunctionParameterListSyntax,
    throwsOrRethrowsKeyword: TokenSyntax?,
    returnClause: ReturnClauseSyntax? = nil
  ) -> SyntaxVisitorContinueKind {
    guard let declComment = node.docComment else { return .skipChildren }
    guard let commentInfo = node.docCommentInfo else { return .skipChildren }
    guard let params = commentInfo.parameters else { return .skipChildren }

    // If a single sentence summary is the only documentation, parameter(s) and
    // returns tags may be ommitted.
    if commentInfo.oneSentenceSummary != nil && commentInfo.commentParagraphs!.isEmpty && params
      .isEmpty && commentInfo.returnsDescription == nil
    {
      return .skipChildren
    }

    // Indicates if the documentation uses 'Parameters' as description of the
    // documented parameters.
    let hasPluralDesc = declComment.components(separatedBy: .newlines).contains {
      $0.trimmingCharacters(in: .whitespaces).starts(with: "- Parameters")
    }

    validateThrows(
      throwsOrRethrowsKeyword, name: name, throwsDesc: commentInfo.throwsDescription, node: node)
    validateReturn(
      returnClause, name: name, returnDesc: commentInfo.returnsDescription, node: node)
    let funcParameters = funcParametersIdentifiers(in: parameters)

    // If the documentation of the parameters is wrong 'docCommentInfo' won't
    // parse the parameters correctly. First the documentation has to be fix
    // in order to validate the other conditions.
    if hasPluralDesc && funcParameters.count == 1 {
      diagnose(.useSingularParameter, on: node)
      return .skipChildren
    } else if !hasPluralDesc && funcParameters.count > 1 {
      diagnose(.usePluralParameters, on: node)
      return .skipChildren
    }

    // Ensures that the parameters of the documantation and the function signature
    // are the same.
    if (params.count != funcParameters.count) || !parametersAreEqual(
      params: params, funcParam: funcParameters)
    {
      diagnose(.parametersDontMatch(funcName: name), on: node)
    }

    return .skipChildren
  }

/// ✅ This doc comment is OK
/// - Parameters:
///   - arg1: This is a arg1
///   - arg2: This is a arg2.
///
public func ok(arg1: String, arg2: String) {
    // do something
}

Printing description of declComment:
" ✅ This doc comment is OK\n - Parameters:\n   - arg1: This is a arg1\n   - arg2: This is a arg2.\n"

(lldb) po commentInfo
▿ ParseComment
  ▿ oneSentenceSummary : Optional<String>
    - some : " ✅ This doc comment is OK\n - Parameters:\n   - arg1: This is a arg1\n   - arg2: This is a arg2"
  ▿ commentParagraphs : Optional<Array<String>>
    - some : 0 elements
  ▿ parameters : Optional<Array<Parameter>>
    - some : 0 elements
  - throwsDescription : nil
  - returnsDescription : nil

(lldb) po params
0 elements

/// ✅ However this doc comment is OK.
/// - Parameters:
///   - arg1: This is a arg1.
///   - arg2: This is a arg2
public func ok2(arg1: String, arg2: String) {
    // do something
}

(lldb) po declComment
" ✅ However this doc comment is OK.\n - Parameters:\n   - arg1: This is a arg1.\n   - arg2: This is a arg2"

(lldb) po commentInfo
▿ ParseComment
  ▿ oneSentenceSummary : Optional<String>
    - some : " ✅ However this doc comment is OK"
  ▿ commentParagraphs : Optional<Array<String>>
    - some : 0 elements
  ▿ parameters : Optional<Array<Parameter>>
    ▿ some : 2 elements
      ▿ 0 : Parameter
        - name : "arg1"
        - summary : "This is a arg1."
      ▿ 1 : Parameter
        - name : "arg2"
        - summary : "This is a arg2"
  - throwsDescription : nil
  - returnsDescription : nil

(lldb) po params
▿ 2 elements
  ▿ 0 : Parameter
    - name : "arg1"
    - summary : "This is a arg1."
  ▿ 1 : Parameter
    - name : "arg2"
    - summary : "This is a arg2"

/// This is sandbox。
/// - Parameters:
///   - arg1: This is a arg1
///   - arg2: This is a arg2
public func sandbox(arg1: String, arg2: String) throws {
    // do something
}

{
  "fileScopedDeclarationPrivacy" : {
    "accessLevel" : "private"
  },
  "indentation" : {
    "spaces" : 4
  },
  "indentConditionalCompilationBlocks" : true,
  "indentSwitchCaseLabels" : false,
  "lineBreakAroundMultilineExpressionChainComponents" : false,
  "lineBreakBeforeControlFlowKeywords" : false,
  "lineBreakBeforeEachArgument" : false,
  "lineBreakBeforeEachGenericRequirement" : false,
  "lineLength" : 300,
  "maximumBlankLines" : 2,
  "prioritizeKeepingFunctionOutputTogether" : false,
  "respectsExistingLineBreaks" : true,
  "rules" : {
    "AllPublicDeclarationsHaveDocumentation" : true,
    "AlwaysUseLowerCamelCase" : true,
    "AmbiguousTrailingClosureOverload" : true,
    "BeginDocumentationCommentWithOneLineSummary" : false,
    "DoNotUseSemicolons" : true,
    "DontRepeatTypeInStaticProperties" : true,
    "FileScopedDeclarationPrivacy" : true,
    "FullyIndirectEnum" : true,
    "GroupNumericLiterals" : true,
    "IdentifiersMustBeASCII" : true,
    "NeverForceUnwrap" : false,
    "NeverUseForceTry" : false,
    "NeverUseImplicitlyUnwrappedOptionals" : false,
    "NoAccessLevelOnExtensionDeclaration" : true,
    "NoBlockComments" : false,
    "NoCasesWithOnlyFallthrough" : true,
    "NoEmptyTrailingClosureParentheses" : true,
    "NoLabelsInCasePatterns" : true,
    "NoLeadingUnderscores" : false,
    "NoParensAroundConditions" : true,
    "NoVoidReturnOnFunctionSignature" : true,
    "OneCasePerLine" : true,
    "OneVariableDeclarationPerLine" : true,
    "OnlyOneTrailingClosureArgument" : true,
    "OrderedImports" : true,
    "ReturnVoidInsteadOfEmptyTuple" : true,
    "UseEarlyExits" : false,
    "UseLetInEveryBoundCaseVariable" : true,
    "UseShorthandTypeNames" : true,
    "UseSingleLinePropertyGetter" : true,
    "UseSynthesizedInitializer" : true,
    "UseTripleSlashForDocumentationComments" : true,
    "UseWhereClausesInForLoops" : true,
    "ValidateDocumentationComments" : true
  },
  "tabWidth" : 4,
  "version" : 1
}

  var docCommentInfo: ParseComment? {
    guard let docComment = self.docComment else { return nil }
    let comments = docComment.components(separatedBy: .newlines)
    var params = [ParseComment.Parameter]()
    var commentParagraphs = [String]()
    var currentSection: DocCommentSection = .commentParagraphs
    var returnsDescription: String?
    var throwsDescription: String?
    // Takes the first sentence of the comment, and counts the number of lines it uses.
    let oneSenteceSummary = docComment.components(separatedBy: ".").first
    let numOfOneSentenceLines = oneSenteceSummary!.components(separatedBy: .newlines).count

    // Iterates to all the comments after the one sentence summary to find the parameter(s)
    // return tags and get their description.
    for line in comments.dropFirst(numOfOneSentenceLines) {
      let trimmedLine = line.trimmingCharacters(in: .whitespaces)

      if trimmedLine.starts(with: "- Parameters") {
        currentSection = .parameters
      } else if trimmedLine.starts(with: "- Parameter") {
        // If it's only a parameter it's information is inline with the parameter
        // tag, just after the ':'.
        guard let index = trimmedLine.firstIndex(of: ":") else { continue }
        let name = trimmedLine.dropFirst("- Parameter".count)[..<index]
          .trimmingCharacters(in: .init(charactersIn: " -:"))
        let summary = trimmedLine[index...].trimmingCharacters(in: .init(charactersIn: " -:"))
        params.append(ParseComment.Parameter(name: name, summary: summary))
      } else if trimmedLine.starts(with: "- Throws:") {
        currentSection = .throwsDescription
        throwsDescription = String(trimmedLine.dropFirst("- Throws:".count))
      } else if trimmedLine.starts(with: "- Returns:") {
        currentSection = .returnsDescription
        returnsDescription = String(trimmedLine.dropFirst("- Returns:".count))
      } else {
        switch currentSection {
        case .parameters:
          // After the paramters tag is found the following lines should be the parameters
          // description.
          guard let index = trimmedLine.firstIndex(of: ":") else { continue }
          let name = trimmedLine[..<index].trimmingCharacters(in: .init(charactersIn: " -:"))
          let summary = trimmedLine[index...].trimmingCharacters(in: .init(charactersIn: " -:"))
          params.append(ParseComment.Parameter(name: name, summary: summary))

        case .returnsDescription:
          // Appends the return description that is not inline with the return tag.
          returnsDescription!.append(trimmedLine)

        case .throwsDescription:
          // Appends the throws description that is not inline with the throws tag.
          throwsDescription!.append(trimmedLine)

        case .commentParagraphs:
          if trimmedLine != "" {
            commentParagraphs.append(" " + trimmedLine)
          }
        }
      }
    }

    // Takes the first sentence of the comment, and counts the number of lines it uses.
    let oneSenteceSummary = docComment.components(separatedBy: ".").first
    let numOfOneSentenceLines = oneSenteceSummary!.components(separatedBy: .newlines).count

(lldb) po docComment
" This is sandbox。\n - Parameters:\n   - arg1: This is a arg1\n   - arg2: This is a arg2"

▿ 4 elements
  - 0 : " This is sandbox。"
  - 1 : " - Parameters:"
  - 2 : "   - arg1: This is a arg1"
  - 3 : "   - arg2: This is a arg2"

(lldb) po oneSenteceSummary
▿ Optional<String>
  - some : " This is sandbox。\n - Parameters:\n   - arg1: This is a arg1\n   - arg2: This is a arg2"

(lldb) po oneSenteceSummary!.components(separatedBy: .newlines)
▿ 4 elements
  - 0 : " This is sandbox。"
  - 1 : " - Parameters:"
  - 2 : "   - arg1: This is a arg1"
  - 3 : "   - arg2: This is a arg2"

(lldb) po comments.dropFirst(numOfOneSentenceLines) 
0 elements

/// ✅ This doc comment is OK
/// - Parameters:
///   - arg1: This is a arg1
///   - arg2: This is a arg2.
public func ok(arg1: String, arg2: String) {
    // do something
}

(lldb) po oneSenteceSummary
▿ Optional<String>
  - some : " ✅ This doc comment is OK\n - Parameters:\n   - arg1: This is a arg1\n   - arg2: This is a arg2"

/// 🚫⚠️ This doc comment occurs swift-format lint warning [ValidateDocumentationComments]: change the parameters of doSomething's documentation to match its parameters
/// - Parameters:
///   - arg1: This is a arg1.
///   - arg2: This is a arg2
public func warning(arg1: String, arg2: String) {
    // do something
}

(lldb) po oneSenteceSummary
▿ Optional<String>
  - some : " 🚫⚠️ This doc comment occurs swift-format lint warning [ValidateDocumentationComments]: change the parameters of doSomething\'s documentation to match its parameters\n - Parameters:\n   - arg1: This is a arg1"

(lldb) po oneSenteceSummary!.components(separatedBy: .newlines)
▿ 3 elements
  - 0 : " 🚫⚠️ This doc comment occurs swift-format lint warning [ValidateDocumentationComments]: change the parameters of doSomething\'s documentation to match its parameters"
  - 1 : " - Parameters:"
  - 2 : "   - arg1: This is a arg1"

(lldb) po comments
▿ 4 elements
  - 0 : " 🚫⚠️ This doc comment occurs swift-format lint warning [ValidateDocumentationComments]: change the parameters of doSomething\'s documentation to match its parameters"
  - 1 : " - Parameters:"
  - 2 : "   - arg1: This is a arg1."
  - 3 : "   - arg2: This is a arg2"

(lldb) po comments.dropFirst(numOfOneSentenceLines)
▿ 1 element
  - 0 : "   - arg2: This is a arg2"

(lldb) po trimmedLine
"- arg2: This is a arg2"

        case .commentParagraphs:
          if trimmedLine != "" {
            commentParagraphs.append(" " + trimmedLine)
          }

▿ ParseComment
  ▿ oneSentenceSummary : Optional<String>
    - some : " 🚫⚠️ This doc comment occurs swift-format lint warning [ValidateDocumentationComments]: change the parameters of doSomething\'s documentation to match its parameters\n - Parameters:\n   - arg1: This is a arg1"
  ▿ commentParagraphs : Optional<Array<String>>
    ▿ some : 1 element
      - 0 : " - arg2: This is a arg2"
  ▿ parameters : Optional<Array<Parameter>>
    - some : 0 elements
  - throwsDescription : nil
  - returnsDescription : nil