path: root/runtime/syntax/doxygen.vim

" DoxyGen syntax hilighting extension for c/c++/idl/java
" Language:     doxygen on top of c, cpp, idl, java
" Maintainer:   Michael Geddes <michaelrgeddes@optushome.com.au>
" Author:       Michael Geddes
" Last Change:  12 December 2005
" Version:      1.15
"
" Copyright 2004 Michael Geddes
" Please feel free to use, modify & distribute all or part of this script,
" providing this copyright message remains.
" I would appreciate being acknowledged in any derived scripts, and would
" appreciate and welcome any updates, modifications or suggestions.

" NOTE:  Comments welcome!
"
" There are two variables that control the syntax hilighting produced by this
" script:
" doxygen_enhanced_colour  - Use the (non-standard) original colours designed for this hilighting.
" doxygen_my_rendering     - Disable the HTML bold/italic/underline rendering.
"
" A brief description without '.' or '!' will cause the end comment
" character to be marked as an error.  You can define the colour of this using
" the highlight doxygenErrorComment.
" A \link without an \endlink will cause an error hilight on the end-comment.
" This is defined by doxygenLinkError
"
" The variable g:doxygen_codeword_font can be set to the guifont for marking \c
" words - a 'typewriter' like font normally. Spaces must be escaped.  It can
" also be set to any hilight attribute. Alternatively, a hilight for doxygenCodeWord
" can be used to override it.
"
" By default, hilighting is done assumng you have the JAVADOC_AUTOBRIEF
" setting tunred on in your Doxygen configuration.  If you don't, you
" can set the variable g:doxygen_javadoc_autobrief to 0 to have the
" hilighting more accurately reflect the way Doxygen will interpret your
" comments.
"
" Special thanks to:  Wu Yongwei, Toby Allsopp
"

if exists('b:suppress_doxygen')
  unlet b:suppress_doxygen
  finish
endif

if exists('b:current_syntax') && b:current_syntax =~ 'doxygen' && !exists('doxygen_debug_script')
  finish
endif

let s:cpo_save = &cpo
set cpo&vim

" Start of Doxygen syntax hilighting:
"

" C/C++ Style line comments
syn region doxygenComment start=+/\*\(\*/\)\@![*!]+  end=+\*/+ contains=doxygenSyncStart,doxygenStart,doxygenTODO keepend
syn region doxygenCommentL start=+//[/!]<\@!+me=e-1 end=+$+ contains=doxygenStartL keepend skipwhite skipnl nextgroup=doxygenComment2
syn region doxygenCommentL start=+//[/!]<+me=e-2 end=+$+ contains=doxygenStartL keepend skipwhite skipnl
syn region doxygenCommentL start=+//@\ze[{}]+ end=+$+ contains=doxygenGroupDefine,doxygenGroupDefineSpecial

" Single line brief followed by multiline comment.
syn region doxygenComment2 start=+/\*\(\*/\)\@![*!]+ end=+\*/+ contained contains=doxygenSyncStart2,doxygenStart2,doxygenTODO keepend
" This helps with sync-ing as for some reason, syncing behaves differently to a normal region, and the start pattern does not get matched.
syn match doxygenSyncStart2 +[^*/]+ contained nextgroup=doxygenBody,doxygenPrev,doxygenStartSpecial,doxygenSkipComment,doxygenStartSkip2 skipwhite skipnl

" Skip empty lines at the start for when comments start on the 2nd/3rd line.
syn match doxygenStartSkip2 +^\s*\*[^/]+me=e-1 contained nextgroup=doxygenBody,doxygenStartSpecial,doxygenStartSkip skipwhite skipnl
syn match doxygenStartSkip2 +^\s*\*$+ contained nextgroup=doxygenBody,doxygenStartSpecial,,doxygenStartSkip skipwhite skipnl
syn match doxygenStart2 +/\*[*!]+ contained nextgroup=doxygenBody,doxygenPrev,doxygenStartSpecial,doxygenStartSkip2 skipwhite skipnl

" Match the Starting pattern (effectively creating the start of a BNF)
if !exists('g:doxygen_javadoc_autobrief') || g:doxygen_javadoc_autobrief
  syn match doxygenStart +/\*[*!]+ contained nextgroup=doxygenBrief,doxygenPrev,doxygenFindBriefSpecial,doxygenStartSpecial,doxygenStartSkip,doxygenPage skipwhite skipnl
else
  syn match doxygenStart +/\*[*!]+ contained nextgroup=doxygenBody,doxygenPrev,doxygenFindBriefSpecial,doxygenStartSpecial,doxygenStartSkip,doxygenPage skipwhite skipnl
endif
syn match doxygenStartL +//[/!]+ contained nextgroup=doxygenPrevL,doxygenBriefL,doxygenSpecial skipwhite

" This helps with sync-ing as for some reason, syncing behaves differently to a normal region, and the start pattern does not get matched.
syn match doxygenSyncStart +\ze[^*/]+ contained nextgroup=doxygenBrief,doxygenPrev,doxygenStartSpecial,doxygenFindBriefSpecial,doxygenStartSkip,doxygenPage skipwhite skipnl

" Match the first sentence as a brief comment
if ! exists('g:doxygen_end_punctuation')
  let g:doxygen_end_punctuation='[.]'
endif
exe 'syn region doxygenBrief contained start=+[\\@]\([pcbea]\>\|em\>\|ref\>\|link\>\|f\$\|[$\\&<>#]\)\|[^ \t\\@*]+ start=+\(^\s*\)\@<!\*/\@!+ start=+\<\k+ skip=+'.doxygen_end_punctuation.'\S+ end=+'.doxygen_end_punctuation.'+ end=+\(\s*\(\n\s*\*\=\s*\)[@\\]\([pcbea]\>\|em\>\|ref\>\|link\>\|f\$\|[$\\&<>#]\)\@!\)\@=+ contains=doxygenSmallSpecial,doxygenContinueComment,doxygenBriefEndComment,doxygenFindBriefSpecial,doxygenSmallSpecial,@doxygenHtmlGroup,doxygenTODO,doxygenOtherLink,doxygenHyperLink,doxygenHashLink  skipnl nextgroup=doxygenBody'

syn match doxygenBriefEndComment +\*/+ contained

exe 'syn region doxygenBriefL start=+@\k\@!\|[\\@]\([pcbea]\>\|em\>\|ref\>\|link\>\|f\$\|[$\\&<>#]\)\|[^ \t\\@]+ start=+\<+ skip=+'.doxygen_end_punctuation.'\S+ end=+'.doxygen_end_punctuation.'\|$+ contained contains=doxygenSmallSpecial,doxygenHyperLink,doxygenHashLink,@doxygenHtmlGroup keepend'

syn region doxygenBriefLine contained start=+\<\k+ end=+\(\n\s*\*\=\s*\([@\\]\([pcbea]\>\|em\>\|ref\>\|link\>\|f\$\|[$\\&<>#]\)\@!\)\|\s*$\)\@=+ contains=doxygenContinueComment,doxygenFindBriefSpecial,doxygenSmallSpecial,@doxygenHtmlGroup,doxygenTODO,doxygenOtherLink,doxygenHyperLink,doxygenHashLink  skipwhite keepend

" Match a '<' for applying a comment to the previous element.
syn match doxygenPrev +<+ contained nextgroup=doxygenBrief,doxygenSpecial,doxygenStartSkip skipwhite
syn match doxygenPrevL +<+ contained  nextgroup=doxygenBriefL,doxygenSpecial skipwhite

" These are anti-doxygen comments.  If there are more than two asterisks or 3 '/'s
" then turn the comments back into normal C comments.
syn region cComment start="/\*\*\*" end="\*/" contains=@cCommentGroup,cCommentString,cCharacter,cNumbersCom,cSpaceError
syn region cCommentL start="////" skip="\\$" end="$" contains=@cCommentGroup,cComment2String,cCharacter,cNumbersCom,cSpaceError

" Special commands at the start of the area:  starting with '@' or '\'
syn region doxygenStartSpecial contained start=+[@\\]\([pcbea]\>\|em\>\|ref\>\|link\>\|f\$\|[$\\&<>#]\)\@!+ end=+$+ end=+\*/+me=s-1,he=s-1  contains=doxygenSpecial nextgroup=doxygenSkipComment skipnl keepend
syn match doxygenSkipComment contained +^\s*\*/\@!+ nextgroup=doxygenBrief,doxygenStartSpecial,doxygenFindBriefSpecial,doxygenPage skipwhite

"syn region doxygenBodyBit contained start=+$+

" The main body of a doxygen comment.
syn region doxygenBody contained start=+.\|$+ matchgroup=doxygenEndComment end=+\*/+re=e-2,me=e-2 contains=doxygenContinueComment,doxygenTODO,doxygenSpecial,doxygenSmallSpecial,doxygenHyperLink,doxygenHashLink,@doxygenHtmlGroup

" These allow the skipping of comment continuation '*' characters.
syn match doxygenContinueComment contained +^\s*\*/\@!\s*+

" Catch a Brief comment without punctuation - flag it as an error but
" make sure the end comment is picked up also.
syn match doxygenErrorComment contained +\*/+


" Skip empty lines at the start for when comments start on the 2nd/3rd line.
if !exists('g:doxygen_javadoc_autobrief') || g:doxygen_javadoc_autobrief
  syn match doxygenStartSkip +^\s*\*[^/]+me=e-1 contained nextgroup=doxygenBrief,doxygenStartSpecial,doxygenFindBriefSpecial,doxygenStartSkip,doxygenPage skipwhite skipnl
  syn match doxygenStartSkip +^\s*\*$+ contained nextgroup=doxygenBrief,doxygenStartSpecial,doxygenFindBriefSpecial,doxygenStartSkip,doxygenPage skipwhite skipnl
else
  syn match doxygenStartSkip +^\s*\*[^/]+me=e-1 contained nextgroup=doxygenStartSpecial,doxygenFindBriefSpecial,doxygenStartSkip,doxygenPage,doxygenBody skipwhite skipnl
  syn match doxygenStartSkip +^\s*\*$+ contained nextgroup=doxygenStartSpecial,doxygenFindBriefSpecial,doxygenStartSkip,doxygenPage,doxygenBody skipwhite skipnl
endif

" Match an [@\]brief so that it moves to body-mode.
"
"
" syn match doxygenBriefLine  contained
syn match doxygenBriefSpecial contained +[@\\]+ nextgroup=doxygenBriefWord skipwhite
syn region doxygenFindBriefSpecial start=+[@\\]brief\>+ end=+\(\n\s*\*\=\s*\([@\\]\([pcbea]\>\|em\>\|ref\>\|link\>\|f\$\|[$\\&<>#]\)\@!\)\|\s*$\)\@=+ keepend contains=doxygenBriefSpecial nextgroup=doxygenBody keepend skipwhite skipnl contained


" Create the single word matching special identifiers.

fun! s:DxyCreateSmallSpecial( kword, name )

  let mx='[-:0-9A-Za-z_%=&+*/!~>|]\@<!\([-0-9A-Za-z_%=+*/!~>|#]\+[-0-9A-Za-z_%=+*/!~>|]\@!\|\\[\\<>&.]@\|[.,][0-9a-zA-Z_]\@=\|::\|([^)]*)\|&[0-9a-zA-Z]\{2,7};\)\+'
  exe 'syn region doxygenSpecial'.a:name.'Word contained start=+'.a:kword.'+ end=+\(\_s\+'.mx.'\)\@<=[-a-zA-Z_0-9+*/^%|~!=&\\]\@!+ skipwhite contains=doxygenContinueComment,doxygen'.a:name.'Word'
  exe 'syn match doxygen'.a:name.'Word contained "\_s\@<='.mx.'" contains=doxygenHtmlSpecial keepend'
endfun
call s:DxyCreateSmallSpecial('p', 'Code')
call s:DxyCreateSmallSpecial('c', 'Code')
call s:DxyCreateSmallSpecial('b', 'Bold')
call s:DxyCreateSmallSpecial('e', 'Emphasised')
call s:DxyCreateSmallSpecial('em', 'Emphasised')
call s:DxyCreateSmallSpecial('a', 'Argument')
call s:DxyCreateSmallSpecial('ref', 'Ref')
delfun s:DxyCreateSmallSpecial

syn match doxygenSmallSpecial contained +[@\\]\(\<[pcbea]\>\|\<em\>\|\<ref\>\|\<link\>\|f\$\|[$\\&<>#]\)\@=+ nextgroup=doxygenOtherLink,doxygenHyperLink,doxygenHashLink,doxygenFormula,doxygenSymbol,doxygenSpecial.*Word

" Now for special characters
syn match doxygenSpecial contained +[@\\]\(\<[pcbea]\>\|\<em\>\|\<ref\|\<link\>\>\|\<f\$\|[$\\&<>#]\)\@!+ nextgroup=doxygenParam,doxygenRetval,doxygenBriefWord,doxygenBold,doxygenBOther,doxygenOther,doxygenOtherTODO,doxygenOtherWARN,doxygenOtherBUG,doxygenPage,doxygenGroupDefine,doxygenCodeRegion,doxygenVerbatimRegion,doxygenDotRegion
" doxygenOtherLink,doxygenSymbol,doxygenFormula,doxygenErrorSpecial,doxygenSpecial.*Word
"
syn match doxygenGroupDefine contained +@\@<=[{}]+
syn match doxygenGroupDefineSpecial contained +@\ze[{}]+

syn match doxygenErrorSpecial contained +\s+

" Match Parmaters and retvals (hilighting the first word as special).
syn match doxygenParamDirection contained +\[\(\<in\>\|\<out\>\|,\)\+\]+ nextgroup=doxygenParamName skipwhite
syn keyword doxygenParam contained param nextgroup=doxygenParamName,doxygenParamDirection skipwhite
syn match doxygenParamName contained +[A-Za-z0-9_:]\++ nextgroup=doxygenSpecialMultilineDesc skipwhite
syn keyword doxygenRetval contained retval throw exception nextgroup=doxygenParamName skipwhite

" Match one line identifiers.
syn keyword doxygenOther contained addindex anchor
\ dontinclude endhtmlonly endlatexonly showinitializer hideinitializer
\ example htmlonly image include ingroup internal latexonly line
\ overload relates relatesalso sa skip skipline
\ until verbinclude version addtogroup htmlinclude copydoc dotfile
\ xmlonly endxmlonly
\ nextgroup=doxygenSpecialOnelineDesc

syn region doxygenCodeRegion contained matchgroup=doxygenOther start=+\<code\>+ matchgroup=doxygenOther end=+[\\@]\@<=\<endcode\>+ contains=doxygenCodeRegionSpecial,doxygenContinueComment,doxygenErrorComment
syn match doxygenCodeRegionSpecial contained +[\\@]\(endcode\>\)\@=+

syn region doxygenVerbatimRegion contained matchgroup=doxygenOther start=+\<verbatim\>+ matchgroup=doxygenOther end=+[\\@]\@<=\<endverbatim\>+ contains=doxygenVerbatimRegionSpecial,doxygenContinueComment,doxygenErrorComment
syn match doxygenVerbatimRegionSpecial contained +[\\@]\(endverbatim\>\)\@=+

let b:doxygen_syntax_save=b:current_syntax
unlet b:current_syntax
syn include @Dotx syntax/dot.vim
let b:current_syntax=b:doxygen_syntax_save
unlet b:doxygen_syntax_save
syn region doxygenDotRegion contained matchgroup=doxygenOther start=+\<dot\>+ matchgroup=doxygenOther end=+[\\@]\@<=\<enddot\>+ contains=doxygenDotRegionSpecial,doxygenErrorComment,doxygenContinueComment,@Dotx
syn match doxygenDotRegionSpecial contained +[\\@]\(enddot\>\)\@=+

" Match single line identifiers.
syn keyword doxygenBOther contained class enum file fn mainpage interface
\ namespace struct typedef union var def name
\ nextgroup=doxygenSpecialTypeOnelineDesc

syn keyword doxygenOther contained par nextgroup=doxygenHeaderLine
syn region doxygenHeaderLine start=+.+ end=+^+ contained skipwhite nextgroup=doxygenSpecialMultilineDesc

syn keyword doxygenOther contained arg author date deprecated li return see invariant note post pre remarks since test nextgroup=doxygenSpecialMultilineDesc
syn keyword doxygenOtherTODO contained todo attention nextgroup=doxygenSpecialMultilineDesc
syn keyword doxygenOtherWARN contained warning nextgroup=doxygenSpecialMultilineDesc
syn keyword doxygenOtherBUG contained bug nextgroup=doxygenSpecialMultilineDesc

" Handle \link, \endlink, hilighting the link-to and the link text bits separately.
syn region doxygenOtherLink matchgroup=doxygenOther start=+link+ end=+[\@]\@<=endlink\>+ contained contains=doxygenLinkWord,doxygenContinueComment,doxygenLinkError,doxygenEndlinkSpecial
syn match doxygenEndlinkSpecial contained +[\\@]\zeendlink\>+

syn match doxygenLinkWord "[_a-zA-Z:#()][_a-z0-9A-Z:#()]*\>" contained skipnl nextgroup=doxygenLinkRest,doxygenContinueLinkComment
syn match doxygenLinkRest +[^*@\\]\|\*/\@!\|[@\\]\(endlink\>\)\@!+ contained skipnl nextgroup=doxygenLinkRest,doxygenContinueLinkComment
syn match doxygenContinueLinkComment contained +^\s*\*\=[^/]+me=e-1 nextgroup=doxygenLinkRest
syn match doxygenLinkError "\*/" contained
" #Link hilighting.
syn match doxygenHashLink /\([a-zA-Z_][0-9a-zA-Z_]*\)\?#\(\.[0-9a-zA-Z_]\@=\|[a-zA-Z0-9_]\+\|::\|()\)\+/ contained contains=doxygenHashSpecial
syn match doxygenHashSpecial /#/ contained
syn match doxygenHyperLink /\(\s\|^\s*\*\?\)\@<=\(http\|https\|ftp\):\/\/[-0-9a-zA-Z_?&=+#%/.!':;@]\+/ contained

" Handle \page.  This does not use doxygenBrief.
syn match doxygenPage "[\\@]page\>"me=s+1 contained skipwhite nextgroup=doxygenPagePage
syn keyword doxygenPagePage page contained skipwhite nextgroup=doxygenPageIdent
syn region doxygenPageDesc  start=+.\++ end=+$+ contained skipwhite contains=doxygenSmallSpecial,@doxygenHtmlGroup keepend skipwhite skipnl nextgroup=doxygenBody
syn match doxygenPageIdent "\<[a-zA-Z0-9]\+\>" contained nextgroup=doxygenPageDesc

" Handle section
syn keyword doxygenOther defgroup section subsection subsubsection weakgroup contained skipwhite nextgroup=doxygenSpecialIdent
syn region doxygenSpecialSectionDesc  start=+.\++ end=+$+ contained skipwhite contains=doxygenSmallSpecial,@doxygenHtmlGroup keepend skipwhite skipnl nextgroup=doxygenContinueComment
syn match doxygenSpecialIdent "\<[a-zA-Z0-9]\+\>" contained nextgroup=doxygenSpecialSectionDesc

" Does the one-line description for the one-line type identifiers.
syn region doxygenSpecialTypeOnelineDesc  start=+.\++ end=+$+ contained skipwhite contains=doxygenSmallSpecial,@doxygenHtmlGroup keepend
syn region doxygenSpecialOnelineDesc  start=+.\++ end=+$+ contained skipwhite contains=doxygenSmallSpecial,@doxygenHtmlGroup keepend

" Handle the multiline description for the multiline type identifiers.
" Continue until an 'empty' line (can contain a '*' continuation) or until the
" next whole-line @ command \ command.
syn region doxygenSpecialMultilineDesc  start=+.\++ skip=+^\s*\(\*/\@!\s*\)\=\(\<\|[@\\]\<\([pcbea]\>\