Tools for formatting doc comment linebreaks?

are there any tools available to help automatically format doc comments to a particular width?

1 Like

SwiftFormat does that for non-doc comments, and was subsequently fixed for doc comments too.

i tried running SwiftFormat on a project, but as it turns out, it can only narrow the doccomment blocks if they exceed a maximum width; it can’t actually reformat them to a consistent width if they are overly/inconsistently linebroken.

for example, i have a doccomment that looks like:

/// Sends the given command document over this connection, unchanged, and awaits its
/// message-response.
///
/// If the deadline passes without a reply from the server, the channel will be closed. This
/// will happen even if the
/// deadline has already passed;
/// therefore it is the responsibility of the calling code to check if the
/// deadline is sensible.
private static
func request(_ channel:any Channel,

and i would like to be able to reformat it into a rectangle, like:

/// Sends the given command document over this connection, unchanged, and awaits its
/// message-response.
///
/// If the deadline passes without a reply from the server, the channel will be closed. This
/// will happen even if the deadline has already passed; therefore it is the responsibility 
/// of the calling code to check if the deadline is sensible.
private static
func request(_ channel:any Channel,

since this can only be done safely within markdown paragraphs, i imagine this would require the formatter to parse the markdown tree.

1 Like

Now that apple/swift-format has a dependency on swift-markdown for structured parsing of doc comments, one thing I've had on my wish list for a while is a configuration setting to reflow them using swift-markdown to re-render them as Markdown after it's been parsed. It would be nice to have a single canonical format for comments and the Params/Returns/etc. block, but I haven't had the free time to dive into it.

If anyone wanted to take a stab at a PR, it'd be very welcome!

1 Like

yes this would be incredibly valuable. among other things, it would be nice to be able to automatically modernize DocC symbol links to remove hash parameters and unnecessary disambiguation.

4 Likes