SourceKit-LSP currently parses the XML comment to generate Markdown again but round-tripping a (probably markdown) doc comment to XML to Markdown is lossy in many cases and unnecessary work. Include the comment as it is spelled in source in the cursor info response so that sourcekit-lsp can display it.
Part of rdar://120685874
We would previously hide the protocol, its extensions and members, but the '_'
prefix really just means the protocol itself isn't intended for clients, rather
than its members.
This also adds support for 'fully_annotated_decl' entries in doc-info for
extensions to be consistent with every other decl, and removes the
'fully_annotated_generic_signature' entry we supplied as a fallback.
Also fixes several bugs with the synthesized extensions mechanism:
- The type sustitutions applied to the extension's requirements were computed
using the extension itself as the decl context rather than the extension's
nominal. The meant the extension's requirements themselves were assumed to
hold when determining the substitutions, so equality constraints were always
met. Because of this extension members were incorrectly merged with the base
nominal or its extensions despite having additional constraints.
- Types within the requirements weren't being transformed when printed (e.g.
'Self.Element' was printed rather than 'T') both in the interface output and
in the requirements list. We were also incorrectly printing requirements
that were already satisfied once the base type was subsituted in.
- If both the protocol extension and 'enabling' extension of the base nominal
that added the protocol conformance had conditional requirements, we were
only printing the protocol extension's requirements in the synthesized
extension.
- The USR and annotated decl output embedded in the 'key.doc.full_as_xml'
string for synthesized members were printed to match their original context, rather than
the synthesized one.
Resolves rdar://problem/57121937
If a documentation comment has a - LocalizationKey: field, strip it
out of the documentation body and report it in cursor/doc info with
the key "key.localization_key".
rdar://problem/30383329
Some modifications for the ms-extension option of the clang.exe in the Visual Studio 2015 development environment
This patch is only for swiftc.exe. I used the library set of Visual Studio 2015 Update 1 and recent version of swift-clang as the compiler. If you are using the real MSVC compiler, more patch might be required.
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
