How to make Quick Help (on the right)
show a summary and discussion like it shows in the codelab (on the left), please?
See screen shot here, please :
Thank you.
1 Like
If you add comments right above a function, starting with three forward slashes (///) instead of the normal two, the first paragraph will show up automatically as the summary in Quick help.
And the next paragraph will show up as the discussion.
/// summary
///
/// discussion
func hasPrefix(…) -> Bool
See the article:
https://developer.apple.com/documentation/Xcode/writing-symbol-documentation-in-your-source-files
2 Likes
Thank you, @Orup70.
So, just to clarify, the "func hasPrefix" was not written with a Summary or Discussion as shown on the left hand side of the screen shot above?
Are you asking specifically about the hasPrefix method in the standard library, or are you wondering more about Quick Help for your own code or in general?
If you're asking about hasPrefix specifically, I think there might be an issue related to how documentation comments are extracted for display in documentation. There's the hasPrefix definition on the type declaration of StringProtocol that doesn't have doc comments (and this String extension), and there's the hasPrefix definition in an extension of StringProtocol in SwiftLegacy.swift which has the doc comments from your screenshot.
It could just be that the doc comments aren't attached in the right place to show up in Quick Help. @Orup70's comment is the right explanation for the usual case.
Out of curiosity, where's the screenshot from in your original post?
(Edit: Oh, I found it. This is from the "student materials" playground download from Develop in Swift AP CS Principles.)
Looks like that book was published based on Xcode 11. I'm guessing that some combination of Swift language changes, documentation extraction changes, and Xcode changes over the years has caused the Quick Help for hasPrefix to drop away.
1 Like
My post above was probably a bit too exploratory; I think you're seeing a bug where func hasPrefix had some documentation with a summary and discussion originally, and there's a bug (somewhere) that prevents it from displaying to you in the version of Xcode you're using now.
For most Swift types, Quick Help should show you something here, I think you ran into a case where the materials you're reading happened to pick an example that broke later.
1 Like
I was referring to the general case, for one of your own methods. Unfortunately, I named the function in my example the same as the standard hasPrefix() function to make a connection to your screen shot. But I realize (now) it made it more confusing.
For a method you write in your own code, you can generally write:
/// summary for myMethod
///
/// discussion about myMethod
func myMethod(…) -> Bool
But I have also noticed that sometimes the Quick Help information “get stuck” in Xcode and you might have to click the cursor back and forth in the editor to get the info panel to refresh or on another file and back.
1 Like
Thank you, @krilnon and @Orup70 .
Just to clarify, I was trying to get the actual "Quick Help" on the right, to look like the codelab playground on the left which shows a Summary and Discussion in the white box for "func hasPrefix".
I'm guessing "func hasPrefix" was written by an Apple Engineer long ago.
This was part of the "Instances, Methods, and Properties.playground" file.
I find it odd that "Summary" and "Description" would be available in the Quick Help of previous version of Xcode but not a current version.
I was thinking maybe there was a verbose and terse setting in Quick Help,
(I wasn't really referring to how to make Summary and Discussion comments in my own code, but I am learning a lot and find all your messages valuable, and I thank you.)