feat: language support in ---@usage (#65)

This adds support for associating a language for `---@usage` tag which
defaults to `lua` for every code block unless explicitly defined using
the syntax below.

#### Emmylua

- Single line

```lua
---@Usage [lang] `<code>`
```

- Multiline

```lua
---@Usage [lang] [[
---
---@Usage ]]
```

#### Help (vimdoc)

```help
>{lang}

code...

<
```

Author: numToStr

emmylua.md

@@ -186,9 +186,9 @@ U:create()                                                            *U:create*
         {Human}
 
     Usage: ~
-        >
-            require('Human'):create()
-        <
+>lua
+        require('Human'):create()
+<
 ```
 
 ### Table of Contents
@@ -291,7 +291,7 @@ This tag can be used to add a divider/separator between section or anything you
 
 ### Functions
 
-A function contains multiple tags which form its structure. Like `---@param` for parameter, `---@return` for the return value, `---@see` for other related things and `---@usage` for example
+A function contains multiple tags which form its structure. Like `---@param` for parameter, `---@return` for the return value, `---@see` for other related things and [`---@usage`](#usage) for example
 
 - Syntax
 
@@ -305,19 +305,7 @@ A function contains multiple tags which form its structure. Like `---@param` for
 ---@usage `<code>`
 ```
 
-> NOTE:
->
-> 1. All tag can be used multiple times except `---@usage`
->
-> 2. `---@usage` tag also has a multiline syntax
->
-> ```lua
-> ---@usage [[
-> ---TEXT
-> ---TEXT
-> ---TEXT
-> ---@usage ]]
-> ```
+> NOTE: All tag can be used multiple times except `---@usage`
 
 - Input
 
@@ -395,9 +383,9 @@ U.sum({this}, {that})                                                    *U.sum*
         {that}  (number)  Second number
 
     Usage: ~
-        >
-            require("module.U").sum(10, 5)
-        <
+>lua
+        require("module.U").sum(10, 5)
+<
 
 U.sub({this}, {that})                                                    *U.sub*
     Subtract second from the first integer
@@ -410,11 +398,11 @@ U.sub({this}, {that})                                                    *U.sub*
         {number}
 
     Usage: ~
-        >
-            local M = require("module.U")
+>lua
+        local M = require("module.U")
 
-            print(M.sub(10 - 5))
-        <
+        print(M.sub(10 - 5))
+<
 
 
 U.magical({this}, {that})                                            *U.magical*
@@ -528,9 +516,9 @@ H:create()                                                            *H:create*
         {Human}
 
     Usage: ~
-        >
-            require('Human'):create()
-        <
+>lua
+        require('Human'):create()
+<
 ```
 
 ### Type
@@ -592,6 +580,79 @@ U.chai                                                                  *U.chai*
         (Chai)
 ```
 
+### Usage
+
+This tag is used to show code usage of functions and [`---@type`](#type). Code inside `---@usage` will be rendered as codeblock. Optionally, a `lang` can be provided to get syntax highlighting (defaults to `lua`).
+
+- Syntax
+
+1. Single-line
+
+```lua
+---@usage [lang] `<code>`
+```
+
+2. Multi-line
+
+```lua
+---@usage [lang] [[
+---<code>...
+---@usage ]]
+```
+
+- Input
+
+```lua
+local U = {}
+
+---Prints a message
+---@param msg string Message
+---@usage lua [[
+---require("module.U").sum(10, 5)
+---@usage ]]
+function U.echo(msg)
+    print(msg)
+end
+
+---Add two integer and print it
+---@param this number First number
+---@param that number Second number
+---@usage `require("module.U").sum(10, 5)`
+function U.sum(this, that)
+    print(this + that)
+end
+
+return U
+```
+
+- Output
+
+```
+U.echo({msg})                                                           *U.echo*
+    Prints a message
+
+    Parameters: ~
+        {msg}  (string)  Message
+
+    Usage: ~
+>lua
+        require("module.U").sum(10, 5)
+<
+
+
+U.sum({this}, {that})                                                    *U.sum*
+    Add two integer and print it
+
+    Parameters: ~
+        {this}  (number)  First number
+        {that}  (number)  Second number
+
+    Usage: ~
+>lua
+        require("module.U").sum(10, 5)
+<
+```
+
 ### Alias
 
 This tag can be used to make a type alias. It is helpful if you are using the same the type multiple times.

src/lexer.rs

@@ -181,6 +181,8 @@ impl Lexer {
             ))
         });
 
+        let code_lang = ident().then_ignore(space).or_not();
+
         let tag = just('@').ignore_then(choice((
             hidden.or(public.clone().ignored()).to(TagType::Skip),
             just("toc")
@@ -256,13 +258,16 @@ impl Lexer {
                 .ignore_then(comment)
                 .map(TagType::See),
             just("usage").ignore_then(space).ignore_then(choice((
-                just("[[").to(TagType::UsageStart),
+                code_lang
+                    .then(
+                        just('`')
+                            .ignore_then(filter(|c| *c != '`').repeated())
+                            .then_ignore(just('`'))
+                            .collect(),
+                    )
+                    .map(|(lang, code)| TagType::Usage(lang, code)),
+                code_lang.then_ignore(just("[[")).map(TagType::UsageStart),
                 just("]]").to(TagType::UsageEnd),
-                just('`')
-                    .ignore_then(filter(|c| *c != '`').repeated())
-                    .then_ignore(just('`'))
-                    .collect()
-                    .map(TagType::Usage),
             ))),
             just("export")
                 .ignore_then(space)

src/lexer/token.rs

@@ -101,13 +101,13 @@ pub enum TagType {
     /// ```
     See(String),
     /// ```lua
-    /// ---@usage `<code>`
+    /// ---@usage [lang] `<code>`
     /// ```
-    Usage(String),
+    Usage(Option<String>, String),
     /// ```lua
-    /// ---@usage [[
+    /// ---@usage [lang] [[
     /// ```
-    UsageStart,
+    UsageStart(Option<String>),
     /// ```lua
     /// ---@usage ]]
     /// ```

src/parser/tags/usage.rs

@@ -7,15 +7,23 @@ use crate::{lexer::TagType, parser::impl_parse};
 
 #[derive(Debug, Clone)]
 pub struct Usage {
+    pub lang: Option<String>,
     pub code: String,
 }
 
 impl_parse!(Usage, {
     choice((
-        select! { TagType::Comment(x) => x }
-            .repeated()
-            .delimited_by(just(TagType::UsageStart), just(TagType::UsageEnd))
-            .map(|x| Self { code: x.join("\n") }),
-        select! { TagType::Usage(code) => Self { code } },
+        select! {
+            TagType::UsageStart(lang) => lang
+        }
+        .then(select! { TagType::Comment(x) => x }.repeated())
+        .then_ignore(just(TagType::UsageEnd))
+        .map(|(lang, code)| Self {
+            lang,
+            code: code.join("\n"),
+        }),
+        select! {
+            TagType::Usage(lang, code) => Self { lang, code }
+        },
     ))
 });

src/vimdoc/usage.rs

@@ -10,10 +10,11 @@ impl ToDoc for UsageDoc {
     fn to_doc(n: &Self::N, _: &super::Settings) -> String {
         let mut doc = String::new();
         doc.push_str(&description("Usage: ~"));
-        doc.push_str("        >\n");
-        doc.push_str(&textwrap::indent(&n.code, "            "));
+        doc.push('>');
+        doc.push_str(n.lang.as_deref().unwrap_or("lua"));
         doc.push('\n');
-        doc.push_str("        <\n\n");
+        doc.push_str(&textwrap::indent(&n.code, "        "));
+        doc.push_str("\n<\n\n");
         doc
     }
 }

tests/basic.rs

@@ -282,9 +282,9 @@ U.sub({this}, {that})                                                    *U.sub*
                   we don't know about
 
     Usage: ~
-        >
-            require('module.U').sub(10, 5)
-        <
+>lua
+        require('module.U').sub(10, 5)
+<
 
 
 U.magical({this}, {that})                                            *U.magical*
@@ -505,12 +505,12 @@ U:create()                                                            *U:create*
         (Human)
 
     Usage: ~
-        >
-            local H = require('Human')
-            local human = H:create()
+>lua
+        local H = require('Human')
+        local human = H:create()
 
-            print(getmetatable(human))
-        <
+        print(getmetatable(human))
+<
 
 
 ================================================================================
@@ -650,15 +650,70 @@ U.VMODE                                                                *U.VMODE*
         (VMode)
 
     Usage: ~
-        >
-            print(require('plugin').VMODE)
-        <
+>lua
+        print(require('plugin').VMODE)
+<
 
 
 "#
     )
 }
 
+#[test]
+fn usage() {
+    let src = "
+    local U = {}
+
+    ---Prints a message
+    ---@param msg string Message
+    ---@usage lua [[
+    ---require('module.U').sum(10, 5)
+    ---@usage ]]
+    function U.echo(msg)
+        print(msg)
+    end
+
+    ---Add a number to 10
+    ---@param this number A number
+    ---@usage `require('module.U').sum(5)`
+    function U.sum(this)
+        print(10 + this)
+    end
+
+    return U
+    ";
+
+    assert_eq!(
+        lemmy!(src),
+        "\
+U.echo({msg})                                                           *U.echo*
+    Prints a message
+
+    Parameters: ~
+        {msg}  (string)  Message
+
+    Usage: ~
+>lua
+        require('module.U').sum(10, 5)
+<
+
+
+U.sum({this})                                                            *U.sum*
+    Add a number to 10
+
+    Parameters: ~
+        {this}  (number)  A number
+
+    Usage: ~
+>lua
+        require('module.U').sum(5)
+<
+
+
+"
+    )
+}
+
 #[test]
 fn private() {
     let src = "

tests/with_settings.rs

@@ -68,9 +68,9 @@ U:create()                                                            *U:create*
         (number)
 
     Usage: ~
-        >
-            require('Pi'):create()
-        <
+>lua
+        require('Pi'):create()
+<
 
 
 "
@@ -126,9 +126,9 @@ U:create()                                                      *awesome:create*
         (number)
 
     Usage: ~
-        >
-            require('Pi'):create()
-        <
+>lua
+        require('Pi'):create()
+<
 
 
 "