CODEWITHSUNDEEP
vimcode-formatting
Sudar
Sudar

Reputation: 19992

How to align phpdoc comments in vim

Is there a easy way to align phpdoc comment blocks in vim?

I want 

/**
 * Call an API method.
 * @param string $method The API method to call, e.g. 'lists/list'
 * @param array $args An array of arguments to pass to the method. Will be json-encoded for you.
 * @return array Associative array of json decoded API response.
 */

to be formatted as

/**
 * Call an API method.
 * @param  string $method The API method to call, e.g. 'lists/list'
 * @param  array  $args   An array of arguments to pass to the method. Will be json-encoded for you.
 * @return array          Associative array of json decoded API response.
 */

Formatting the line that contains @return may be tough, because it doesn't contain the third column. So even if I can come up with a way to align only the lines that contain @param that would be great.

Edit:

I have already tried the tabular addon, but that doesn't work since in the above case, we can't use space as the delimeter.

Edit 2:

This is the second usecase for which @PeterRincker answer is failing

/**
 * Call an API method.
 * @since 1.7
 * @param string $method The API method to call, e.g. 'lists/list'
 * @param array $args An array of arguments to pass to the method. Will be json-encoded for you.
 * @return array Associative array of json decoded API response.
 */

It becomes

/**
 * Call an API method.
 * @since  1      .7
 * @param  string $method The API method to call, e.g. 'lists/list'
 * @param  array  $args   An array of arguments to pass to the method. Will be json-encoded for you.
 * @return array          Associative array of json decoded API response.
 */

Upvotes: 1

Views: 381

Answers (1)

Peter Rincker
Peter Rincker

Reputation: 45107

I'm sure this could be simplified but it worked for your example case:

:Tabularize/@\w\+\s\+\zs\S\+\|\%(@\w\+.*\)\@<=\u.*/

Overview

The key to this is to pick good deliminators to split on because we want to align the @return line as well as the @param lines. Use Tabularize to split on the start of the WORD after an @-word and the first uppercase letter.

Explanation

  • \| creates a branches in a regex pattern. This means we can split on both deliminators
  • @\w\+ matches @ followed by a word. e.g. @param
  • \zs set the start of the match
  • @\w\+\s\+\zs\S\+ match an @-word followed by a WORD and set the start of the match a the start of the WORD
  • \u match an uppercase letter
  • \u.* match the uppercase letter followed the rest of the line to prevent more splits
  • \%(...\) a non-capturing group
  • \@<= is vim's positive look behind. \(foo\)\@<=bar matches bar after foo in foobar
  • \%(@\w\+.*\)\@<=\u match an uppercase letter that follows an @-word

Common Tabular alignment idioms

  • use \zs to set the start of a match
  • end with .* to consume the rest of the line and prevent more splitting

For more help see:

:h :Tabularize
:h /\|
:h /\S
:h WORD
:h /\zs
:h /\u
:h /\%(
:h /\@<=

Upvotes: 3

Related Questions