How to add lists in Xcode documentation markup?

Question

I'm trying to add documentation to my code in Xcode. I've followed a couple of articles that suggest my markup should work with Xcode preview (https://nshipster.com/swift-documentation/ and https://sarunw.com/posts/swift-documentation/) but the bullet point list isn't displaying. Have I missed something obvious?

    /**
     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)
    }

But this is the preview I get at the call site:

Answer 1

Here is fixed part (removed #, and wrapping comment is only /** */, you don't need * at every line for comment itself, but it's a mark for list item)

 /**
  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

This actually has nothing to do with lists, but headings. Notice that if you remove the heading # Examples:, or just the # character, the markdown is rendered as expected.

For some reason, Xcode ignores all the text after it encounters a heading of any kind in a documentation comment.

See this example from this very old answer. It apparently worked back then!

/// 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's "discussion" part stops before the first heading,

(Try deleting the headings and see what happens!)

The parameters and returns seem to be rendered fine though.

On the other hand, if I use a documentation generator like jazzy like the linked answer suggests, the headings and all the other text are rendered properly:

There is no Swift Logo because I didn't download one to my local machine :) Your documentation for formattedString function is also generated properly by jazzy, without needing to change anything.

As another alternative, AppCode generates documentation for both your formattedString function and the above example correctly too.

So I think this is a just a quirk/bug in Xcode. Documentation generators can still properly generate documentations from these comments.