For example when we have
```swift
protocol BaseProtocol {}
extension BaseProtocol {
/// Say hello
func hello() { }
}
struct MyStruct: BaseProtocol {
func hello() {}
}
```
Then `MyStruct.hello` should inherit the doc comment from the implementation of `BaseProtocol.hello`. Currently no doc comment is associated with `MyStruct.hello`.
rdar://126240546
Although I don't plan to bring over new assertions wholesale
into the current qualification branch, it's entirely possible
that various minor changes in main will use the new assertions;
having this basic support in the release branch will simplify that.
(This is why I'm adding the includes as a separate pass from
rewriting the individual assertions)
`StringRef::endswith_insensitive` and
`StringRef::startswith_insensitive` is deprecated and being replaced
with `StringRef::ends_with_insensitive` and
`StringRef::starts_with_insensitive` respectively.
Reformatting everything now that we have `llvm` namespaces. I've
separated this from the main commit to help manage merge-conflicts and
for making it a bit easier to read the mega-patch.
This is phase-1 of switching from llvm::Optional to std::optional in the
next rebranch. llvm::Optional was removed from upstream LLVM, so we need
to migrate off rather soon. On Darwin, std::optional, and llvm::Optional
have the same layout, so we don't need to be as concerned about ABI
beyond the name mangling. `llvm::Optional` is only returned from one
function in
```
getStandardTypeSubst(StringRef TypeName,
bool allowConcurrencyManglings);
```
It's the return value, so it should not impact the mangling of the
function, and the layout is the same as `std::optional`, so it should be
mostly okay. This function doesn't appear to have users, and the ABI was
already broken 2 years ago for concurrency and no one seemed to notice
so this should be "okay".
I'm doing the migration incrementally so that folks working on main can
cherry-pick back to the release/5.9 branch. Once 5.9 is done and locked
away, then we can go through and finish the replacement. Since `None`
and `Optional` show up in contexts where they are not `llvm::None` and
`llvm::Optional`, I'm preparing the work now by going through and
removing the namespace unwrapping and making the `llvm` namespace
explicit. This should make it fairly mechanical to go through and
replace llvm::Optional with std::optional, and llvm::None with
std::nullopt. It's also a change that can be brought onto the
release/5.9 with minimal impact. This should be an NFC change.
This source location will be used to determine whether to add a name lookup
option to exclude macro expansions when the name lookup request is constructed.
Currently, the source location argument is unused.
If we have both loaded a swiftdoc, and the decl we
have should have had its doc comment serialized into
it, we can check it without needing to fall back
to the swiftsourceinfo.
This requires a couple of refactorings:
- Factoring out the `shouldIncludeDecl` logic
into `getDocCommentSerializationTargetFor` for
determining whether a doc comment should end up
in the swiftdoc or not.
- Factoring out `CommentProviderFinder` for searching
for the doc providing comment decl for brief
comments, in order to allow us to avoid querying
the raw comment when searching for it. This has the
added bonus of meaning we no longer need to fall
back to parsing the raw comment for the brief
comment if the comment is provided by another decl
in the swiftdoc.
This diff is best viewed without whitespace.
It doesn't seem like there's any client that's
actually taking advantage of setting it to `false`,
and its default value of `false` is more likely
than not going to cause clients to accidentally
miss comments that they may want. In fact, this
was exactly the case for code completion's brief
field. Finally, the parameter wasn't even
consistently applied, as we would attempt to
deserialize swiftdoc comments even if it were
`false`.
`getValue` -> `value`
`getValueOr` -> `value_or`
`hasValue` -> `has_value`
`map` -> `transform`
The old API will be deprecated in the rebranch.
To avoid merge conflicts, use the new API already in the main branch.
rdar://102362022
The `equals_lower` API was replaced with `equals_insensitive` in llvm
commit 2e4a2b8430aca6f7aef8100a5ff81ca0328d03f9 and
3eed57e7ef7da5eda765ccc19fd26fb8dfcd8d41.
Ran git clang-format.
(cherry picked from commit e21e70a6bf)
Emit copies of default implementations in protocol extensions and superclass declarations in conforming types and subclasses respectively using a virtual USR, i.e. `${REAL_USR}::SYNTHESIZED::${CONFORMING_OR_SUBCLASS_TYPE_USR}`.
- Add a -skip-synthesized-members option to skip these synthesized members.
- Create a new wrapping `Symbol` type that can also contain a base type declaration as well as the inherited declaration for those synthesized cases. Move some symbol-specific APIs there.
- Doc comments can “cascade” down to protocol extensions or refinements in concrete types. When emitting the doc comment for a symbol, look up through to superclasses or protocol requirements for where a doc comment is actually written.
- Clean up filtering of implicitly private (e.g. “public underscored”) types
rdar://problem/59128787
- 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
- getAsDeclOrDeclExtensionContext -> getAsDecl
This is basically the same as a dyn_cast, so it should use a 'getAs'
name like TypeBase does.
- getAsNominalTypeOrNominalTypeExtensionContext -> getSelfNominalTypeDecl
- getAsClassOrClassExtensionContext -> getSelfClassDecl
- getAsEnumOrEnumExtensionContext -> getSelfEnumDecl
- getAsStructOrStructExtensionContext -> getSelfStructDecl
- getAsProtocolOrProtocolExtensionContext -> getSelfProtocolDecl
- getAsTypeOrTypeExtensionContext -> getSelfTypeDecl (private)
These do /not/ return some form of 'this'; instead, they get the
extended types when 'this' is an extension. They started off life with
'is' names, which makes sense, but changed to this at some point. The
names I went with match up with getSelfInterfaceType and
getSelfTypeInContext, even though strictly speaking they're closer to
what getDeclaredInterfaceType does. But it didn't seem right to claim
that an extension "declares" the ClassDecl here.
- getAsProtocolExtensionContext -> getExtendedProtocolDecl
Like the above, this didn't return the ExtensionDecl; it returned its
extended type.
This entire commit is a mechanical change: find-and-replace, followed
by manual reformatted but no code changes.
Switch a number of callers of the Type-based lookupQualified() over to
the newer (and preferred) declaration-based lookupQualified(). These are
the easy ones; NFC.
You can now specify multiple - Tag: simple fields in documentation
comments for general purpose use. These are not currently intended
to show up in rendered documentation but are for metadata purposes
only.
Name lookup into a class type always looks into its supertypes; if you
want to look directly into a particular class and its extensions, use
lookupDirect and filter.
This allows authors to not have to copy and paste doc comments
from requirements to default implementations to get documentation.
For now, this will only be active if a protocol doesn't inherit
two equivalent requirements from other protocols with doc comments.
Those will need special treatment and it would be better not to just
copy and paste them into the same doc comment. More output structure
is needed to differentiate documentation for different protocols'
requirements.
rdar://problem/16512247
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
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
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
