Syntax highlighting of nested comment folds in Vim

Question

In Vim, I use the standard foldmarkers {{{,}}} with a naming convention for the folds (e.g. {{{ collection). Some named folds define a comment (e.g. {{{ documentation) and I would like these to be highlighted as such. All the folds end with the same }}} marker.

I am having some success with the following:

syn region cComment start="{{{ documentation" end="}}}"
    contains=@cCommentGroup,cCommentStartError,cSpaceError,@Spell fold

but the problem is that commented folds can also contain generic collection folds, as in the following example:

{{{ documentation
    {{{ collection
    // some text
    }}}
    {{{ collection
    // some text
    }}}
}}}}

In this case, the commenting stops when the first }}} is reached, so the second collection fold is not highlighted as a comment.

The contains option does not seem relevant, as this makes contained folds have their standard highlighting.

I would like any fold inside a comment fold to inherit the comment syntax, without affecting their default syntax outside a comment fold.

Is this possible in Vim, given that all folds have the same endmarkers?

Answer 1

" Hi. Two syntax regions aren't enough, you have to use a third. There
" are two important things to note. First, 'matchgroup' (see :help
" :syn-matchgroup) prevents contained items from matching in the start
" and end patterns of the containing item. Second 'transparent' (see
" :help :syn-transparent) allows the inheriting of an item's containing
" syntax colouring.
"
" Save this entire text in a file and then :source it to see the effect.
"
"   blah
"   {{{ collection
"       blah
"   }}}
"   blah
"   {{{ documentation
"       {{{ collection
"           blah
"       }}}
"       blah
"       {{{ collection
"           blah
"       }}}
"   }}}
"   blah
"   {{{ collection
"       // some text
"   }}}
"   blah

syn clear

hi documentation guifg=darkcyan ctermfg=darkcyan
hi collection guifg=darkmagenta ctermfg=darkmagenta

syn region genericdoc start="{{{" end="}}}" transparent
syn region collection start="{{{ collection" end="}}}"
syn region documentation matchgroup=documentation
\ start="{{{ documentation" end="}}}" contains=genericdoc

Answer 2

I honestly am not entirely sure what you want, but there does appear to be a way to distinguish between end of your 'documentation' fold and end of your 'collection' folds. The code below will end the cComment region only when three right brackes are found as first characters in a line:

syn region cComment start="{{{ documentation" end="^}}}"
    contains=@cCommentGroup,cCommentStartError,cSpaceError,@Spell fold

Also, the 'fold' option in your syntax region command is not relevant if you're using markers to specify folds. Using fold with syn-region is useful only if you're using syntax to specify folds, which you aren't.