How to document struct synthesized init parameter?
import SwiftUI
/// A very very ordinary view
/// but how to document the `a` and `b` parameters?
/// this do not work:
///
/// - Parameters
/// - a: a is a parameter
/// - b: b is another parameter
struct AView: View {
let a: String
let b: String
var body: some View {
Text("\(a) -- \(b)")
}
}
I suspect that you need to write out the initializer manually if you want a place to write its documentation. You could put doc comments above the a and b property declarations, too, but they won't effect the initializer docs.
It's also probably worth noting that opening Quick Help for a type isn't supposed to show documentation for the type's initializer(s), especially because there can be more than one initializer. Instead, that shows up if you call the initializer ( AView(a: "a", b: "b")) and invoke help when the cursor or insertion point is selecting the arguments.
It might be a worthwhile enhancement to have synthesized initializers also synthesize parameter docs based on the relevant property docs.
import SwiftUI
/// A very very ordinary view
struct AView: View {
/// A parameter
let a: String
/// Another parameter
let b: String
var body: some View {
Text("\(a) -- \(b)")
}
}
I am asking about the one and only implicit/synthesized init. If there are any explicit user define init's then implicit/synthesized init is no more.
If only implicit/synthesized init exist, quick help on the struct should show this the descriptions of the struct and this one init and its parameters, I think.
Option click on the param label show "No description" even though there is doc comment right above the properties:
@young I think the source of your confusion is that Xcode shows the documentation for the struct itself, even though what you're clicking on is actually the initializer.
Try this:
import SwiftUI
/// A very very ordinary view
struct AView: View {
/// A parameter
let a: String
/// Another parameter
let b: String
/// The body
var body: some View {
Text("\(a) -- \(b)")
}
/// Creates a view.
///
/// - Parameters:
/// - a: a is a parameter
/// - b: b is another parameter
init(a: String, b: String) {
self.a = a
self.b = b
}
}
AView(a: "a", b: "b")
Then Option-click on the a: or b: part of AView(a: "a", b: "b"), not on the type name AView.
I assume this behavior is intentional, as it shows you the documentation for the type you've just clicked on, but yes, it's confusing if what you wanted to see was the documentation for the initializer.
These are not the same thing. The let a: String and let b: String in the struct are properties. The a and b in the initializer are its parameters. These often correspond, but they don't have to. For example:
struct Vector {
var x: Double
var y: Double
init(angle: Double, length: Double) {
x = length * cos(angle)
y = length * sin(angle)
}
}
It definitely seems reasonable for the synthesized initializer to show the doc comments for the properties as parameter comments. Worth filing at https://bugs.swift.org under "SourceKit".