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'm getting this:
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.
You can document each member separately:
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)")
}
}
Also see https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/ for information on special markup like - Parameters, which is for function parameters, not properties.
I tried putting doc comment right above the properties but option click the struct or "call site" didn't show any doc comment for the properties:
Must be a bug?
Question: who is responsible for the processing of doc comments and any bugs related to this? Swiftc or Xcode?
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)
}
}
But for the synthesized init, they do correspond exactly.
I want to make use the synthesized init and provide document for this init for showing that in quick help. It appears this is not doable...
If I have to write out the init for documentation, then I lose the benefit of automation provided by the compiler.
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".