Format Swift symbol declarations using swift-format

[mportiz08]

Bug/issue #, if applicable: 135820356

Summary

This PR adds a new --enable-experimental-declaration-formatting feature flag to the docc convert command. When this new experimental flag is enabled, Swift-DocC will utilize API from the swift-format package to format Swift symbol declarations.

Example declaration:

@attached(peer) macro Test<C1, C2>(_ displayName: String? = nil, _ traits: any TestTrait..., arguments zippedCollections: Zip2Sequence<C1, C2>) where C1 : Collection, C1 : Sendable, C2 : Collection, C2 : Sendable, C1.Element : Sendable, C2.Element : Sendable

Example declaration (using --enable-experimental-declaration-formatting):

@attached(peer)
macro Test<C1, C2>(
    _ displayName: String? = nil,
    _ traits: any TestTrait...,
    arguments zippedCollections: Zip2Sequence<C1, C2>
)
where
    C1: Collection,
    C1: Sendable,
    C2: Collection,
    C2: Sendable,
    C1.Element: Sendable,
    C2.Element: Sendable

The benefits from doing this:

• swift-format can provide a canonical whitespace formatting to better present declarations across multiple lines, with added indentation when necessary
• swift-format utilizes swift-syntax, so it can make well-informed decisions on how to best format complex declarations due to the high-fidelity syntax tree AST that it provides (very hard to do in non-Swift based rendering tools)
• as the Swift language evolves, swift-format can be updated as appropriate and newer versions can be utilized by DocC
• all renderers (including Swift-DocC-Render) can use these formatted declarations directly, without needing to re-implement their own custom formatting logic in a different programming language

Some minor drawbacks:

• there will be a small added performance cost for formatting declarations when DocC previously has not done any of this logic
• introduces 2 new dependencies for the SwiftDocC package

Dependencies

Introduces 2 new Swift package dependencies used in the formatting process:

• swift-format
• swift-syntax

Testing

Steps:

1. Include the new --enable-experimental-declaration-formatting flag when running docc convert on a DocC catalog with Swift symbols
2. Verify that the Render JSON includes additional newline and indentation in the declaration tokens for symbols in certain, more complex symbols (DocC-Render has not yet been updated to render these "preformatted" declarations yet but I can provide a quick prototype of it for visually testing content in the browser if desired)

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

Open questions

I'm marking this as a draft/work-in-progress PR, because I have a few questions about the implementation for this that I would like some feedback on:

1. Due to incompatibilities between the new Swift package dependencies, I had to bump the supported macOS platform of Swift-DocC to be able to build this branch. Is there a better way to resolve the supported platforms between packages to avoid this or do something better here?
   See: https://github.com/mportiz08/swift-docc/blob/2be640012cc15aeefcda0176933b56ccec4dbc26/Package.swift#L22

2. Right now I'm just overwriting the normal tokens field in Render JSON when the feature flag is enabled. Are there any preferences on how I should approach the Render JSON?

Options:

• leave as-is and overwrite tokens when experimental flag is used
• overwrite tokens and also add a formatted: true property to the declaration JSON
• add a new formattedTokens field that lives alongside tokens

After I get help with those questions, I think it would make sense to maybe do a quick post in the Swift forums and then remove the draft status from this PR :)

[j-f1]

It would also be neat if you could format the declaration at a series of page widths (e.g. one for desktop and one for mobile) so that users on narrower screens don’t have to scroll horizontally to read the declaration!

[mportiz08]

It would also be neat if you could format the declaration at a series of page widths (e.g. one for desktop and one for mobile) so that users on narrower screens don’t have to scroll horizontally to read the declaration!

That sounds like a cool idea, although it's less clear to me how long, complex declarations should be formatted specially for small width viewports.

That could be a great future improvement if there's a clear configuration that works better for that scenario though.