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
allevato
(Tony Allevato)
4
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
