Comments (8)
I'm taking a stab at fixing this per @QuietMisdreavus guidelines. Feedback very welcome.
from swift-docc.
It looks like there are two parts to this issue:
-
Ensuring actors show up as `actor SomeActor` in topic listings, and
-
Organizing actors (and potentially also distributed actors) into separate topic listings.
The first is relatively easy; the second requires some greater design effort in Swift-DocC to allow symbol graphs to customize the automatic topic organization behavior. I would suggest proposing that on the forums and splitting it into its own issue.
For the first, the change needs to happen in the compiler, in lib/SymbolGraphGen/DeclarationFragmentsPrinter.cpp
, in the printAbridgedType
function. This is used by SymbolGraphGen to emit "sub-headings" and "navigator headings", which are used by DocC to render symbols in topic listings. Changing the lines that emit the kw_class
keyword to instead convert TD
into a ClassDecl
and check isActor()
to determine which keyword to emit (and additionally check isDistributedActor()
to emit the distributed
keyword as well) will allow actors to properly show up in class listings with the actor
keyword.
from swift-docc.
from swift-docc.
It looks like the Swift compiler is treating actors as classes in symbol graph file generation. This is the data I'm seeing for an actor I defined:
{
"kind": {
"identifier": "swift.class",
"displayName": "Class"
},
"identifier": {
"precise": "s:12Test5HelloC",
"interfaceLanguage": "swift"
},
"pathComponents": […],
"names": {…},
"declarationFragments": [
{
"kind": "keyword",
"spelling": "actor"
},
{…},
{…}
],
"accessLevel": "public",
"availability": […],
"location": {…}
},
from swift-docc.
Yeah, that's correct – they are `ClassDecl` but you need to check the keyword it is declared with and treat it separately as an actor if it was declared as actor.
A distributed actor will also have a modifier
distributed. so "is distributed actor?" means: was introduced using actor keyword
+ has modifier distributed
.
Those should also be listed as distributed actor
but they can be under the actors "section" I guess.
from swift-docc.
If it helps, this is how we detect them in SwiftSyntax, if you want to do this on the consuming end of symbols you'd do the same here I suppose:
extension ClassDeclSyntax {
var isActor: Bool {
classOrActorKeyword.text == "actor"
}
var isDistributedActor: Bool {
guard isActor else {
return false
}
guard let mods = self.modifiers else {
return false
}
for mod in mods where mod.name.text == "distributed" {
return true
}
return false
}
}
If you want to do it in the compiler, then the Decls have accurate isActor()
and isDistributedActor()
functions you can use 🙂
from swift-docc.
+1 just ran into this myself and found it pretty confusing
from swift-docc.
+1
Also just noticed that, a bit misleading when working with actors.
UPD: +1 also for distributed actors
from swift-docc.
Related Issues (20)
- Linkable glossary
- Document Objective-C extensions with DocC HOT 2
- Xcode "Build documentation" not working with Swift Macro package in project HOT 5
- Curating a module under a technology root causes the sidebar to not show Objective-C symbols
- illegal hardware instruction HOT 4
- This mangled quote/code fence results in a crash HOT 1
- `@DeprecationSummary` directive doesn't always have an effect HOT 2
- Xcode does not provide fix for operator functions HOT 4
- Make DocC-Generated Website Indexable by Search Engines HOT 2
- Slices of Snippets don't have indentation removed HOT 1
- optional force unwrap fails if target name contains special characters
- Snippet slicing does not handle multiline string literals correctly
- Migrate to Swift 6
- Deprecated Objective-C methods not being marked as Deprecated
- Add `*` support for `@Available` directive HOT 2
- Remove duplicate semantic versioning types HOT 1
- DocC cannot generate documentation for tuple containing multiple parameter packs.
- Theme like developer.apple.com/documentation
- Interactive tutorial for building interactive tutorials
- Tutorial code delta not picking up changes in some cases
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from swift-docc.