编辑器支持在 Xcode 12.4 中记录 Swift API
Editor support for documenting Swift APIs in Xcode 12.4
我正在使用 Xcode 12.4 编写 Swift 代码，并希望编写具有 Markdown 样式标记的文档注释。我的印象是 Xcode 希望我将这些评论写成以 /// 开头的一系列段落，例如（取自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
但是Xcode好像根本没有帮我写这些表扬。以下是一些我希望 Xcode 为我做但没有做的事情：
- 提供一个命令，为这些评论生成存根（包括例如参数列表和摘要行和描述的占位符）。
- 在命令结束时点击 return 时自动以
/// 开始下一行。
- 将段落换行到配置的列数（这些评论的正文以比例字体呈现，因此不可能知道在哪里换行），或者
- 建议我不要通过正确缩进换行将单个段落分成多行，但事实并非如此。换行的缩进小于段落的第一行。
有没有办法让 Xcode 帮我解决这些问题，或者我应该使用不同的工具来记录 Swift 代码？
这是我知道的：
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).
有几个选项：
- 您可以将光标放在函数上方，然后使用“编辑器”>“结构”>“添加文档”。
- 您可以创建一个代码片段，如解释的那样here
- 有几个 Xcode 扩展提供了这样的功能
功能（例如：Comments for Xcode，或其他）
Automatically starting the next line with /// when hitting return at the end of the commend.
Xcode 13 做到了。不确定它是否适用于旧版本。
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)
我认为这可以通过名为 Comment wrapper for Xcode 的扩展来完成。但问题是你是否真的需要这样做。通常，当您在 Xcode 中看到评论时，它会自动换行。但是，当您发布它时，您可能不需要这种包装。所以我个人的喜好是不要弄乱 Xcode 的包装。
我正在使用 Xcode 12.4 编写 Swift 代码，并希望编写具有 Markdown 样式标记的文档注释。我的印象是 Xcode 希望我将这些评论写成以 /// 开头的一系列段落，例如（取自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
但是Xcode好像根本没有帮我写这些表扬。以下是一些我希望 Xcode 为我做但没有做的事情：
- 提供一个命令，为这些评论生成存根（包括例如参数列表和摘要行和描述的占位符）。
- 在命令结束时点击 return 时自动以
///开始下一行。 - 将段落换行到配置的列数（这些评论的正文以比例字体呈现，因此不可能知道在哪里换行），或者
- 建议我不要通过正确缩进换行将单个段落分成多行，但事实并非如此。换行的缩进小于段落的第一行。
有没有办法让 Xcode 帮我解决这些问题，或者我应该使用不同的工具来记录 Swift 代码？
这是我知道的：
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).
有几个选项：
- 您可以将光标放在函数上方，然后使用“编辑器”>“结构”>“添加文档”。
- 您可以创建一个代码片段，如解释的那样here
- 有几个 Xcode 扩展提供了这样的功能 功能（例如：Comments for Xcode，或其他）
Automatically starting the next line with /// when hitting return at the end of the commend.
Xcode 13 做到了。不确定它是否适用于旧版本。
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)
我认为这可以通过名为 Comment wrapper for Xcode 的扩展来完成。但问题是你是否真的需要这样做。通常，当您在 Xcode 中看到评论时，它会自动换行。但是，当您发布它时，您可能不需要这种包装。所以我个人的喜好是不要弄乱 Xcode 的包装。