Add documentation highlighting in OCaml files

Co-authored-by: Samuel Hym <[email protected]>

Author: n-osborne

syntax/ocaml.vim

@@ -6,6 +6,7 @@
 "               Issac Trotts      <[email protected]>
 " URL:          https://github.com/ocaml/vim-ocaml
 " Last Change:
+"               2024 Jan 25 - Add OCamldoc/Odoc highlighting (Samuel Hym, Nicolas Osborne)
 "               2019 Nov 05 - Accurate type highlighting (Maëlan)
 "               2018 Nov 08 - Improved highlighting of operators (Maëlan)
 "               2018 Apr 22 - Improved support for PPX (Andrey Popp)
@@ -86,11 +87,19 @@ syn region   ocamlNone transparent matchgroup=ocamlEncl start="{" matchgroup=oca
 syn region   ocamlNone transparent matchgroup=ocamlEncl start="\[" matchgroup=ocamlEncl end="\]" contains=ALLBUT,@ocamlContained,ocamlBrackErr
 syn region   ocamlNone transparent matchgroup=ocamlEncl start="\[|" matchgroup=ocamlEncl end="|\]" contains=ALLBUT,@ocamlContained,ocamlArrErr
 
-
-" Comments
-syn region   ocamlComment start="(\*" end="\*)" contains=@Spell,ocamlComment,ocamlTodo
+" Comments and documentation
 syn keyword  ocamlTodo contained TODO FIXME XXX NOTE
 
+if !exists('odoc_syntax_loading')
+  " Load odoc syntax only when we are not in a *.mld file
+  syn region   ocamlComment start="(\*" end="\*)" contains=@Spell,ocamlComment,ocamlTodo
+  syn include  @ocamlOdoc syntax/odoc.vim
+  syn region   ocamlDocumentation matchgroup=ocamlComment start="(\*\*" end="\*)" contains=@ocamlOdoc
+else
+  " Nested in odoc syntax: for some reason, allowing ocamlComment inside
+  " ocamlComment in odocCodeBlock in ocamlDocumentation breaks
+  syn region   ocamlComment start="(\*" end="\*)" contains=@Spell,ocamlTodo
+endif
 
 " Objects
 syn region   ocamlEnd matchgroup=ocamlObject start="\<object\>" matchgroup=ocamlObject end="\<end\>" contains=ALLBUT,@ocamlContained,ocamlEndErr
@@ -662,7 +671,11 @@ hi def link ocamlPpxEncl       ocamlEncl
 
 let b:current_syntax = "ocaml"
 
-let &cpo = s:keepcpo
-unlet s:keepcpo
+" Because of the nesting (ocaml in odoc in ocaml), s:keepcpo might have been
+" unlet already
+if exists('s:keepcpo')
+  let &cpo = s:keepcpo
+  unlet s:keepcpo
+endif
 
 " vim: ts=8