How to add lists in Xcode documentation markup?-CodePudding

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 (

CodePudding user response：

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

CodePudding user response：

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

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

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