rc: Highlight embedded documentation

This commit adds a `documentation` face to the builtin themes, used
to highlight common documentation syntaxes:

	/**
	 * JavaDoc
	 */

	/*!
	 * QtDoc
	 */

	/// Inline documentation

	## Inline documentation

The face is only an alias to the `comment` one for now.

Closes #1944

25 files changed, 78 insertions, 51 deletions

diff --git a/colors/base16.kak b/colors/base16.kak
index 677d35b7..dd661ecf 100644
--- a/colors/base16.kak
+++ b/colors/base16.kak
@@ -28,6 +28,7 @@ evaluate-commands %sh{
         face global operator ${cyan_light}
         face global attribute ${orange_dark}
         face global comment ${grey_dark}
+        face global documentation comment
         face global meta ${orange_light}
         face global builtin default+b
     "
diff --git a/colors/default.kak b/colors/default.kak
index eb101049..4ade7d8f 100644
--- a/colors/default.kak
+++ b/colors/default.kak
@@ -11,6 +11,7 @@ face global keyword blue
 face global operator yellow
 face global attribute green
 face global comment cyan
+face global documentation comment
 face global meta magenta
 face global builtin default+b
 
diff --git a/colors/desertex.kak b/colors/desertex.kak
index b30efbf6..ae437281 100644
--- a/colors/desertex.kak
+++ b/colors/desertex.kak
@@ -1,15 +1,16 @@
 # desertex theme
 
 # Code
-face global value      rgb:fa8072
-face global type       rgb:dfdfbf
-face global identifier rgb:87ceeb
-face global string     rgb:fa8072
-face global error      rgb:c3bf9f+b
-face global keyword    rgb:eedc82
-face global operator   rgb:87ceeb
-face global attribute  rgb:eedc82
-face global comment    rgb:7ccd7c+i
+face global value         rgb:fa8072
+face global type          rgb:dfdfbf
+face global identifier    rgb:87ceeb
+face global string        rgb:fa8072
+face global error         rgb:c3bf9f+b
+face global keyword       rgb:eedc82
+face global operator      rgb:87ceeb
+face global attribute     rgb:eedc82
+face global comment       rgb:7ccd7c+i
+face global documentation comment
 
 # #include <...>
 face global meta rgb:ee799f
diff --git a/colors/github.kak b/colors/github.kak
index f685553b..2ca2519b 100644
--- a/colors/github.kak
+++ b/colors/github.kak
@@ -14,6 +14,7 @@ face global keyword rgb:A71D5D+b
 face global operator yellow
 face global attribute rgb:A71D5D
 face global comment rgb:AAAAAA
+face global documentation comment
 face global meta rgb:183691
 face global builtin default+b
 
diff --git a/colors/greyscale.kak b/colors/greyscale.kak
index 1f9e7421..7faed391 100644
--- a/colors/greyscale.kak
+++ b/colors/greyscale.kak
@@ -24,6 +24,7 @@ evaluate-commands %sh{
     set-face global builtin ${grey}+b
     set-face global module ${grey_dark_1}
     set-face global comment ${grey}+i
+    set-face global documentation comment
     set-face global function Default
     set-face global operator Default
     set-face global variable Default
diff --git a/colors/gruvbox.kak b/colors/gruvbox.kak
index d2613e46..b2995b90 100644
--- a/colors/gruvbox.kak
+++ b/colors/gruvbox.kak
@@ -24,18 +24,19 @@ evaluate-commands %sh{
 
     echo "
         # Code highlighting
-        face global value     ${purple}
-        face global type      ${yellow}
-        face global variable  ${blue}
-        face global module    ${green}
-        face global function  ${fg}
-        face global string    ${green}
-        face global keyword   ${red}
-        face global operator  ${fg}
-        face global attribute ${orange}
-        face global comment   ${gray}+i
-        face global meta      ${aqua}
-        face global builtin   ${fg}+b
+        face global value         ${purple}
+        face global type          ${yellow}
+        face global variable      ${blue}
+        face global module        ${green}
+        face global function      ${fg}
+        face global string        ${green}
+        face global keyword       ${red}
+        face global operator      ${fg}
+        face global attribute     ${orange}
+        face global comment       ${gray}+i
+        face global documentation comment
+        face global meta          ${aqua}
+        face global builtin       ${fg}+b
 
         # Markdown highlighting
         face global title     ${green}+b
diff --git a/colors/kaleidoscope-dark.kak b/colors/kaleidoscope-dark.kak
index f59bf70d..c078afe8 100644
--- a/colors/kaleidoscope-dark.kak
+++ b/colors/kaleidoscope-dark.kak
@@ -1,4 +1,4 @@
-# Kaleidoscope: colorblind-friendly light colorscheme
+# Kaleidoscope: colorblind-friendly dark colorscheme
 # https://personal.sron.nl/~pault/
 
 evaluate-commands %sh{
@@ -82,6 +82,7 @@ evaluate-commands %sh{
     set-face global builtin ${vibrant_blue}+b
     set-face global module ${vibrant_orange}
     set-face global comment ${bright_green}+i
+    set-face global documentation comment
     set-face global function Default
     set-face global operator Default
     set-face global variable Default
diff --git a/colors/kaleidoscope-light.kak b/colors/kaleidoscope-light.kak
index 0924ebba..68119f33 100644
--- a/colors/kaleidoscope-light.kak
+++ b/colors/kaleidoscope-light.kak
@@ -82,6 +82,7 @@ evaluate-commands %sh{
     set-face global builtin ${muted_indigo}+b
     set-face global module ${vibrant_orange}
     set-face global comment ${muted_green}+i
+    set-face global documentation comment
     set-face global function Default
     set-face global operator Default
     set-face global variable Default
diff --git a/colors/lucius.kak b/colors/lucius.kak
index 7bba885d..c65aaabb 100644
--- a/colors/lucius.kak
+++ b/colors/lucius.kak
@@ -34,6 +34,7 @@ evaluate-commands %sh{
         face global operator ${lucius_green}
         face global attribute ${lucius_light_blue}
         face global comment ${lucius_grey}
+        face global documentation comment
         face global meta ${lucius_purple}
         face global builtin default+b
 
diff --git a/colors/palenight.kak b/colors/palenight.kak
index aa5f92c0..e4aed532 100644
--- a/colors/palenight.kak
+++ b/colors/palenight.kak
@@ -25,17 +25,18 @@ evaluate-commands %sh{
 
     printf "%s\n" "
     # Code
-    face global value      $dark_yellow
-    face global type       $yellow
-    face global function   $blue
-    face global variable   $blue
-    face global identifier $blue
-    face global string     $green
-    face global error      rgb:c3bf9f+b
-    face global keyword    $purple
-    face global operator   $cyan
-    face global attribute  rgb:eedc82
-    face global comment    $comment_grey+i
+    face global value         $dark_yellow
+    face global type          $yellow
+    face global function      $blue
+    face global variable      $blue
+    face global identifier    $blue
+    face global string        $green
+    face global error         rgb:c3bf9f+b
+    face global keyword       $purple
+    face global operator      $cyan
+    face global attribute     rgb:eedc82
+    face global comment       $comment_grey+i
+    face global documentation comment
 
     # #include <...>
     face global meta       $yellow
diff --git a/colors/plain.kak b/colors/plain.kak
index d044d2a6..7c87c839 100644
--- a/colors/plain.kak
+++ b/colors/plain.kak
@@ -9,6 +9,7 @@ face global keyword default
 face global operator default
 face global attribute default
 face global comment blue
+face global documentation comment
 face global meta default
 face global builtin default
 
diff --git a/colors/red-phoenix.kak b/colors/red-phoenix.kak
index 9573edfb..c4bc0b55 100644
--- a/colors/red-phoenix.kak
+++ b/colors/red-phoenix.kak
@@ -43,6 +43,7 @@ evaluate-commands %sh{
         face global operator ${yellow1}
         face global attribute ${tan1}
         face global comment ${gray1}
+        face global documentation comment
         face global meta ${gray2}
         face global builtin ${tan1}
     "
diff --git a/colors/reeder.kak b/colors/reeder.kak
index a4fd06a6..cc174290 100644
--- a/colors/reeder.kak
+++ b/colors/reeder.kak
@@ -22,18 +22,19 @@ evaluate-commands %sh{
     # Base color definitions
     echo "
         # then we map them to code
-        face global value      ${orange_light}+b
-        face global type       ${orange}
-        face global variable   default
-        face global module     ${green}
-        face global function   default
-        face global string     ${green}
-        face global keyword    ${brown_dark}
-        face global operator   default
-        face global attribute  ${green}
-        face global comment    ${brown_light}
-        face global meta       ${brown_dark}
-        face global builtin   default+b
+        face global value         ${orange_light}+b
+        face global type          ${orange}
+        face global variable      default
+        face global module        ${green}
+        face global function      default
+        face global string        ${green}
+        face global keyword       ${brown_dark}
+        face global operator      default
+        face global attribute     ${green}
+        face global comment       ${brown_light}
+        face global documentation comment
+        face global meta          ${brown_dark}
+        face global builtin       default+b
 
         # and markup
         face global title      ${orange}+b
diff --git a/colors/solarized-dark-termcolors.kak b/colors/solarized-dark-termcolors.kak
index ffb891f4..322c5f1c 100644
--- a/colors/solarized-dark-termcolors.kak
+++ b/colors/solarized-dark-termcolors.kak
@@ -12,6 +12,7 @@ face global keyword            green
 face global operator           green
 face global attribute          bright-magenta
 face global comment            bright-green
+face global documentation      comment
 face global meta               bright-red
 face global builtin            default+b
 
diff --git a/colors/solarized-dark.kak b/colors/solarized-dark.kak
index cf1314f6..7672ca27 100644
--- a/colors/solarized-dark.kak
+++ b/colors/solarized-dark.kak
@@ -30,6 +30,7 @@ evaluate-commands %sh{
         face global operator           ${yellow}
         face global attribute          ${violet}
         face global comment            ${base01}
+        face global documentation      comment
         face global meta               ${orange}
         face global builtin            default+b
 
diff --git a/colors/solarized-light-termcolors.kak b/colors/solarized-light-termcolors.kak
index 07ded5a0..fdbec3ba 100644
--- a/colors/solarized-light-termcolors.kak
+++ b/colors/solarized-light-termcolors.kak
@@ -12,6 +12,7 @@ face global keyword            green
 face global operator           yellow
 face global attribute          bright-magenta
 face global comment            bright-cyan
+face global documentation      comment
 face global meta               bright-red
 face global builtin            default+b
 
diff --git a/colors/solarized-light.kak b/colors/solarized-light.kak
index 9402742a..7128fc13 100644
--- a/colors/solarized-light.kak
+++ b/colors/solarized-light.kak
@@ -30,6 +30,7 @@ evaluate-commands %sh{
         face global operator           ${yellow}
         face global attribute          ${violet}
         face global comment            ${base1}
+        face global documentation      comment
         face global meta               ${orange}
         face global builtin            default+b
 
diff --git a/colors/tomorrow-night.kak b/colors/tomorrow-night.kak
index 20a25480..8b038afa 100644
--- a/colors/tomorrow-night.kak
+++ b/colors/tomorrow-night.kak
@@ -33,6 +33,7 @@ evaluate-commands %sh{
         face global operator ${aqua}
         face global attribute ${purple}
         face global comment ${comment}
+        face global documentation comment
         face global meta ${purple}
         face global builtin ${orange}
     "
diff --git a/colors/zenburn.kak b/colors/zenburn.kak
index a27c8320..57b4ba79 100644
--- a/colors/zenburn.kak
+++ b/colors/zenburn.kak
@@ -41,6 +41,7 @@ evaluate-commands %sh{
         face global operator ${zenfunction}
         face global attribute ${zenstatement}
         face global comment ${zencomment}
+        face global documentation comment
         face global meta ${zenspecial}
         face global builtin default+b
 
diff --git a/rc/filetype/c-family.kak b/rc/filetype/c-family.kak
index 2c82a90e..e955fc8e 100644
--- a/rc/filetype/c-family.kak
+++ b/rc/filetype/c-family.kak
@@ -198,6 +198,10 @@ evaluate-commands %sh{
             add-highlighter shared/$ft/code default-region group
             add-highlighter shared/$ft/string region %{$maybe_at(?<!')(?<!'\\\\)"} %{(?<!\\\\)(?:\\\\\\\\)*"} fill string
             add-highlighter shared/$ft/raw_string region -match-capture %{R"([^(]*)\\(} %{\\)([^")]*)"} fill string
+            add-highlighter shared/$ft/javadoc region /\*\* \*/ fill documentation
+            add-highlighter shared/$ft/qtdoc region /\*! \*/ fill documentation
+            add-highlighter shared/$ft/inline_doc region /// $ fill documentation
+            add-highlighter shared/$ft/inline_qtdoc region //! $ fill documentation
             add-highlighter shared/$ft/comment region /\\* \\*/ fill comment
             add-highlighter shared/$ft/line_comment region // (?<!\\\\)(?=\\n) fill comment
             add-highlighter shared/$ft/disabled region -recurse "#\\h*if(?:def)?" ^\\h*?#\\h*if\\h+(?:0|FALSE)\\b "#\\h*(?:else|elif|endif)" fill comment
diff --git a/rc/filetype/d.kak b/rc/filetype/d.kak
index 9f70b7b3..18e547d5 100644
--- a/rc/filetype/d.kak
+++ b/rc/filetype/d.kak
@@ -40,12 +40,12 @@ add-highlighter shared/d/code default-region group
 add-highlighter shared/d/string region %{(?<!')(?<!'\\)"} %{(?<!\\)(?:\\\\)*"} group
 add-highlighter shared/d/verbatim_string region %{(?<!')(?<!'\\)`} %{(?<!\\)(?:\\\\)*`} fill meta
 add-highlighter shared/d/verbatim_string_prefixed region %{r`([^(]*)\(} %{\)([^)]*)`} fill meta
+add-highlighter shared/d/docstring1 region '/\+\+' '\+/' fill documentation
+add-highlighter shared/d/docstring2 region '/\*\*' '\*/' fill documentation
+add-highlighter shared/d/docstring3 region /// $ fill documentation
 add-highlighter shared/d/disabled region '/\+[^+]?' '\+/' fill comment
 add-highlighter shared/d/comment1 region '/\*[^*]?' '\*/' fill comment
 add-highlighter shared/d/comment2 region '//[^/]?' $ fill comment
-add-highlighter shared/d/docstring1 region '/\+\+' '\+/' fill comment
-add-highlighter shared/d/docstring2 region '/\*\*' '\*/' fill comment
-add-highlighter shared/d/docstring3 region /// $ fill comment
 
 add-highlighter shared/d/string/ fill string
 add-highlighter shared/d/string/ regex %{\\(x[0-9a-fA-F]{2}|[0-7]{1,3}|u[0-9a-fA-F]{4}|U[0-9a-fA-F]{8})\b} 0:value
diff --git a/rc/filetype/java.kak b/rc/filetype/java.kak
index 829652c4..f6a77f82 100644
--- a/rc/filetype/java.kak
+++ b/rc/filetype/java.kak
@@ -22,13 +22,13 @@ hook -group java-highlight global WinSetOption filetype=java %{
     hook -once -always window WinSetOption filetype=.* %{ remove-highlighter window/java }
 }
 
-
 provide-module java %§
 
 add-highlighter shared/java regions
 add-highlighter shared/java/code default-region group
 add-highlighter shared/java/string region %{(?<!')"} %{(?<!\\)(\\\\)*"} fill string
 add-highlighter shared/java/comment region /\* \*/ fill comment
+add-highlighter shared/java/inline_documentation region /// $ fill documentation
 add-highlighter shared/java/line_comment region // $ fill comment
 
 add-highlighter shared/java/code/ regex %{\b(this|true|false|null)\b} 0:value
diff --git a/rc/filetype/nim.kak b/rc/filetype/nim.kak
index dff43b18..a3ef1ab9 100644
--- a/rc/filetype/nim.kak
+++ b/rc/filetype/nim.kak
@@ -38,8 +38,10 @@ add-highlighter shared/nim/code default-region group
 add-highlighter shared/nim/triple_string region '([A-Za-z](_?\w)*)?"""' '"""(?!")' fill string
 add-highlighter shared/nim/raw_string region [A-Za-z](_?[A-Za-z])*" (?<!")"(?!") fill string
 add-highlighter shared/nim/string region (?<!'\\)" ((?<!\\)(\\\\)*"|$) group
-add-highlighter shared/nim/comment region '#?#\[' '\]##?' group
-add-highlighter shared/nim/comment_line region (?<![^'].')#?#(?!'\[) $ group
+add-highlighter shared/nim/inline_documentation region '##' $ fill documentation
+add-highlighter shared/nim/documentation region '##\[' '\]##' fill documentation
+add-highlighter shared/nim/comment region '#\[' '\]#' group
+add-highlighter shared/nim/comment_line region (?<![^'].')#(?!'\[) $ group
 
 add-highlighter shared/nim/string/fill fill string
 add-highlighter shared/nim/comment/fill fill comment
diff --git a/rc/filetype/python.kak b/rc/filetype/python.kak
index 5a5da6f6..58854638 100644
--- a/rc/filetype/python.kak
+++ b/rc/filetype/python.kak
@@ -37,6 +37,7 @@ add-highlighter shared/python/code default-region group
 add-highlighter shared/python/docstring     region -match-capture ("""|''') ("""|''') regions
 add-highlighter shared/python/double_string region '"'   (?<!\\)(\\\\)*"  fill string
 add-highlighter shared/python/single_string region "'"   (?<!\\)(\\\\)*'  fill string
+add-highlighter shared/python/documentation region '##'  '$'              fill documentation
 add-highlighter shared/python/comment       region '#'   '$'              fill comment
 
 # Integer formats
diff --git a/rc/filetype/rust.kak b/rc/filetype/rust.kak
index 501291d7..7e7248b3 100644
--- a/rc/filetype/rust.kak
+++ b/rc/filetype/rust.kak
@@ -35,6 +35,7 @@ add-highlighter shared/rust/code default-region group
 add-highlighter shared/rust/string           region %{(?<!')"} (?<!\\)(\\\\)*"              fill string
 add-highlighter shared/rust/raw_string       region -match-capture %{(?<!')r(#*)"} %{"(#*)} fill string
 add-highlighter shared/rust/comment          region -recurse "/\*" "/\*" "\*/"              fill comment
+add-highlighter shared/rust/documentation    region "//[!/]" "$"                            fill documentation
 add-highlighter shared/rust/line_comment     region "//" "$"                                fill comment
 
 add-highlighter shared/rust/macro_attributes region -recurse "\[" "#!?\[" "\]" regions