Automatically Formatting Doc Comments


#1

I’m having trouble finding the best way to automate managing the line length of doc comments. Is everyone else just doing this manually or are there any tools to help manage.

I’m using Sublime Text. Would appreciate if anyone could point me in the right direction on how to approach setting that up or if any other tools / scripts are known about.


#2

Sublime Text has the Alt+Q command. It will automatically wrap the lines at the preferred line length (80 char by default). It’s even aware of the special characters at the beginning of the line (like ///).


#3

I tend to use the par command for this. I have this in my .vimrc:

vmap \g !par T4 B=. 79qr<CR>

#4

@ogeon:
Ok yeah I messed around with Alt+Q but it just generally mangles up all my comments and I never could find any clear information about how to configure it.

For example, if I have some text like this:

//! A really great module that does amazing things.
//!
//! A cleverly worded short bit of info.
//!
//! A really ridiculously long and repetitive explanation about every tiny detail. A really ridiculously long and repetitive explanation about every tiny detail. A really ridiculously long and repetitive explanation about every tiny detail. A really ridiculously long and repetitive explanation about every tiny detail. A really ridiculously long and repetitive explanation about every tiny detail. A really ridiculously long and repetitive explanation about every tiny detail. 
//! 

Alt+Q turns it into this:


//! A really great module that does amazing things. //! //! A cleverly worded
short bit of info. //! //! A really ridiculously long and repetitive
explanation about every tiny detail. A really ridiculously long and repetitive
explanation about every tiny detail. A really ridiculously long and repetitive
explanation about every tiny detail. A really ridiculously long and repetitive
explanation about every tiny detail. A really ridiculously long and repetitive
explanation about every tiny detail. A really ridiculously long and repetitive
explanation about every tiny detail.  //!

As I’m typing this I just found this repo which I’m going to have a look at.

@BurntSushi:
Awesome thanks, I might just go that route and pop open vi to format those when needed if I can’t find an easier solution.


#5

That sounds painful! :slight_smile: I’m not familiar with Sublime, but if it has an ability to “send highlighted text to stdin of a command and replace it with stdout of said command” then you should be able to use par for that.

par handles the //! intelligently as well (among other things). It was built to properly format emails containing quotes, which are structured a lot like line comments. :slight_smile:


#6

Yup, I’m dusting off par right now. Haven’t used it in like 15 years. Thanks for pointing me in the right direction!


#7

That’s strange. It usually happens when it fails to recognize the first characters as a prefix. You will also have to make sure that there is an empty line between the paragraphs you are wrapping (you can add //! to it after wrapping), otherwise it will just mash them together.

Oh, that looks interesting.


#8

I would say rustfmt is a good tool for that, but it has issues formatting doc comments:


#9

If you just need to format a single paragraph in vim, gqip will do it (go format inside paragraph).