[SR-15407] DocC (wrongly) renders actors as classes

[ktoso]

[SR-15407] DocC (wrongly) renders actors as classes

[QuietMisdreavus]

It looks like there are two parts to this issue:

1. Ensuring actors show up as `actor SomeActor` in topic listings, and

2. 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.

[heckj]

I'm taking a stab at fixing this per @QuietMisdreavus guidelines. Feedback very welcome.

[ktoso]

[franklinsch]

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": {…}
},

[ktoso]

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.

[ktoso]

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 🙂

[FranzBusch]

+1 just ran into this myself and found it pretty confusing

[akbashev]

+1
Also just noticed that, a bit misleading when working with actors.

UPD: +1 also for distributed actors