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
Instead of appending a character for each substitution, we now prefix the substitution with the repeat count, e.g.
AbbbbB -> A5B
The same is done for known-type substitutions, e.g.
SiSiSi -> S3i
This significantly shrinks mangled names which contain large lists of the same type, like
func foo(_ x: (Int, Int, Int, Int, Int, Int, Int, Int, Int, Int, Int, Int))
rdar://problem/30707433
In Swift, init() is represented as a class method, but in ObjC it is an
instance method. This fixes the USRs we generate for @objc inits so they
match the ObjC USRs.
rdar://problem/30707115
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
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
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.
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
And include some supplementary mangling changes:
- Give the first generic param (depth=0, index=0) a single character mangling. Even after removing the self type from method declaration types, 'Self' still shows up very frequently in protocol requirement signatures.
- Fix the mangling of generic parameter counts to elide the count when there's only one parameter at the starting depth of the mangling.
Together these carve another 154KB out of a debug standard library. There's some awkwardness in demangled strings that I'll clean up in subsequent commits; since decl types now only mangle the number of generic params at their own depth, it's context-dependent what depths those represent, which we get wrong now. Currying markers are also wrong, but since free function currying is going away, we can mangle the partial application thunks in different ways.
Swift SVN r32896
'Ss' appears in manglings tens of thousands of times in the standard library and is also incredibly frequent in other modules. This alone is enough to shrink the standard library by 59KB.
Swift SVN r32409
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
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
This lets us disambiguate the symbols for static and instance properties, and enables us to eventually leave the useless "self" type mangling out of method symbols. Fixes rdar://19012022 and dupes thereof, including crasher #1341.
Swift SVN r25111
This change adds infrastructure to represent inline markup in the AST,
implements parsing of some of the inline markup (*emphasis*, **strong
emphasis**, `interpreted text`, ``inline literal``), and XML generation
for these constructs for SourceKit clients to consume.
The parsing itself is incomplete for constructs not mentioned above.
Most notably, we don't parse hyperlinks, and we don't parse the
double-colon that changes the next paragraph into a literal block.
Swift SVN r22752
- Change the parser to accept "objc" without an @ sign as a contextual
keyword, including the dance to handle the general parenthesized case.
- Update all comments to refer to "objc" instead of "@objc".
- Update all diagnostics accordingly.
- Update all tests that fail due to the diagnostics change.
- Switch the stdlib to use the new syntax.
This does not switch all tests to use the new syntax, nor does it warn about
the old syntax yet. That will be forthcoming. Also, this needs a bit of
refactoring, which will be coming up.
Swift SVN r19555
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
