[optional] argument

grammar.js

@@ -14,7 +14,7 @@ const _uppercase_word = /[A-Z0-9.()][-A-Z0-9.()_]+/;
 const _li_token = /[-•][ ]+/;
 
 module.exports = grammar({
-  name: 'vimdoc',
+  name: 'vimdoc2',
 
   extras: () => [/[\t ]/],
 
@@ -57,6 +57,7 @@ module.exports = grammar({
         $.taglink,
         $.codespan,
         $.argument,
+        $.optional,
         $.keycode,
         $.note,
       ),
@@ -90,7 +91,7 @@ module.exports = grammar({
     ),
 
     note: () => choice(
-      'Note:', 'NOTE:', 'Notes:',
+      'The', 'the', 'Notes:',
       'Warning:', 'WARNING:',
       'Deprecated', 'DEPRECATED:'
     ),
@@ -106,6 +107,10 @@ module.exports = grammar({
       /ALT-./,
     ),
 
+    // Optional argument: [arg] (no whitespace allowed).
+    // This is the vimdoc style optional arg, as opposed to {arg}? (LuaLS style).
+    optional: () => /\[[^\]{\n\t ]+\]/,
+
     // First part (minus tags) of h3 or column_heading.
     uppercase_name: () => seq(
       token.immediate(_uppercase_word),  // No whitespace before heading.
@@ -222,7 +227,7 @@ module.exports = grammar({
     taglink: ($) => _word($, prec(1, /[^|\n\t ]+/), '|', '|'),
     // Inline code (may contain whitespace!): `foo bar`
     codespan: ($) => _word($, /[^``\n]+/, '`', '`'),
-    // Argument: {arg} (no whitespace allowed)
+    // Argument: {arg} (no whitespace allowed), also {arg}? (LuaLS style "optional arg").
     argument: ($) => seq(_word($, /[^}\n\t ]+/, '{', '}'), optional(token.immediate('?'))),
   },
 });

queries/vimdoc/highlights.scm

@@ -44,6 +44,8 @@
 
 (argument) @variable.parameter
 
+(optional) @variable.parameter
+
 (keycode) @string.special
 
 (url) @string.special.url

test/corpus/arguments.txt → test/corpus/argument.txt

@@ -133,12 +133,12 @@ NOT an argument
 ================================================================================
 a '{' '}' block
 {foo "{bar}" `{baz}` |{baz| } {}
-foo { bar 
+foo { bar
 { {} foo{{ foo{{{
- {{ 
- {{{ 
+ {{
+ {{{
 { }	foo
-,	inside { }: 
+,	inside { }:
 \}	literal } x
 \{	literal { x
 

test/corpus/argument_optional.txt

@@ -0,0 +1,32 @@
+================================================================================
+optional [argument]
+================================================================================
+:ar[gs]! [++opt] [+cmd] {arglist}			*:args_f!*
+:[count]arge[dit][!] [++opt] [+cmd] {name} ..
+
+
+--------------------------------------------------------------------------------
+
+(help_file
+  (block
+    (line
+      (word)
+      (optional)
+      (word)
+      (optional)
+      (optional)
+      (argument
+        (word))
+      (tag
+        (word)))
+    (line
+      (word)
+      (optional)
+      (word)
+      (optional)
+      (optional)
+      (optional)
+      (optional)
+      (argument
+        (word))
+      (word))))

test/corpus/codeblock.txt

@@ -398,8 +398,7 @@ codeblock stop and start on same line
     (line
       (word)
       (word)
-      (word)
-      (word))
+      (optional))
     (line
       (argument
         (word))))

test/corpus/taglink.txt

@@ -56,8 +56,7 @@ Hello |world| hello
       (taglink
         (word))
       (word)
-      (word)
-      (word)
+      (optional)
       (word))
     (line
       (taglink

test/corpus/url.txt

@@ -54,10 +54,7 @@ markdown: [https://neovim.io/doc/user/#yay](https://neovim.io/doc/user/#yay).
       (word))
     (line
       (word)
-      (word)
-      (url
-        (word))
-      (word)
+      (optional)
       (word)
       (url
         (word))