I'm using Xcode 12.4 to write Swift code and would like to write documentation comments featuring Markdown-style markup. My impression is that Xcode expects me to write these comments as a series of paragraphs starting with ///, e.g. (taken from Swift.Collection.Array):

/// Returns the position immediately after the given index.
///
/// - Parameter i: A valid index of the collection. `i` must be less than
///   `endIndex`.
/// - Returns: The index immediately after `i`.
@inlinable public func index(after i: Int) -> Int

But it seems that Xcode doesn't try help me write these commends at all. Here are a few things I expected Xcode to do for me but doesn't:

• Provide a command that generates a stub for these comments (including e.g. a list of parameters and placeholders for the summary line and description).
• Automatically starting the next line with /// when hitting return at the end of the commend.
• Wrap paragaphs to the configured number of columns (the body of these comments are rendered with a proportional font so it's impossible to know where to wrap), or
• suggest that I should not break single paragraphs onto multiple lines by correctly indenting wrapped lines, which it doesn't. Wrapped lines are indented less than the first line of a paragraph.

Is there a way to make Xcode help me with these things or should I e.g. use a different tool to document Swift code?

CodePudding user response：

Here's what I know:

Provide a command that generates a stub for these comments (including e.g. a list of parameters and placeholders for the summary line and description).

There are a few options:

1. You can put a cursor above the function, and use Editor > Structure > Add Documentation.
2. You can create a code snippet, as explained here
3. There are a couple of Xcode extensions that provide such functionality (for example: Comments for Xcode, or others)

Automatically starting the next line with /// when hitting return at the end of the commend.

Xcode 13 does that. Not sure if it was working in older versions.

Wrap paragaphs to the configured number of columns (the body of these comments are rendered with a proportional font so it's impossible to know where to wrap)

I think this can be done with extension called Comment wrapper for Xcode. But question is if you actually need to do that. Typically when you see comment in Xcode, it will automatically be wrapped. When you publish it however, you may not need that wrapping. So my personal preference is not to mess with Xcode's wrapping.