Type aliases are not resolved, in particular for autolinks

[reitzig]

I'm hope I'm getting it right this time! :D

Consider code like this:

public class Foo {
    public var foo: Bool = false
}

typealias HideMe = Foo
public extension HideMe {
    /// It's here!
    public var foo2: Bool { return true }
}

public class Bar {
    /// You know about `Foo.foo`, `Foo.foo2`, `HideMe.foo` and `HideMe.foo2`?
    public func bar() {}
}

It leads to three things:

1. The extension property foo2 is listed separately under "Extensions" instead of being included into the documentation of Foo, as it would be for extension Foo { ... }.

   Reasons can be given for either behaviour, I think.

2. Auto-linking only works with the syntactic path; the typealias is ignored.

   

   All these references should autolink.

3. If the type alias has a documentation comment, there will be three entries in total: Foo, HideMe under "Extensions", and HideMe under "Typaliases", spreading out the documentation quite a bit.

   Reasons can be given for this being by design, or for this being a bad idea. If the latter, a broader discussion about what should go on one page might be in order.

[reitzig]

What I can't reproduce in the MWE: In my production code, not even HideMe.foo2 auto-links. The only difference I can tell is that, there, Foo is defined in another module. I'd expect the autolink to the extension property given in the current module to autolink, anyway.

[johnfairh]

This is a mixture of bugs and 'how things happen to work'. A SourceKit bug means that typealias declarations need a doc-comment for jazzy to even see them, and explicit accessibility to avoid them being treated as public. Autolinking through typealiases is not implemented. The issue in prod is probably related to declaration ordering: try moving the typealias decl below the extension decl.

In the case where the project contains both the original type (class Foo) and the extension (extension HideMe) the simplest thing feels like making jazzy behave as though user wrote extension Foo. Meaning that there would be one top-level decl for class Foo covering both foo and foo2, and one further top-level decl for typealias HideMe (iff min-acl < public).

[tbh "the simplest thing" is respectfully asking the author to write "extension Foo" but I guess they probably have a good reason for doing what they did!]

[reitzig]

In the case where the project contains both the original type (class Foo) and the extension (extension HideMe) the simplest thing feels like making jazzy behave as though user wrote extension Foo. Meaning that there would be one top-level decl for class Foo covering both foo and foo2, and one further top-level decl for typealias HideMe (iff min-acl < public).

That sounds very reasonable.

[tbh "the simplest thing" is respectfully asking the author to write "extension Foo" but I guess they probably have a good reason for doing what they did!]

In my case, I have a type SecureData in module A, and I want to alias it Password in module B so the API is clearer for users. Now, adding a property in B I have to use extension Password, otherwise it's less clear (in code and doc) what the property is added to; plus, I don't need/want readers/users of B to see SecureData or have to know that it exists. The typealias being documented is fine; the goal would be that if someone clicked an auto-linked Password, they'd end up on a page with the typealias and it's doc and extensions with matching name.

Not sure how I'd like extensions to SecureData in B to be treated.