Typealiased type are not reflected properly in the documentation

[mackoj]

Description

In the situation below the generated documentation is wrong because Foo should have the Initializers and Type Properties in it's documentations and not Generic.

import Foundation

// This a generic wrapper
public struct Generic<T, S> {
  
}

// Foo is a contextual application of `Generic`
public typealias Foo = Generic<Int, String>

extension Foo {
  /// This should be for Foo and not Generic
  public init(_ inputNumber: Int, _ inputString: String) { }
}

extension Foo {
  /// The red state for Foo.
  public static var red: Self { Foo(1, "toto") }
}

Generic	Foo

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

Foo should have the Initializers and Type Properties in the documentation.

Actual behavior

Generic display having the Initializers and Type Properties in the documentation.

Steps To Reproduce

1. Using Xcode Version 15.0 (15A240d)
2. Using the code below the issue appear when generating documentation.

import Foundation

// This a generic wrapper
public struct Generic<T, S> {
  
}

// Foo is a contextual application of `Generic`
public typealias Foo = Generic<Int, String>

extension Foo {
  /// This should be for Foo and not Generic
  public init(_ inputNumber: Int, _ inputString: String) { }
}

extension Foo {
  /// The red state for Foo.
  public static var red: Self { Foo(1, "toto") }
}

Swift-DocC Version Information

swift-5.9-RELEASE

Swift Compiler Version Information

swift-driver version: 1.87.1 Apple Swift version 5.9 (swiftlang-5.9.0.128.108 clang-1500.0.40.1)
Target: arm64-apple-macosx13.0

[mackoj]

Hi @d-ronnqvist,

Any idea if this is a user error or something that should be fixed ?

Thanks,

[d-ronnqvist]

Any idea if this is a user error or something that should be fixed ?

One could argue that this is the correct behavior because the type alias isn't its own symbol, and any extension you add to the aliased symbol are also available on the aliased type.

In other words; in source code you can still call .red on Generic when its two generic type are Int and String. As such, I feel that it would be incorrect to remove init(_:,_:) and red from the Generic page because those members are available when the generic constraints are met.

That leaves the question of what should be displayed on the page for the type alias. Currently the alias doesn't display any members of the type that it is an alias of. We could choose to duplicate all the members from the aliased type but I'm not sure that would be better. For example, say that a developer defines an alias for readability

public struct Record {
    public typealias Identifier = Int
}

IMO the most important information on the Record.Identifier page is that the identifier is an integer. If I want to see all the API that's available for integers that's just a click away. We could reconsider this behavior but that type of change should be discussed in the Swift Forums.

[mackoj]

I do understand your point of view, and I agree that a typealias is not a real type. However, when you can extend a typealias, I believe this code should be included in the typealias documentation.

As suggested, I will post on the forum to gather input from other people.

Thanks,

[joshuapoq]

I'm not sure whether to raise a separate issue or ask for help in the forums but I'm facing a similar problem where I cannot reference public symbols in extensions for typealiases of generic types (struct or class).

In the scenario posted here I can't reference red or the initialiser. The generated docs show red with a symbol path of Generic/red. I'd agree that preferably that should be Foo/red but neither work and I can't figure out a way to reference this symbol.

In my scenario I'm adding dependency injection namespaces via a generic and typealiases. From a code perspective the namespaces work as expected only exposing properties per specialised typealias. From a docs perspective I cannot reference these and they're all grouped under the single generic. I know I can replace the specialised types with concrete types to solve this but am looking to avoid that.