Provide a fold for doc comments

[reem]

Having documentation inline in a source file is a blessing when working in a new codebase, but when working in a familiar file large amounts of comments between each piece of code only serve to obscure clarity. A way to fold them up would go a long way towards alleviating this problem.

[danigm]

I've done this adding a folding.vim file inside rust.vim/plugin with the following content:

setlocal foldmethod=expr
setlocal foldexpr=GetRustFold(v:lnum)

function! IndentLevel(lnum)
    return indent(a:lnum) / &shiftwidth
endfunction

function! GetRustFold(lnum)
    if getline(a:lnum) =~? '\v^\s*$'
        return '-1'
    endif

    let this_indent = IndentLevel(a:lnum)

    if getline(a:lnum) =~? '^\s*///.*$'
        return this_indent
    endif

    if getline(a:lnum) =~? '^\s*//!.*$'
        return '1'
    endif

    return '0'
endfunction

[soltanmm]

For those of us who prefer to use set fdm=syntax over expr, here's a syntax-based workaround to be placed in a new file at ~/.vim/after/syntax/rust.vim (or similarly functioning location) thrown together just now (and thus potentially coming with all the caveats of things that have been done 'just now'):

" Change rust.vim's syntax spec to allow comment-block-folding (only adds
" `fold` to the relevant lines pulled from the plugin's `syntax/rust.vim`
" file)
syn region rustCommentBlock             matchgroup=rustCommentBlock         start="/\*\%(!\|\*[*/]\@!\)\@!" end="\*/" contains=rustTodo,rustCommentBlockNest,@Spell
  \ fold
syn region rustCommentBlockDoc          matchgroup=rustCommentBlockDoc      start="/\*\%(!\|\*[*/]\@!\)"    end="\*/" contains=rustTodo,rustCommentBlockDocNest,rustCommentBlockDocRustCode,@Spell
  \ fold

" Change rust.vim's syntax spec to extend line comment regions to include subsequent
" line comments (changes the `end` regex to extend the region as long as the following
" line isn't headed by another comment line of the same kind [either normal or
" doc-comment]).
syn region rustCommentLine
  \ start="//"
  \ end="^\(\(\s*//\(//\@!\)\@!\)\@!\)"
  \ contains=rustTodo,@Spell
  \ fold
syn region rustCommentLineDoc
  \ start="//\%(//\@!\|!\)"
  \ end="^\(\s*//\%(//\@!\|!\)\)\@!"
  \ contains=rustTodo,@Spell
  \ fold