Attachment: Download

Issue Description:

I'm finding that Swift-DocC's line breaking is sometimes a bit awkward. For example:

Line break in the middle of the name "BidirectionalCollection"

Line break in the middle of the name "StringProtocol"

Line break in the middle of the dictionary sugar's value type

Line break in the middle of a constraint.

—

This is obviously a very difficult problem - in the long-term, pie-in-the-sky ideal case, we'd have some kind of WebAssembly version of swift-format, using the compiler's syntax parser to dynamically and intelligently break the symbol based on its meaning and the available width.

In the mean time, it turns out that Swift-DocC is automatically inserting word-breaks, but does so at very strange positions. In the first example, there are HTML <wbr> tags between "String" and "Protocol" and between "Bidirectional" and "Collection". Removing those improves the situation a little, and BDC no longer breaks in the middle:

But it may be possible to improve this yet further, with better tuning of where we emit non-breaking spaces and explicit word breaks/zero-width spaces. For example, if I replace the spaces in the generic constraints list with non-breaking spaces, we get a much nicer result:

As for what these rules could look like, I would suggest the following as a starting point, although they'll likely need some experimentation and tweaking:

• A function's name, generic parameter list, and opening bracket of the parameter list, should all be considered a single unit, with a word-break/ZWSP after the opening bracket.

• "label name: Type" elements in a function's parameter list should internally use non-breaking spaces, and be separated from each-other by breaking spaces; we'd prefer breaks before/after each parameter than in the middle of one.

• A function's parameter list's closing bracket, effects (throws, async) and return type should likewise be considered a single unit, with a word-break/ZWSP before the parameter list's closing bracket and after the return type and non-breaking spaces within that region.

• Word-break between a function's return type and where clause

• "GenericType : MyProto" elements in a function's where clause should be considered a single unit for text flow and internally use non-breaking spaces, just like function parameters.

Applying these to the 3rd example, it looks much better, and more readable. It still not absolutely perfect - I'd love for the closing bracket to reset the indentation, but I can't think of a way to express that with Unicode line breaks. Perhaps that's something where Swift-DocC-render could add some heuristics if it thinks the parameter list is likely to need line breaks, so it can try to keep that section isolated to set of lines with the fewest internal line breaks.