LLVM is presumably moving towards `std::string_view` -
`StringRef::startswith` is deprecated on tip. `SmallString::startswith`
was just renamed there (maybe with some small deprecation inbetween, but
if so, we've missed it).
The `SmallString::startswith` references were moved to
`.str().starts_with()`, rather than adding the `starts_with` on
`stable/20230725` as we only had a few of them. Open to switching that
over if anyone feels strongly though.
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
The primary goal is to fix this warning:
$PROJECT_PATH/swift-project/swift/lib/Markup/LineList.cpp:46:10: warning: variable 'Col' set but not used [-Wunused-but-set-variable]
size_t Col = 0;
I also rewrote the implementation to use StringRef functionality instead
of manually walking over the characters.
The start and end lines were only used while constructing the comments,
so move the line tracking into that method instead of storing it in each
comment.
LineList Line end locations were getting cut off too early because they were
based on the untrimmed (w.r.t. comment markers) locations, instead of the
trimmed one.
Adds a tool `swift-symbolgraph-extract` that reads an existing Swift
module and prints a platform- and language-agnostic JSON description of
the module, primarly for documentation.
Adds a small sub-library `SymbolGraphGen` which houses the core
implementation for collecting relevant information about declarations.
The main entry point is integrated directly into the driver as a mode:
the tool is meant to be run outside of the normal edit-compile-run/test
workflow to avoid impacting build times.
Along with common options for other tools, unique options include
`pretty-print` for debugging, and a `minimum-access-level` options for
including internal documentation.
A symbol graph is a directed graph where the nodes are symbols in a
module and the edges are relationships between them. For example, a
`struct S` may have a member `var x`. The graph would have two nodes for
`S` and `x`, and one "member-of" relationship edge. Other relationship
kinds include "inherits-from" or "conforms to". The data format for a
symbol graph is still under development and may change without notice
until a specificiation and versioning scheme is published.
Various aspects about a symbol are recorded in the nodes, such as
availability, documentation comments, or data needed for printing the
shapes of declarations without having to understand specifics about the
langauge.
Implicit and public-underscored stdlib declarations are not included by
default.
rdar://problem/55346798
Doc comments assume a prefix of /** and a suffix of */
but if a user accidentally types /**/, SourceKit can crash and
bring down Xcode with certain timings. Check both ends of doc
comments before dropping characters.
rdar://problem/21105409
Swift SVN r29035
Printing Doxygen isn't inside an XML tag, so we can't just print
code block content, which may have new lines without a doc comment
marker. Also, be more robust with indentation.
+ Tests.
rdar://problem/20703026
Swift SVN r27851
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
