`toRawComment` takes a range of line/block ordinary/doc comments and
converts them into a `RawComment` that should represent the doc comment
for the attached decl.
Fix a bunch of unhandled cases:
- A prior comment with whitespace in between would cause the first
line of the next comment to be missed
- A gyb comment would attach the prior comment, regardless of
whitespace inbetween
Resolves rdar://82414210
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.
Various uses of `getPresumedLineAndColumnForLoc` were likely added when
that function was the very misleading name `getLineAndColumn`. Change
these to use `getLineAndColumnForBuffer` instead where appropriate, ie.
we want the underlying file rather than the location to display to the
user.
There were also some cases where the buffer identifier had been swapped
to use the display name instead, under the assumption that the presumed
location was needed. Updated those as well.
SingleRawComment: Lines are only used when merging comments, where the
original location is fine to use.
Index: Doesn't store the file set in #sourceLocation, so using the
presumed line would end up pointing to a location that makes no sense.
Editor functionality: Formatting and refactoring are on the current
file. Using the presumed location would result in incorrect
replacements.
For example 'SourceFile' can handle all operations inside
'getSerializedLocs()', but it unnecessarily loads source content in a
new buffer, and resolve 'SourceLoc' from the line and the column.
And the result is completely useless.
rdar://problem/75010520
- Add DocRangesLayout to the `.swiftsourceinfo`.
This is a blob containing an array of `SingleRawComment`
source locations.
- Add DocLocWriter for serializing `SingleRawComment` locs into the
`DocLocsLayout` buffer.
Serialize start line, start column, and length of `SingleRawComment`
pieces in `.swiftsourceinfo`
- Read doc locs when loading basic declaration locs from a ModuleFile.
- Load `DOC_LOCS` blob into ModuleFile::DocLocsData
- Reconstitute RawComment ranges when available from .swiftsourceinfo
- Allow requesting serialized raw comment if available
rdar://problem/58339492
Most of AST, Parse, and Sema deal with FileUnits regularly, but SIL
and IRGen certainly don't. Split FileUnit out into its own header to
cut down on recompilation times when something changes.
No functionality change.
Previously, the Lexer kept a single flag whether we’re lexing Swift or SIL. Instead, keep track if we’re parsing Swift, SIL, or a Swiftinterface file. .swiftinterface files allow $-prefixed identifiers anywhere.
Having this be a single buffer hardcoded in the SourceManager and set
by all clients is silly. SourceFiles with the 'Main' kind are allowed
to have hashbang lines (`#!`), other files are not. And anyone
manually setting up a Lexer can decide for themselves.
No intended behavioral change.
Introduce ExtensionDecl::getExtendedNominal() to provide the nominal
type declaration that the extension declaration extends. Move most
of the existing callers of the callers to getExtendedType() over to
getExtendedNominal(), because they don’t need the full type information.
ExtensionDecl::getExtendedNominal() is itself not very interesting yet,
because it depends on getExtendedType().
llvm::SourceMgr caches the line and column of the last query. It
usually scans from that position for subsequent queries. However, if the
query is for a position ahead of the last query, it re-scan from the top
of the whole buffer. This significally slows down the performance.
This change effectively mitigate performance regression introduced in
https://github.com/apple/swift/pull/11264 without functional changes.
Add an option to the lexer to go back and get a list of "full"
tokens, which include their leading and trailing trivia, which
we can index into from SourceLocs in the current AST.
This starts the Syntax sublibrary, which will support structured
editing APIs. Some skeleton support and basic implementations are
in place for types and generics in the grammar. Yes, it's slightly
redundant with what we have right now. lib/AST conflates syntax
and semantics in the same place(s); this is a first step in changing
that to separate the two concepts for clarity and also to get closer
to incremental parsing and type-checking. The goal is to eventually
extract all of the syntactic information from lib/AST and change that
to be more of a semantic/symbolic model.
Stub out a Semantics manager. This ought to eventually be used as a hub
for encapsulating lazily computed semantic information for syntax nodes.
For the time being, it can serve as a temporary place for mapping from
Syntax nodes to semantically full lib/AST nodes.
This is still in a molten state - don't get too close, wear appropriate
proximity suits, etc.
Store leading a trailing "trivia" around a token, such as whitespace,
comments, doc comments, and escaping backticks. These are syntactically
important for preserving formatting when printing ASTs but don't
semantically affect the program.
Tokens take all trailing trivia up to, but not including, the next
newline. This is important to maintain checks that statements without
semicolon separators start on a new line, among other things.
Trivia are now data attached to the ends of tokens, not tokens
themselves.
Create a new Syntax sublibrary for upcoming immutable, persistent,
thread-safe ASTs, which will contain only the syntactic information
about source structure, as well as for generating new source code, and
structural editing. Proactively move swift::Token into there.
Since this patch is getting a bit large, a token fuzzer which checks
for round-trip equivlence with the workflow:
fuzzer => token stream => file1
=> Lexer => token stream => file 2 => diff(file1, file2)
Will arrive in a subsequent commit.
This patch does not change the grammar.
If a class member doesn't have a doc comment but a base class does, show
the base class's comment and add a note about where it came from.
rdar://problem/16512247
Let's say I am a good citizen and document my private symbols:
/** My TOP SECRET DOCUMENTATION */
private class Foo {
}
When I go to distribute the compiled binary, I find out my private
documentation is distributed as well:
$ swiftc test.swift -emit-module -module-name "test"
$ strings test.swiftdoc
My TOP SECRET DOCUMENTATION
/** My TOP SECRET DOCUMENTATION */
If a client can't use a symbol (e.g. it's private [or internal and not
-enable-testing]) don't emit the documentation for a symbol in the
swiftdoc.
Fixes: SR-762, rdar://21453624
The test coverage implements this truth table:
| visibility | -enable-testing | documentation? |
|------------|-----------------|----------------|
| private | no | ❌ |
| internal | no | ❌ |
| public | no | ✅ |
| private | yes | ❌ |
| internal | yes | ✅ |
| public | yes | ✅ |
Modified the existing comments test coverage to expect non-public
documentation not to be emitted.
Don't rely on existing comment structure
Refuse to emit comments if the decl cannot actually have one. To
accomplish this, we move `canHaveComment` into the Decl instance. It
must also be marked `const`, since one of its existing usages operates
on a const pointer.
Perform fewer checks when serializing the standard library.
Gyb started emitting more line markers, which are sometimes inserted in
the middle of doc comments, and I can't find a trick to prevent that.
Skip these comments in the source code for now.
rdar://21882721
Swift SVN r30337
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
