Navigating HTML docs vs generated interfaces

[taylorswift]

@wadetregaskis

I remembered one additional thing: DocC's formatting of methods is pretty awful on the struct / class page, e.g.:

Mystifyingly it does a much better job on the detail page for a specific method; I don't know why it doesn't render it the same in both places.

just an update, i tried implementing this for abridged signatures on swiftinit (using the DocC PR as inspiration) and ran into the issue where it is impossible to parse the argument boundaries in an abridged signature without argument labels:

for example, in an abridged signature like:

func transform<ElementOfResult>(
    (Self.Index, Self.Element) throws -> ElementOfResult?, 
    (Self.Index, Self.Element) throws -> ElementOfResult?
) rethrows -> [ElementOfResult]

it is impossible to compute the locations of the linebreaks without the AST of the declaration, which has long been lost by the time we get the symbol information from a symbol graph.

for comparison, it is possible to compute the linebreaks from the full signature without the AST because we can pick out the externalParam tokens and insert linebreaks before them.

func transform<ElementOfResult>(
    _ a:(Self.Index, Self.Element) throws -> ElementOfResult?, 
//  ^ linebreak
    _ b:(Self.Index, Self.Element) throws -> ElementOfResult?
//  ^ linebreak
) rethrows -> [ElementOfResult]
// line break before parenthesis can be computed by counting parentheses

it would be interesting if SymbolGraphGen could emit the declaration AST instead of flattening it into tokens. but that is blocked until we have a way to serialize syntax trees to JSON.

alternatively, we could throw away the SymbolGraphGen tokens entirely and reparse at documentation-compile time with the SwiftSyntax library. i am reluctant to do this because SwiftSyntax is enormous and takes ages to compile.