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:
2
Answers
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)
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!
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 byjazzy
, 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.