This information needs to be picked up through SourceKit. It might be
useful as both metadata for sorting/filtering as well as presentation,
so it makes sense to print it in the normal XML inside CommentParts.
rdar://problem/32877771
Under parameter doc comment list items, allow function doc comment
syntax to nest so you can document the meaning of closure parameters'
signatures.
rdar://problem/24794725
Add a language property for Markup code blocks - the default is
"swift" but will respect overrides such as the following:
```c++
Something::Somethign::create()
```
For code listings in doc comments written in other languages, such
as when you want to compare usage against another language.
rdar://problem/23948115
Adding the following to a doc comment:
- throws: ...
Will create a description about what/when the function will throw.
This should be a peer to "- returns:" and "- parameter:" and not appear
inline in the description.
rdar://problem/21621679
Swift SVN r29831
Replace ReST-flavored documentation comments with Markdown.
rdar://problem/20180412
In addition to full Markdown support, the following extensions are
supported. These appear as lists at the top level of the comment's
"document". All of these extensions are matched without regard to
case.
Parameter Outlines
------------------
- Parameters:
- x: ...
- y: ...
Separate Parameters
-------------------
- parameter x: ...
- parameter y: ...
- Note:
Parameter documentation may be broken up across the entire comment,
with a mix of parameter documentation kinds - they'll be consolidated
in the end.
Returns
-------
- returns: ...
The following extensions are also list items at the top level, which
will also appear in Xcode QuickHelp as first-class citizens:
- Attention: ...
- Author: ...
- Authors: ...
- Bug: ...
- Complexity: ...
- Copyright: ...
- Date: ...
- Experiment: ...
- Important: ...
- Invariant: ...
- Note: ...
- Postcondition: ...
- Precondition: ...
- Remark: ...
- Remarks: ...
- See: ...
- Since: ...
- Todo: ...
- Version: ...
- Warning: ...
These match most of the extra fields in Doxygen, plus a few more per request.
Other changes
-------------
- Remove use of rawHTML for all markup AST nodes except for those
not representable by the Xcode QuickHelp XSLT - <h>, <hr/>, and of
course inline/block HTML itself.
- Update the doc comment RNG schema to more accurately reflect Xcode
QuickHelp.
- Clean up cmark CMake configuration.
- Rename "FullComment" to "DocComment"
- Update the Swift Standard Documentation (in a follow-up commit)
- Update SourceKit for minor changes and link against cmark
(in a follow-up commit).
Swift SVN r27727
This commit adds infrastructure for conversion and testing it.
The conversion is still incomplete, pending discussion about which tags should
we use in the XML documents. I copied the RelaxNG schema from Clang, and will
edit it accordingly.
Swift SVN r16451
