Open 05262b81-54a9-4fe1-bf6a-96f8042de10e opened 8 years ago
Comment by Leonard Pauli (JIRA)
Until this is implemented, the block type could be defined above using typealias, which in turn would allow the block parameters to be documented. Example: http://stackoverflow.com/a/41970146/1054573
Xcode today supports documenting block parameters by putting the - Parameter:
line at the top level (with the rest of the method parameters). This is weird, and I don't know what happens if a block parameter is named the same as one of the method parameters.
I still want the ability to use nested parameter blocks (and other directives) in parameters though.
Attachment: Download
Additional Detail from JIRA
| | | |------------------|-----------------| |Votes | 4 | |Component/s | | |Labels | Improvement | |Assignee | None | |Priority | Medium | md5: 20cc179ef278de55fb2222d3e8fa056cIssue Description:
Swift docstrings are Markdown-formatted text that has special handling for certain formats used in unordered lists. I know Swift parses the comment itself to find certain commands, and I'm assuming that Swift's parsing of the full doc comment is fed to Xcode in a structured manner for Xcode to display, instead of having Xcode re-parse the thing itself. But I'm not quite sure about this, so I also filed a Radar on Xcode for this same request.
Anyway, what I want is for nested documentation commands to be supported. I mainly just care about nested
- Parameter
commands, and possibly- Returns
, but it would be better to support arbitrary commands too like- Note
. The reason for wanting this stuff is to be able to document closure parameters to functions. For example:If I try this today in Xcode 7.2.1, the nested commands are rendered as a nested unordered list instead of parsing them for commands. I've attached a screenshot showing this. What I really want to see instead is something similar to how Apple's documentation handles this, such as with
NSURLSession.dataTaskWithURL(_:completionHandler:)
.