Align code functions documentation

Question

Is there an easy way to align a function documentation (I'm using Python) from this:

arg1 :: Some text

arg2345 :: Some very long text text text text

arg3:: Other text

to something like:

arg1    :: Some text

arg2345 :: Some very long text text 
           text text

arg3    :: Other text

where the second argument is wrapped by a maximum number of columns (I'm using a maximum of 80 columns). I'm used to align with gqip but that formats a whole paragraph. I tried recording some movements but it gets complex, I was wondering if there was a better way to do this.

Answer 1

Vim's comment formatting only handles comment characters that appear at the start of the line. However you could make use of the list formatting facility (:help 'formatlistpat') that kicks in when n is in 'formatoptions'.

So, define an appropriate pattern:

:set flp=^.*::\\s\\+

(You may need to adjust this: I don't speak Python.)

Then add n to 'formatoptions':

:set fo+=n

Now gqq on:

arg2345 :: Some very long text text text text asfd asdf asd fas fdasd fasd fas fdas fdsa fdas df sad asdf adsf asdf asdf as dfa sdfa sdf

with :set tw=40 for demonstration purposes, will result in:

arg2345 :: Some very long text text text
           text asfd asdf asd fas fdasd
           fasd fas fdas fdsa fdas df
           sad asdf adsf asdf asdf as
           dfa sdfa sdf

But you also want to align the :: markers. If you don't mind picking a column position to align on (not a bad idea: it enforces consistency and doesn't let really long argument names produce silly indentation), you can use a substitute that uses an expression as the replacement part (:help sub-replace-expression):

:s/\v(.*)\s*\ze::/\=submatch(0).repeat(' ',13-len(submatch(1)))/

Running this on:

arg1 :: Some text
arg2345 :: Some text

will produce:

arg1         :: Some text
arg2345      :: Some text

Adjust 13 to taste.

You can put it all together with a :global command:

:g/::/ s/\v(.*)\s*\ze::/\=submatch(0).repeat(' ',13-len(submatch(1)))/ | norm!gqq

Running it on a buffer with these contents:

arg1 :: Some text

arg2345 :: Some very long text text text text asfd asdf asd fas fdasd fasd fas fdas fdsa fdas df sad asdf adsf asdf asdf as dfa sdfa sdf

Don't touch me! Don't touch me! Don't touch me! Don't touch me! Don't touch me!

arg3:: Other text

produces:

arg1         :: Some text

arg2345      :: Some very long text text
                text text asfd asdf asd
                fas fdasd fasd fas fdas
                fdsa fdas df sad asdf
                adsf asdf asdf as dfa
                sdfa sdf

Don't touch me! Don't touch me! Don't touch me! Don't touch me! Don't touch me!

arg3         :: Other text

This assumes that /::/ is enough to identify a documentation line. You might want to tighten this up.