Comments vs. Doc Strings

[Stiivi]

It would be nice if the highlighting distinguished between regular comments // and /* ... */ and comments containing documentation: /// and /** ... */. The former keeping the form of traditional comments with the later having a different formatting as for "document string". The formatting might be used the same as for strings (would keep visual consistency with languages such as Python). The keywords within the doc strings might have different formatting to stand-out.

My knowledge of vim script is limited, but I achieved it with something like this:

" In comment identifiers
function! s:CommentKeywordMatch(keyword)
  execute "syntax match swiftDocKeyword \"\\v^\\s*-\\s*". a:keyword . "\\W\"hs=s+1,he=e-1 contained"
  " Recognize document keywords after /// comment
  execute "syntax match swiftDocKeyword \"\/\\s*-\\s*". a:keyword . "\\W\"hs=s+1,he=e-1 contained"
endfunction

...

" Comment patterns
syntax match swiftComment "\v\/\/.*$"
      \ contains=swiftTodos,swiftDocKeyword,swiftMarker,@Spell oneline
syntax match swiftDocString "\v\/\/\/.*$"
      \ contains=swiftTodos,swiftDocKeyword,swiftMarker,@Spell oneline
syntax region swiftComment start="/\*" end="\*/"
      \ contains=swiftTodos,swiftDocKeyword,swiftMarker,swiftComment,@Spell fold

...

highlight default link swiftDocKeyword PreProc
highlight default link swiftDocString String

The above does not add the /** ... */ comment.

This is how it looks like with the Sunburst theme:

What do you think?

[keith]

Just to clarify, you're thinking that the highlighting inside the comment should be different for 'normal' comments vs 'documentation comments' which is indicated by // and /* */ vs /// and /** */ ?

[Stiivi]

Highlighting of the whole comment should be different – /// comment has different highlighting (in the above example as String) than // comment (in the above example as standard comment).

The highlighting of keywords inside of comment can be the same, just it needs to be visible. In my example I used PreProc which is other than 'string', since 'string' within 'string' can't be distinguished visually as they are the same. They keywords inside comments can be anything but 'comment' or 'string'.

EDIT: Goal is to be able to see which comments (as a whole line/block) are the code documentation comments and which comments are just ordinary commentary of the code.

[Stiivi]

5 patterns and 3 styles:

• single-line comment // ... → style C
• block comment /* ... */ → style C
• single-line "doc-string" comment /// ... → style D
• block "doc-string" comment /** ... / → style D
• special documentation keyword within any of the above (or just within D) → style K