[SR-874] Doc comment should support nested commands such as - Parameter

[05262b81-54a9-4fe1-bf6a-96f8042de10e]

Previous ID	SR-874
Radar	rdar://problem/24961176
Original Reporter	@lilyball
Type	Improvement

Attachment: Download

Additional Detail from JIRA

| | | |------------------|-----------------| |Votes | 4 | |Component/s | | |Labels | Improvement | |Assignee | None | |Priority | Medium | md5: 20cc179ef278de55fb2222d3e8fa056c

Issue 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:

/// Does something and calls a completion block with the results.
///
/// - Parameter completion: A completion block that's called on the main thread with the following parameters:
///   - Parameter result: The result of the task, or `nil` if an error occurred.
///   - Parameter error: If an error occurred, contains an `NSError` describing what went wrong.
///   - Returns: A `Disposition` value indicating how to proceed.
func doSomething(completion: (result: String?, error: NSError?) -> Disposition)

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:).

[swift-ci]

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

[05262b81-54a9-4fe1-bf6a-96f8042de10e]

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.