How can I clearly document errorformat patterns in a plugin compiler file?

Question

While testing out the vim-go plugin I encountered an issue that I wanted to look into more closely. In a comment on the issue, the owner of the plugin writes:

The text read 0 byte, err read tcp 127.0.0.1:8800: i/o timeout: [] is seen as an error line, so makeprg automatically parses it and puts into the quickfix list.

I'm not familiar with Vim plugin development but with a bit of digging I found the file where the parsing patterns are defined:

CompilerSet errorformat=
      \%-G#\ %.%#,
      \%-G%.%#panic:\ %m,
      \%Ecan\'t\ load\ package:\ %m,
      \%A%f:%l:%c:\ %m,
      \%A%f:%l:\ %m,
      \%C%*\\s%m,
      \%-G%.%#

I read the QuickFix error format documentation to understand these patterns, and I figured while doing so that I would add comments to the repository for the next reader to come along who isn't familiar with these patterns and tokens.

I got into the habit of using inline comments in this type of situation when documenting complicated regex patterns in Python. It's really useful. I wanted to do the same here, so I tried using ":

" Define the patterns that will be recognized by QuickFix when parsing the output of GoRun.
" More information at http://vimdoc.sourceforge.net/htmldoc/quickfix.html#errorformat
CompilerSet errorformat=
      \%-G#\ %.%#,                   " Ignore lines beginning with "#" ("# command-line-arguments" line sometimes appears?)
      \%-G%.%#panic:\ %m,            " Ignore lines containing "panic: message"
      \%Ecan\'t\ load\ package:\ %m, " Start of multiline error string is "can't load package: message"
      \%A%f:%l:%c:\ %m,              " Start of multiline unspecified string is "filename:linenumber:columnnumber: message"
      \%A%f:%l:\ %m,                 " Start of multiline unspecified string is "filename:linenumber: message"
      \%C%*\\s%m,                    " Continuation of multiline error message is indented
      \%-G%.%#                       " All lines not matching any of the above patterns are ignored

If this worked correctly, it wouldn't change the behavior of the plugin at all; but I found that QuickFix stopped working entirely after this change. If the syntax highlighting on GitHub is to be believed, most of these aren't actually being parsed as comments. I searched around and found "Commenting is simple: put a double quote to the left of the text you want to comment" on the Vim Tips Wiki but apparently it's not so simple as that.

A question on SO points to a similar issue, but I'm not defining mappings here and the different lines are actually part of the same command, so I can't just separate them.

According to an existing question here on Vi.SE, it's not possible to use inline comments with multi-line statements. So, how can I add a brief explanation for each pattern in the source, corresponding directly to the pattern where it appears in the code? I'd rather not throw it all into an overly-verbose multi-line comment in front of the CompilerSet command.

Answer 1

Settings like errorformat can be modified using the += and -= operators. You can take advantage of this by setting an initial value and adding to it, with a comment accompanying each addition. You could do, for example:

" Define the patterns that will be recognized by QuickFix when parsing the output of GoRun.
" More information at http://vimdoc.sourceforge.net/htmldoc/quickfix.html#errorformat
CompilerSet  errorformat=%-G#\ %.%#                   " Ignore lines beginning with "#" ("# command-line-arguments" line sometimes appears?)
CompilerSet errorformat+=%-G%.%#panic:\ %m            " Ignore lines containing "panic: message"
CompilerSet errorformat+=%Ecan\'t\ load\ package:\ %m " Start of multiline error string is "can't load package: message"
CompilerSet errorformat+=%A%f:%l:%c:\ %m              " Start of multiline unspecified string is "filename:linenumber:columnnumber: message"
CompilerSet errorformat+=%A%f:%l:\ %m                 " Start of multiline unspecified string is "filename:linenumber: message"
CompilerSet errorformat+=%C%*\\s%m                    " Continuation of multiline error message is indented
CompilerSet errorformat+=%-G%.%#                      " All lines not matching any of the above patterns are ignored

Maybe a bit verbose, but it should work (assuming CompilerSet errorformat behaves the way set errorformat does).