You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
If a type has nested types (e.g. a generic Collection with a nested Index type), then for any functions which accept or return that nested type, DocC writes out the full type name (e.g. Foo<X>.Index). Even on Foo<X>'s own documentation page.
For example, on the documentation page for WebURL.KeyValuePairs<Schema>, the index type is written out in full:
This leads to poor readability. Actually trying to understand what these functions do requires careful examination of their signatures (especially the 3rd and 4th functions, as they wrap across multiple lines).
If I go in the web inspector and shorten these names to demonstrate what they could look like, I think you'll agree that it's much easier to digest what these functions do:
It's a shame. Clearly, these function signatures are not all that complex, but the presentation in the first image makes them appear unwieldy and intimidating. This is how I wrote it in my code; I just used the name Index, and since it was in the scope of the KeyValuePairs type, the compiler knew I was talking about WebURL.KeyValuePairs<Schema>.Index.
I think it's important for DocC to present these functions in the clearest possible way, so I would like it to avoid qualifying type names which are already obvious based on context.
Checklist
If possible, I've reproduced the issue using the main branch of this package.
Interestingly, Xcode seems to do this, although it also describes some types entirely differently. Notice that the Docc-render version of insert(contentsOf:) describes the parameter as only some Collection, but Xcode includes the primary associated type (some Collection<(some StringProtocol, some StringProtocol)>)
d-ronnqvist
changed the title
Use shorter names for nested types
[SymbolGraphGen] Use shorter names for nested types
Dec 21, 2023
Similar to #70588, this information comes from the different compilers. If there's a way to emit shorter names in the declarations that would most likely be performed there.
Description
If a type has nested types (e.g. a generic Collection with a nested Index type), then for any functions which accept or return that nested type, DocC writes out the full type name (e.g.
Foo<X>.Index
). Even onFoo<X>
's own documentation page.For example, on the documentation page for
WebURL.KeyValuePairs<Schema>
, the index type is written out in full:This leads to poor readability. Actually trying to understand what these functions do requires careful examination of their signatures (especially the 3rd and 4th functions, as they wrap across multiple lines).
If I go in the web inspector and shorten these names to demonstrate what they could look like, I think you'll agree that it's much easier to digest what these functions do:
It's a shame. Clearly, these function signatures are not all that complex, but the presentation in the first image makes them appear unwieldy and intimidating. This is how I wrote it in my code; I just used the name
Index
, and since it was in the scope of theKeyValuePairs
type, the compiler knew I was talking aboutWebURL.KeyValuePairs<Schema>.Index
.I think it's important for DocC to present these functions in the clearest possible way, so I would like it to avoid qualifying type names which are already obvious based on context.
Checklist
main
branch of this package.Expected Behavior
No response
Actual behavior
No response
Steps To Reproduce
No response
Swift-DocC Version Information
Xcode 14.1 (14B47b)
Swift Compiler Version Information
The text was updated successfully, but these errors were encountered: