Documentation for Switch, Return, Throw and Type syntax nodes #3231
Conversation
Padmashree06
requested review from
ahoppen,
hamishknight,
hborla and
rintaro
as code owners
ahoppen
left a comment
ahoppen
left a comment
There was a problem hiding this comment.
Thanks for adding the documentation @Padmashree06. I added a few comments below.
| base: .syntax, | ||
| nameForDiagnostics: nil, | ||
| documentation: """ | ||
| A clause that specifies the underlying type of a type declaration. |
There was a problem hiding this comment.
| A clause that specifies the underlying type of a type declaration. | |
| A clause that specifies the underlying type of a `typealias` or `associatedtype` declaration. |
| ``` | ||
|
|
||
| ```swift | ||
| func greet(name: String) {} |
There was a problem hiding this comment.
Function parameters actually don’t use TypeAnnotationSyntax, see https://swiftpackageindex.com/swiftlang/swift-syntax/main/documentation/swiftsyntax/functionparametersyntax
| A statement that exits a function or closure and optionally returns a value. | ||
|
|
||
| Written as: | ||
| ```swift | ||
| return | ||
| ``` | ||
|
|
||
| ```swift | ||
| return <expr> | ||
| ``` | ||
| """, |
There was a problem hiding this comment.
The indentation seems a little off to me here, both within the code blocks and overall.
Same below
| name: "expression", | ||
| kind: .node(kind: .expr) | ||
| kind: .node(kind: .expr), | ||
| nameForDiagnostics: "error" |
There was a problem hiding this comment.
Did you intentionally change the name for diagnostics here?
| base: .syntax, | ||
| nameForDiagnostics: nil, | ||
| documentation: """ | ||
| A clause that specifies the return type of a function or closure. |
There was a problem hiding this comment.
Actually function, subscript, type, or closure.
// function
func f() -> Int { }
// subscript
subscript(I: Int) -> Int {}
// type
let a: () -> Int = { 1 }
// closure
_ = { () -> Int in 1 }But I'm not sure we should list everything here. This information is automatically rendered as "Contained in" section.
So maybe A clause that specifies the return type is enough.
There was a problem hiding this comment.
My proposal would be A clause that specifies the return type, typically of a function or subscript. That leaves room for the slightly more edge cases in the Contained In section, while still giving you an idea of what this is about.
| Written as: | ||
| ```swift | ||
| -> <type> | ||
| ``` |
There was a problem hiding this comment.
This technically a duplicated information with ### Children section in the rendered doc-comments. Although this simplified code might be nice to read, my personal preference is not to have this.
There was a problem hiding this comment.
Fair point, I don’t have a strong opinion here either way
| -> <type> | ||
| ``` | ||
|
|
||
| ### Examples |
There was a problem hiding this comment.
I'm not really sure we should write a section (###) here. It's the same header level as other generated sections (i.e. ### Children and ### Contained in), If we want another section for "examples", we might need another property on Node.
But I think something like this would be enough.
A clause that specifies the return type.
For example, the `-> Int` part in
```swift
func foo() throws -> Int { ... }
```
There was a problem hiding this comment.
We have a lot of precedence for ### Examples sections in the documentation, just search for that string in CodeGeneration. So, I vote to keep it.
I’m not opposed to moving the examples into a different property of Node but I think that should be a different PR.
|
The requested changes have been addressed, and the test suite passes without issues. |
3 participants
This PR adds documentation comments for the following Syntax nodes:
SwitchCaseLabelSyntaxSwitchDefaultLabelSyntaxSwitchCaseSyntaxThrowStmtSyntaxReturnClauseSyntaxReturnStmtSyntaxTypeInitializerClauseSyntaxTypeAnnotationSyntaxThe documentation follows the format used in #1527 and includes
brief explanations and examples where applicable.
This contributes to issue #1528.