feat: add `@comment.documentation` where applicable

32 files changed, 256 insertions, 58 deletions

diff --git a/queries/ada/highlights.scm b/queries/ada/highlights.scm
index 884203791..bcd041d5a 100644
--- a/queries/ada/highlights.scm
+++ b/queries/ada/highlights.scm
@@ -94,11 +94,9 @@
 [
    "exception"
    "raise"
-]  @exception
-(comment)         @comment
-(comment)         @spell       ;; spell-check comments
-(string_literal)  @string
-(string_literal)  @spell       ;; spell-check strings
+] @exception
+(comment) @comment @spell
+(string_literal) @string @spell
 (character_literal) @string
 (numeric_literal) @number
 
@@ -173,6 +171,24 @@
 ;    ] @function.spec
 ;)
 
+((comment) @comment.documentation
+  . [
+      (entry_declaration)
+      (subprogram_declaration)
+      (parameter_specification)
+    ])
+
+(compilation_unit 
+  . (comment) @comment.documentation)
+
+(component_list
+  (component_declaration)
+    . (comment) @comment.documentation)
+
+(enumeration_type_definition 
+  (identifier)
+  . (comment) @comment.documentation)
+
 ;; Highlight errors in red. This is not very useful in practice, as text will
 ;; be highlighted as user types, and the error could be elsewhere in the code.
 ;; This also requires defining    :hi @error guifg=Red    for instance.
diff --git a/queries/c/highlights.scm b/queries/c/highlights.scm
index 661f71b53..f607d3b8c 100644
--- a/queries/c/highlights.scm
+++ b/queries/c/highlights.scm
@@ -176,6 +176,9 @@
 
 (comment) @comment @spell
 
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
+
 ;; Parameters
 (parameter_declaration
   declarator: (identifier) @parameter)
diff --git a/queries/c_sharp/highlights.scm b/queries/c_sharp/highlights.scm
index c2bac3c1d..993609485 100644
--- a/queries/c_sharp/highlights.scm
+++ b/queries/c_sharp/highlights.scm
@@ -75,6 +75,14 @@
 
 (comment) @comment @spell
 
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///[^/]"))
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///$"))
+
 (using_directive
   (identifier) @type)
 
diff --git a/queries/d/highlights.scm b/queries/d/highlights.scm
index 8bec1ca10..229a9bf55 100644
--- a/queries/d/highlights.scm
+++ b/queries/d/highlights.scm
@@ -4,7 +4,18 @@
   (line_comment)
   (block_comment)
   (nesting_block_comment)
-] @comment
+] @comment @spell
+
+((line_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///[^/]"))
+((line_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///$"))
+
+((block_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
+
+((nesting_block_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[+][+][^+].*[+]/$"))
 
 [
   "(" ")"
diff --git a/queries/dart/highlights.scm b/queries/dart/highlights.scm
index 154a92b3a..e34467f65 100644
--- a/queries/dart/highlights.scm
+++ b/queries/dart/highlights.scm
@@ -155,8 +155,8 @@
 (false) @boolean
 (null_literal) @constant.builtin
 
-(documentation_comment) @comment
-(comment) @comment
+(comment) @comment @spell
+(documentation_comment) @comment.documentation @spell
 
 ; Keywords
 ; --------------------
diff --git a/queries/ecma/highlights.scm b/queries/ecma/highlights.scm
index 97feae8f3..82a0b99ab 100644
--- a/queries/ecma/highlights.scm
+++ b/queries/ecma/highlights.scm
@@ -123,11 +123,12 @@
   (undefined)
 ] @constant.builtin
 
-(comment) @comment
+(comment) @comment @spell
 
-(hash_bang_line) @preproc
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
 
-(comment) @spell
+(hash_bang_line) @preproc
 
 (string) @string @spell
 (template_string) @string
diff --git a/queries/elixir/highlights.scm b/queries/elixir/highlights.scm
index d87afcf1b..3223fa683 100644
--- a/queries/elixir/highlights.scm
+++ b/queries/elixir/highlights.scm
@@ -29,12 +29,10 @@
 ((identifier) @comment (#match? @comment "^_"))
 
 ; Comments
-(comment) @comment
-(comment) @spell
+(comment) @comment @spell
 
 ; Strings
-(string) @string
-(string) @spell
+(string) @string @spell
 
 ; Modules
 (alias) @type
@@ -214,15 +212,15 @@
 (unary_operator
   operator: "@"
   operand: (call
-    target: ((identifier) @_identifier (#any-of? @_identifier "moduledoc" "typedoc" "shortdoc" "doc")) @comment
+    target: ((identifier) @_identifier (#any-of? @_identifier "moduledoc" "typedoc" "shortdoc" "doc")) @comment.documentation
     (arguments [
       (string)
       (boolean)
       (charlist)
       (sigil
-        "~" @comment
-        ((sigil_name) @comment)
-        quoted_start: _ @comment
-        (quoted_content) @comment
-        quoted_end: _ @comment)
-    ] @comment))) @comment
+        "~" @comment.documentation
+        ((sigil_name) @comment.documentation)
+        quoted_start: _ @comment.documentation
+        (quoted_content) @comment.documentation
+        quoted_end: _ @comment.documentation)
+    ] @comment.documentation))) @comment.documentation
diff --git a/queries/elm/highlights.scm b/queries/elm/highlights.scm
index 4d0f6f447..fbd3a4c3f 100644
--- a/queries/elm/highlights.scm
+++ b/queries/elm/highlights.scm
@@ -1,7 +1,10 @@
 [
   (line_comment)
   (block_comment)
-] @comment
+] @comment @spell
+
+((block_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^{[-]|[^|]"))
 
 
 ; Keywords
diff --git a/queries/erlang/highlights.scm b/queries/erlang/highlights.scm
index fba44359f..63e6ea214 100644
--- a/queries/erlang/highlights.scm
+++ b/queries/erlang/highlights.scm
@@ -5,7 +5,10 @@
 (integer) @number
 (float) @float
 
-(comment) @comment
+(comment) @comment @spell
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^[%%][%%]"))
 
 ;; keyword
 [
@@ -104,7 +107,6 @@
 (type_alias name: _ @type) @type.definition
 (spec) @type.definition
 
-(comment) @comment
 [(string) (binary)] @string
 
 ;;; expr_function_call
diff --git a/queries/fortran/highlights.scm b/queries/fortran/highlights.scm
index 4604e9a92..a6b55413b 100644
--- a/queries/fortran/highlights.scm
+++ b/queries/fortran/highlights.scm
@@ -324,6 +324,9 @@
 
 (comment) @comment @spell
 
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^!>"))
+
 ; Errors
 
 (ERROR) @error
diff --git a/queries/gleam/highlights.scm b/queries/gleam/highlights.scm
index 0e2712879..00cabd171 100644
--- a/queries/gleam/highlights.scm
+++ b/queries/gleam/highlights.scm
@@ -83,10 +83,13 @@
 
 ; Comments
 [
+  (comment)
+] @comment @spell
+
+[
   (module_comment)
   (statement_comment)
-  (comment)
-] @comment
+] @comment.documentation @spell
 
 ; Unused Identifiers
 [
diff --git a/queries/go/highlights.scm b/queries/go/highlights.scm
index be72804b6..ce4ae89b6 100644
--- a/queries/go/highlights.scm
+++ b/queries/go/highlights.scm
@@ -196,20 +196,46 @@
 (float_literal) @float
 (imaginary_literal) @number
 
-(true) @boolean
-(false) @boolean
+[
+ (true)
+ (false)
+] @boolean
+
 (nil) @constant.builtin
 
 (keyed_element
   . (literal_element (identifier) @field))
 (field_declaration name: (field_identifier) @field)
 
+; Comments
+
 (comment) @comment @spell
 
+;; Doc Comments
+
+(source_file . (comment)+ @comment.documentation)
+
+(source_file
+  (comment)+ @comment.documentation
+  . (const_declaration))
+
+(source_file
+  (comment)+ @comment.documentation
+  . (function_declaration))
+
+(source_file
+  (comment)+ @comment.documentation
+  . (type_declaration))
+
+(source_file
+  (comment)+ @comment.documentation
+  . (var_declaration))
+
+; Errors
+
 (ERROR) @error
 
+; Spell
+
 ((interpreted_string_literal) @spell
-	(#not-has-parent? @spell
-		import_spec
-	)
-)
+  (#not-has-parent? @spell import_spec))
diff --git a/queries/hack/highlights.scm b/queries/hack/highlights.scm
index ffb365c87..a75b166ca 100644
--- a/queries/hack/highlights.scm
+++ b/queries/hack/highlights.scm
@@ -12,7 +12,10 @@
 [
   (comment)
   (heredoc)
-] @comment
+] @comment @spell
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
 
 "function" @keyword.function
 
diff --git a/queries/java/highlights.scm b/queries/java/highlights.scm
index 717a13bad..c97242295 100644
--- a/queries/java/highlights.scm
+++ b/queries/java/highlights.scm
@@ -279,3 +279,12 @@
   (line_comment)
   (block_comment)
 ] @comment @spell
+
+((block_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
+
+((line_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///[^/]"))
+
+((line_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///$"))
diff --git a/queries/kotlin/highlights.scm b/queries/kotlin/highlights.scm
index caf62f1f0..679cc0ad6 100644
--- a/queries/kotlin/highlights.scm
+++ b/queries/kotlin/highlights.scm
@@ -217,11 +217,12 @@
 
 ;;; Literals
 
-(comment) @comment
+(comment) @comment @spell
 
-(shebang_line) @preproc
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
 
-(comment) @spell
+(shebang_line) @preproc
 
 (real_literal) @float
 [
diff --git a/queries/lua/highlights.scm b/queries/lua/highlights.scm
index 1c17d823b..fa2eff68d 100644
--- a/queries/lua/highlights.scm
+++ b/queries/lua/highlights.scm
@@ -187,6 +187,12 @@
 
 (comment) @comment @spell
 
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^[-][-][-]"))
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^[-][-](%s?)@"))
+
 (hash_bang_line) @preproc
 
 (number) @number
diff --git a/queries/pascal/highlights.scm b/queries/pascal/highlights.scm
index 3a1c484e0..e11e0eaa2 100644
--- a/queries/pascal/highlights.scm
+++ b/queries/pascal/highlights.scm
@@ -248,7 +248,36 @@
 
 ; -- Comments
 
-(comment)         @comment
+(comment) @comment @spell
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///[^/]"))
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///$"))
+
+((comment) @comment.documentation
+  . [(unit) (declProc)])
+
+(declTypes
+  (comment) @comment.documentation
+  . (declType))
+
+(declSection
+  (comment) @comment.documentation
+  . [(declField) (declProc)])
+
+(declEnum
+  (comment) @comment.documentation
+  . (declEnumValue))
+
+(declConsts
+  (comment) @comment.documentation
+  . (declConst))
+
+(declVars
+  (comment) @comment.documentation
+  . (declVar))
+
 (pp)              @preproc
 
 ; -- Type declaration
diff --git a/queries/prisma/highlights.scm b/queries/prisma/highlights.scm
index e3a025d98..59ee2881c 100644
--- a/queries/prisma/highlights.scm
+++ b/queries/prisma/highlights.scm
@@ -8,10 +8,9 @@
  "type"
 ] @keyword
 
-[
-  (comment)
-  (developer_comment)
-] @comment
+(comment) @comment @spell
+
+(developer_comment) @comment.documentation @spell
 
 [
   (attribute)
diff --git a/queries/proto/highlights.scm b/queries/proto/highlights.scm
index 48c18906c..a6f47da93 100644
--- a/queries/proto/highlights.scm
+++ b/queries/proto/highlights.scm
@@ -42,7 +42,10 @@
   (false)
 ] @boolean
 
-(comment) @comment
+(comment) @comment @spell
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
 
 [
   "("
@@ -53,7 +56,7 @@
   "}"
   "<"
   ">"
-]  @punctuation.bracket
+] @punctuation.bracket
 
 [
  ";"
diff --git a/queries/ql/highlights.scm b/queries/ql/highlights.scm
index 009920a82..dcc702263 100644
--- a/queries/ql/highlights.scm
+++ b/queries/ql/highlights.scm
@@ -130,5 +130,6 @@
 [
   (line_comment)
   (block_comment)
-  (qldoc)
-] @comment
+] @comment @spell
+
+(qldoc) @comment.documentation
diff --git a/queries/ruby/highlights.scm b/queries/ruby/highlights.scm
index c350e5ad1..9488297b4 100644
--- a/queries/ruby/highlights.scm
+++ b/queries/ruby/highlights.scm
@@ -173,13 +173,30 @@
 (float) @float
 
 [
- (nil)
  (true)
  (false)
  ] @boolean
 
-(comment) @comment
-(comment) @spell
+(nil) @constant.builtin
+
+(comment) @comment @spell
+
+(program
+  (comment)+ @comment.documentation
+  (class))
+
+(module
+  (comment)+ @comment.documentation
+  (body_statement (class)))
+
+(class
+  (comment)+ @comment.documentation
+  (body_statement (method)))
+
+(body_statement
+  (comment)+ @comment.documentation
+  (method))
+
 (string_content) @spell
 
 ; Operators
diff --git a/queries/rust/highlights.scm b/queries/rust/highlights.scm
index c24a278f6..1a9330a70 100644
--- a/queries/rust/highlights.scm
+++ b/queries/rust/highlights.scm
@@ -148,6 +148,18 @@
   (block_comment)
 ] @comment @spell
 
+((line_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///[^/]"))
+((line_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///$"))
+((line_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^//!"))
+
+((block_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
+((block_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][!]"))
+
 (boolean_literal) @boolean
 (integer_literal) @number
 (float_literal) @float
diff --git a/queries/scala/highlights.scm b/queries/scala/highlights.scm
index f600dc185..6220cbfe1 100644
--- a/queries/scala/highlights.scm
+++ b/queries/scala/highlights.scm
@@ -234,6 +234,9 @@
 
 (comment) @comment @spell
 
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
+
 ;; `case` is a conditional keyword in case_block
 
 (case_block
diff --git a/queries/smali/highlights.scm b/queries/smali/highlights.scm
index 5f89cfa74..bdcb464ae 100644
--- a/queries/smali/highlights.scm
+++ b/queries/smali/highlights.scm
@@ -182,3 +182,10 @@
 ; Comments
 
 (comment) @comment @spell
+
+(class_definition
+  (comment) @comment.documentation)
+
+; Errors
+
+(ERROR) @error
diff --git a/queries/smithy/highlights.scm b/queries/smithy/highlights.scm
index 07ee328f1..2b709c2a2 100644
--- a/queries/smithy/highlights.scm
+++ b/queries/smithy/highlights.scm
@@ -108,7 +108,6 @@
 
 ; Comments
 
-[
-  (comment)
-  (documentation_comment)
-] @comment @spell
+(comment) @comment @spell
+
+(documentation_comment) @comment.documentation @spell
diff --git a/queries/solidity/highlights.scm b/queries/solidity/highlights.scm
index 5afebb990..76a623267 100644
--- a/queries/solidity/highlights.scm
+++ b/queries/solidity/highlights.scm
@@ -252,6 +252,14 @@
 
 (comment) @comment @spell
 
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///[^/]"))
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///$"))
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
+
 ; Errors
 
 (ERROR) @error
diff --git a/queries/swift/highlights.scm b/queries/swift/highlights.scm
index 5773c2377..4cdd882a8 100644
--- a/queries/swift/highlights.scm
+++ b/queries/swift/highlights.scm
@@ -107,6 +107,15 @@
  (multiline_comment)
 ] @comment @spell
 
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///[^/]"))
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///$"))
+
+((multiline_comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
+
 ; String literals
 (line_str_text) @string
 (str_escaped_char) @string
diff --git a/queries/teal/highlights.scm b/queries/teal/highlights.scm
index 2af9be589..4af3e212b 100644
--- a/queries/teal/highlights.scm
+++ b/queries/teal/highlights.scm
@@ -2,7 +2,11 @@
 ;; Primitives
 (boolean) @boolean
 (comment) @comment @spell
-(shebang_comment) @comment
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^[-][-][-]"))
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^[-][-](%s?)@"))
+(shebang_comment) @preproc
 (identifier) @variable
 ((identifier) @variable.builtin
   (#eq? @variable.builtin "self"))
diff --git a/queries/thrift/highlights.scm b/queries/thrift/highlights.scm
index 5df609c3d..adf147d9d 100644
--- a/queries/thrift/highlights.scm
+++ b/queries/thrift/highlights.scm
@@ -198,3 +198,11 @@
 ; Comments
 
 (comment) @comment @spell
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///[^/]"))
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^///$"))
diff --git a/queries/v/highlights.scm b/queries/v/highlights.scm
index 16904d18b..c4e69e802 100644
--- a/queries/v/highlights.scm
+++ b/queries/v/highlights.scm
@@ -406,5 +406,8 @@
 
 (ERROR) @error
 
-(comment) @comment
+(comment) @comment @spell
 
+(_
+  (comment)+ @comment.documentation
+  [(function_declaration) (type_declaration) (const_spec) (enum_declaration)])
diff --git a/queries/vala/highlights.scm b/queries/vala/highlights.scm
index 5ad7e0345..e1a20b8a0 100644
--- a/queries/vala/highlights.scm
+++ b/queries/vala/highlights.scm
@@ -1,7 +1,9 @@
 ; highlights.scm
 
 ; highlight comments and symbols
-(comment) @comment
+(comment) @comment @spell
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
 (symbol) @symbol
 (member_access_expression (_) (identifier) @symbol)
 
diff --git a/queries/zig/highlights.scm b/queries/zig/highlights.scm
index 0989704ce..37afe1c2f 100644
--- a/queries/zig/highlights.scm
+++ b/queries/zig/highlights.scm
@@ -1,8 +1,9 @@
+(line_comment) @comment @spell
+
 [
   (container_doc_comment)
   (doc_comment)
-  (line_comment)
-] @comment @spell
+] @comment.documentation @spell
 
 [
   variable: (IDENTIFIER)