1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
//===----------------------------------------------------------------------===//
//
// 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 SwiftSyntax
/// All public or open declarations must have a top-level documentation comment.
///
/// Lint: If a public declaration is missing a documentation comment, a lint error is raised.
@_spi(Rules)
public final class AllPublicDeclarationsHaveDocumentation: SyntaxLintRule {
/// Identifies this rule as being opt-in. While docs on most public declarations are beneficial,
/// there are a number of public decls where docs are either redundant or superfluous. This rule
/// can't differentiate those situations and will make a lot of noise for projects that are
/// intentionally avoiding docs on some decls.
public override class var isOptIn: Bool { return true }
public override func visit(_ node: FunctionDeclSyntax) -> SyntaxVisitorContinueKind {
diagnoseMissingDocComment(DeclSyntax(node), name: node.fullDeclName, modifiers: node.modifiers)
return .skipChildren
}
public override func visit(_ node: InitializerDeclSyntax) -> SyntaxVisitorContinueKind {
diagnoseMissingDocComment(DeclSyntax(node), name: "init", modifiers: node.modifiers)
return .skipChildren
}
public override func visit(_ node: DeinitializerDeclSyntax) -> SyntaxVisitorContinueKind {
diagnoseMissingDocComment(DeclSyntax(node), name: "deinit", modifiers: node.modifiers)
return .skipChildren
}
public override func visit(_ node: SubscriptDeclSyntax) -> SyntaxVisitorContinueKind {
diagnoseMissingDocComment(DeclSyntax(node), name: "subscript", modifiers: node.modifiers)
return .skipChildren
}
public override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind {
diagnoseMissingDocComment(DeclSyntax(node), name: node.name.text, modifiers: node.modifiers)
return .skipChildren
}
public override func visit(_ node: VariableDeclSyntax) -> SyntaxVisitorContinueKind {
guard let mainBinding = node.bindings.firstAndOnly else { return .skipChildren }
diagnoseMissingDocComment(DeclSyntax(node), name: "\(mainBinding.pattern)", modifiers: node.modifiers)
return .skipChildren
}
public override func visit(_ node: StructDeclSyntax) -> SyntaxVisitorContinueKind {
diagnoseMissingDocComment(DeclSyntax(node), name: node.name.text, modifiers: node.modifiers)
return .skipChildren
}
public override func visit(_ node: ProtocolDeclSyntax) -> SyntaxVisitorContinueKind {
diagnoseMissingDocComment(DeclSyntax(node), name: node.name.text, modifiers: node.modifiers)
return .skipChildren
}
public override func visit(_ node: TypeAliasDeclSyntax) -> SyntaxVisitorContinueKind {
diagnoseMissingDocComment(DeclSyntax(node), name: node.name.text, modifiers: node.modifiers)
return .skipChildren
}
private func diagnoseMissingDocComment(
_ decl: DeclSyntax,
name: String,
modifiers: DeclModifierListSyntax
) {
guard
DocumentationCommentText(extractedFrom: decl.leadingTrivia) == nil,
modifiers.contains(anyOf: [.public]),
!modifiers.contains(anyOf: [.override])
else {
return
}
diagnose(.declRequiresComment(name), on: decl)
}
}
extension Finding.Message {
fileprivate static func declRequiresComment(_ name: String) -> Finding.Message {
"add a documentation comment for '\(name)'"
}
}
|
