Skip to content

Format doc comments so they render better in docc #2034

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 9, 2023
Merged

Format doc comments so they render better in docc #2034

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 67 additions & 49 deletions CodeGeneration/Sources/SyntaxSupport/DeclNodes.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,9 @@ public let DECL_NODES: [Node] = [
base: .decl,
nameForDiagnostics: "associatedtype declaration",
documentation: """
An associated type declaration like the following.
An `associatedtype` declaration

An example of an associatedtype declaration is

```swift
associatedtype Item
Expand Down Expand Up @@ -332,7 +334,9 @@ public let DECL_NODES: [Node] = [
base: .decl,
nameForDiagnostics: "class",
documentation: """
A class declaration like the following.
A `class` declaration

An example of a class declaration is

```swift
class SomeClass {
Expand Down Expand Up @@ -498,7 +502,9 @@ public let DECL_NODES: [Node] = [
base: .decl,
nameForDiagnostics: "deinitializer",
documentation: """
A deinitializer declaration like the following.
A `deint` declaration

An example of a deinitializer is

```swift
deinit {
Expand Down Expand Up @@ -1135,7 +1141,9 @@ public let DECL_NODES: [Node] = [
base: .decl,
nameForDiagnostics: "import",
documentation: """
An import declaration like the following.
An `import` declaration

An example of an import declaration is

```swift
import Foundation
Expand Down Expand Up @@ -1180,7 +1188,11 @@ public let DECL_NODES: [Node] = [
.keyword(text: "func"),
.keyword(text: "inout"),
]),
documentation: "The kind of declaration being imported. For example, a struct can be imported from a specific module.",
documentation: """
The kind of declaration being imported.

A struct can be imported from a specific module.
""",
isOptional: true
),
Child(
Expand Down Expand Up @@ -1241,7 +1253,9 @@ public let DECL_NODES: [Node] = [
base: .decl,
nameForDiagnostics: "initializer",
documentation: """
An initializer declaration like the following.
An `init` declaration

An example of an initializer is

```swift
init(someParameter: Int) {
Expand Down Expand Up @@ -1900,7 +1914,9 @@ public let DECL_NODES: [Node] = [
base: .decl,
nameForDiagnostics: "protocol",
documentation: """
A protocol declaration like the following.
A `protocol` declaration

An example of a protocol declaration is

```swift
protocol Example {
Expand Down Expand Up @@ -2021,61 +2037,63 @@ public let DECL_NODES: [Node] = [
base: .decl,
nameForDiagnostics: "struct",
documentation: """
A struct declaration like the following.
A `struct` declaration

```swift
struct SomeStruct {
let someMember: String
var anotherMember: Int
An example of a struct declaration is

func foo() {
print(someMember)
}
```swift
struct SomeStruct {
let someMember: String
var anotherMember: Int

mutating func bar() {
anotherMember = 42
}
}
```
func foo() {
print(someMember)
}

A struct declaration may be declared without any members.
mutating func bar() {
anotherMember = 42
}
}
```

```swift
struct EmptyStruct {
A struct declaration may be declared without any members.

}
```
```swift
struct EmptyStruct {

A struct declaration may include a type inheritance clause listing
one or more protocols the struct conforms to.
}
```

The example below uses Hashable and Equatable protocols whose members
are automatically synthesized by the compiler if the struct contains
stored members that are themselves `Hashable` and `Equatable`.
A struct declaration may include a type inheritance clause listing
one or more protocols the struct conforms to.

```swift
struct AdvancedStruct: Hashable, Equatable {
let someMember: String
var anotherMember: Int
}
```
The example below uses Hashable and Equatable protocols whose members
are automatically synthesized by the compiler if the struct contains
stored members that are themselves `Hashable` and `Equatable`.

```swift
struct AdvancedStruct: Hashable, Equatable {
let someMember: String
var anotherMember: Int
}
```

A struct declaration may include a generic parameter clause as well
as a generic where clause.
A struct declaration may include a generic parameter clause as well
as a generic where clause.

```swift
struct Stack<Element> {
var items: [Element] = []
```swift
struct Stack<Element> {
var items: [Element] = []

mutating func push(_ item: Element) {
items.append(item)
}
mutating func push(_ item: Element) {
items.append(item)
}

mutating func pop() -> Element {
return items.removeLast()
}
}
```
mutating func pop() -> Element {
return items.removeLast()
}
}
```
""",
traits: [
"DeclGroup",
Expand Down
4 changes: 3 additions & 1 deletion CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -981,7 +981,9 @@ public let EXPR_NODES: [Node] = [
base: .expr,
nameForDiagnostics: "'is'",
documentation: """
An `is` expression like the following.
Checks if an expression is of a given type.

An example of an `is` expression is

```swift
value is Double
Expand Down
27 changes: 17 additions & 10 deletions CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SyntaxBaseNodesFile.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,11 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
"""
// MARK: - \(node.kind.syntaxType)

/// Protocol to which all ``\(node.kind.syntaxType)`` nodes conform. Extension point to add
/// common methods to all ``\(node.kind.syntaxType)`` nodes.
/// DO NOT CONFORM TO THIS PROTOCOL YOURSELF!
/// Protocol to which all ``\(node.kind.syntaxType)`` nodes conform.
///
/// Extension point to add common methods to all ``\(node.kind.syntaxType)`` nodes.
///
/// - Warning: Do not conform to this protocol yourself.
public protocol \(node.kind.protocolType): \(raw: node.base.protocolType) {}
"""
)
Expand All @@ -33,7 +35,8 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
"""
/// Check whether the non-type erased version of this syntax node conforms to
/// \(node.kind.protocolType).
/// Note that this will incur an existential conversion.
///
/// - Note: This will incur an existential conversion.
func isProtocol(_: \(node.kind.protocolType).Protocol) -> Bool {
return self.asProtocol(\(node.kind.protocolType).self) != nil
}
Expand All @@ -44,7 +47,8 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
"""
/// Return the non-type erased version of this syntax node if it conforms to
/// \(node.kind.protocolType). Otherwise return nil.
/// Note that this will incur an existential conversion.
///
/// - Note: This will incur an existential conversion.
func asProtocol(_: \(node.kind.protocolType).Protocol) -> \(node.kind.protocolType)? {
return self.asProtocol(SyntaxProtocol.self) as? \(node.kind.protocolType)
}
Expand Down Expand Up @@ -131,9 +135,10 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {

try InitializerDeclSyntax(
"""
/// Creates a ``\(node.kind.syntaxType)`` node from the given ``SyntaxData``. This assumes
/// that the ``SyntaxData`` is of the correct kind. If it is not, the behaviour
/// is undefined.
/// Creates a ``\(node.kind.syntaxType)`` node from the given ``SyntaxData``.
///
/// - Warning: This assumes that the ``SyntaxData`` is of the correct kind.
/// If it is not, the behaviour is undefined.
internal init(_ data: SyntaxData)
"""
) {
Expand Down Expand Up @@ -192,7 +197,8 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
"""
/// Syntax nodes always conform to `\(node.kind.protocolType)`. This API is just
/// added for consistency.
/// Note that this will incur an existential conversion.
///
/// - Note: This will incur an existential conversion.
@available(*, deprecated, message: "Expression always evaluates to true")
public func isProtocol(_: \(raw: node.kind.protocolType).Protocol) -> Bool {
return true
Expand All @@ -203,7 +209,8 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
DeclSyntax(
"""
/// Return the non-type erased version of this syntax node.
/// Note that this will incur an existential conversion.
///
/// - Note: This will incur an existential conversion.
public func asProtocol(_: \(node.kind.protocolType).Protocol) -> \(node.kind.protocolType) {
return Syntax(self).asProtocol(\(node.kind.protocolType).self)!
}
Expand Down
8 changes: 5 additions & 3 deletions CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SyntaxNodesFile.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,10 @@ func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {

DeclSyntax(
"""
/// Creates a ``\(node.kind.syntaxType)`` node from the given ``SyntaxData``. This assumes
/// that the `SyntaxData` is of the correct kind. If it is not, the behaviour
/// is undefined.
/// Creates a ``\(node.kind.syntaxType)`` node from the given ``SyntaxData``.
///
/// - Warning: This assumes that the `SyntaxData` is of the correct kind.
/// If it is not, the behaviour is undefined.
internal init(_ data: SyntaxData) {
precondition(data.raw.kind == .\(raw: node.varOrCaseName))
self._syntaxNode = Syntax(data)
Expand Down Expand Up @@ -199,6 +200,7 @@ func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {
"""
/// Adds the provided `element` to the node's `\(child.varOrCaseName)`
/// collection.
///
/// - param element: The new `\(raw: childElt)` to add to the node's
/// `\(child.varOrCaseName)` collection.
/// - returns: A copy of the receiver with the provided `\(raw: childElt)`
Expand Down
Loading