Open Radar

 
The Swift 2.0 documentation format is a confusing mixture of Markdown and magically parsed strings that creates a challenging landscape to even know what to expect Xcode to be parsing as special tags.

Take this example:

  /// A magical function that does something with `x` and `y`.
  ///
  /// The behavior is outlined as:
  ///   - if `x` is magical, do something cool
  ///   - if `y` is magical, do something even cooler
  ///
  /// - parameters:
  ///   - x: The first magic number.
  ///   - y: The second magic number.
  ///
  /// - throws: A `NonMagicalError` if either `x` or `y` is `0`.
  /// - returns: The magic operation of `f(x, y)`.
  func f(x: Int, y: Int) throws -> Int { ... }

First, it seems like a hack that we are using list items to denote potential matches for Xcode parseable items. This is made further odd if the description of the method actually uses lists as well. Also, the behavior of unparsed Xcode tags showing up in the method description is also unexpected, especially when they are towards the end of the list (e.g. throws above).

  /// A magical function that does something with `x` and `y`.
  ///
  /// The behavior is outlined as:
  ///   - if `x` is magical, do something cool
  ///   - if `y` is magical, do something even cooler
  ///
  /// - parameters:

The use of Markdown is great, but it seems like it would be better if the comment block was sectioned and the content was parsed as Markdown.

  /// A magical function that does something with `x` and `y`.
  ///
  /// The behavior is outlined as:
  ///
  ///   - if `x` is magical, do something cool
  ///   - if `y` is magical, do something even cooler
  ///
  /// [parameters]
  ///   - x The first magic number.
  ///   - y The second magic number.
  ///
  /// [param] x The fist magic number (inlined)
  /// [param] y The second magic number (inlined)
  ///
  /// [throws]
  /// A `NonMagicalError` if either `x` or `y` is `0`.
  ///
  /// [returns] The magic operation of `f(x, y)`.
  func f(x: Int, y: Int) throws -> Int { ... }

Also, this would facilitate better documentation features as well. When in the [parameters] section, typing “-“ could offer the set of undocumented parameter names. 

At the top-level, typing “[“ (or “:”, “|”, whatever…) could offer the completion list of supported, parseable sections applicable to the type.