Why is Swift 2 switching from reStructuredText to Markdown?

I'm sure I'm not alone in thinking that Swift had made an excellent choice in going with reStructuredText for doc comments. I know Markdown is more ubiquitous, but it's also somewhat ill-defined and isn't particularly well-suited to long-form text. The use of reStructuredText promised to have a much more standardized way of writing documentation that could be very expressive and support extensions in a well-defined way (e.g. so documentation tools could define extensions you could use in your code).


The only real concrete benefit to using Markdown is unifying it with Playground rich comments, but it seems to me that Playground rich comments should have just been using reStructuredText to begin with (or perhaps could have had a toggle in the document inspector for comment style, if there's a real need to support Markdown here, although I don't know what that need would be).

Also worth pointing out: the Swift 1.x documentation format used a well-defined reST construct for doing parameter and return types (e.g. a field list with specific field names, which is exactly how that construct is meant to be used), but the Swift 2 markdown syntax is using an ad-hoc completely custom way of defining parameters.

Well the signs were on the wall when Playgrounds got Markdown comments. I was wondering why not in in both environments the same system and here it is.

Can anyone tell me how I would go about using Markdown to document code? With RestrText, if I option-click on a function name, it will properly format my description, parameters, and return types. What is the format for Markdown? Thanks.

Why is Swift 2 switching from reStructuredText to Markdown?
 
 
Q