如何在 Xcode 文档标记中添加列表？

Question

我正在尝试向 Xcode 中的代码添加文档。我关注了几篇文章，这些文章建议我的标记应该与 Xcode 预览 (https://nshipster.com/swift-documentation/ and https://sarunw.com/posts/swift-documentation/) 一起使用，但项目符号列表未显示。我错过了一些明显的东西吗？

    /**
     Formats date components into a sensible representation given the other date components included.

     # Examples:

     * If two dates are in the same year, the common year will be returned.
     * If two dates are in the same month and year, the common months and year will be returned.
     * If two dates don't share any commonality, nil is returned.
     */
    func formattedString(for components: [DateComponents]) -> String? {
        getFormattedDateRange(for: components)
    }

但这是我在调用站点获得的预览：

Answer 1

这里是固定的部分（去掉了#，包装注释只是/** */，注释本身不需要每行*，但它是列表项的标记）

 /**
  Formats date components into a sensible representation given the other date components included.

  Examples:
  * If two dates are in the same year, the common year will be returned.
  * If two dates are in the same month and year, the common months and year will be returned.
  * If two dates don't share any commonality, nil is returned.

  */
 func formattedString(for components: [DateComponents]) -> String? {
      getFormattedDateRange(for: components)
 }

Answer 2

这实际上与列表无关，而是标题。请注意，如果您删除标题 # Examples:，或仅删除 # 字符，降价将按预期呈现。

出于某种原因，Xcode 在文档注释中遇到任何类型的标题后会忽略所有文本。

请参阅 this very old answer 中的示例。它显然在当时有效！

/// Text like this appears in "Description".
///
/// Leave a blank line to separate further text into paragraphs.
///
/// You can use bulleted lists (use `-`, `+` or `*`):
///
/// - Text can be _emphasised_
/// - Or **strong**
///
/// Or numbered lists:
///
/// 7. The numbers you use make no difference
/// 0. The list will still be ordered, starting from 1
/// 5. But be sensible and just use 1, 2, 3 etc…
///
/// ---
///
/// More Stuff
/// ==========
///
/// Code
/// ----
///
/// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block, handy for example usage:
///
///     // Create an integer, and do nothing with it
///     let myInt = 42
///     doNothing(myInt)
///
///     // Also notice that code blocks scroll horizontally instead of wrapping.
///
/// Links & Images
/// --------------
///
/// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images:
///
/// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
///
/// - note: That "Note:" is written in bold.
/// - requires: A basic understanding of Markdown.
/// - seealso: `Error`, for a description of the errors that can be thrown.
///
/// - parameters:
///   - int: A pointless `Int` parameter.
///   - bool: This `Bool` isn't used, but its default value is `false` anyway…
/// - throws: A `BadLuck` error, if you're unlucky.
/// - returns: Nothing useful.
public func doNothing(int: Int, bool: Bool = false) throws -> String {
    return "Totally contrived."
}

Xcode的“讨论”部分在第一个标题之前停止，

（尝试删除标题，看看会发生什么！）

参数和 returns 似乎渲染得很好。

另一方面，如果我像链接的答案所建议的那样使用 jazzy 之类的文档生成器，则标题和所有其他文本都会正确呈现：

没有 Swift 徽标，因为我没有将一个徽标下载到我的本地计算机 :) formattedString 功能的文档也由 jazzy 正确生成，无需改变任何东西。

作为另一种选择，AppCode 也可以为您的 formattedString 函数和上面的示例正确生成文档。

所以我认为这只是 Xcode 中的一个 quirk/bug。文档生成器仍然可以从这些评论中正确生成文档。

如何在 Xcode 文档标记中添加列表？

How to add lists in Xcode documentation markup?

xcode

swift