feat: add ---@toc (Table of Contents) generation (#25)

Author: numToStr

emmylua.md

@@ -11,12 +11,16 @@ Following are the tags that you can use to create docs
 
 A `brief` can be used to describe a module or even to add some footnote etc.
 
+- Syntax
+
 ```lua
 ---@brief [[
 ---@comment
 ---@brief ]]
 ```
 
+- Input
+
 ```lua
 ---@brief [[
 ---Any summary you wanted to write you can write here.
@@ -73,12 +77,19 @@ NOTE: remember there is no formatting or text wrapping
 
 This can be used to add a heading for the module and change the prefix of every exported _function and type_.
 
-> NOTE: This can appear multiple times in a file but only the last `---@mod` will be used to rename prefixes.
+> NOTE:
+>
+> 1. This can appear multiple times in a file but only the last `---@mod` will be used to rename prefixes.
+> 2. Also adds a entries in the [`Table of Contents`](#table-of-contents)
+
+- Syntax
 
 ```lua
 ---@mod <name> [desc]
 ```
 
+- Input
+
 ```lua
 ---@mod mod.intro Introduction
 ---@brief [[
@@ -181,15 +192,71 @@ U:create()                                                    *mod.Human:create*
         <
 ```
 
+### Table of Contents
+
+Following tag can be used to generate a _Table of Contents_ section. It uses [`---@mod`](#module) tags for the entries.
+
+- Syntax
+
+```lua
+---@toc <tag>
+```
+
+- Input
+
+```lua
+---@toc my-plugin.contents
+
+---@mod first.module First Module
+
+---@mod second.module Second Module
+
+---@mod third.module Third Module
+
+local U = {}
+
+return U
+```
+
+- Output
+
+```help
+================================================================================
+Table of Contents                                           *my-plugin.contents*
+
+First Module······················································|first.module|
+Second Module····················································|second.module|
+Third Module······················································|third.module|
+
+================================================================================
+First Module                                                      *first.module*
+
+================================================================================
+Second Module                                                    *second.module*
+
+================================================================================
+Third Module                                                      *third.module*
+```
+
 ### Tag
 
 This can used to create an alternate tag for your module, functions etc.
 
+- Syntax
+
+```lua
+---@tag <name>
+```
+
+- Input
+
 ```lua
 ---@tag cool-tag
 ---@tag another-cool-tag
 ```
 
+- Output
+
 ```
                                                                       *cool-tag*
                                                               *another-cool-tag*
@@ -199,10 +266,14 @@ This can used to create an alternate tag for your module, functions etc.
 
 This tag can be used to add a divider/separator between section or anything you desire
 
+- Syntax
+
 ```lua
 ---@divider <char>
 ```
 
+- Input
+
 ```lua
 ---@divider -
 ---@divider =
@@ -223,17 +294,21 @@ This tag can be used to add a divider/separator between section or anything you
 
 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
 
+- Syntax
+
 ```lua
 ---@comment
----@param <name> <type> <desc>
+---@param <name> <type> [desc]
 ---@comment
----@return <type> <name> <desc>
+---@return <type> [name] [desc]
 ---@see <ref>
 ---@usage `<code>`
 ```
 
 > NOTE: All tag can be used multiple times except `---@usage`
 
+- Input
+
 ```lua
 local U = {}
 
@@ -324,15 +399,19 @@ U.magical({this}, {that})                                            *U.magical*
 
 Classes can be used to better structure your code and can be referenced as an argument to a function or it's return value. You can define it once and use it multiple times.
 
+- Syntax
+
 ```lua
----@class <name> <desc>
+---@class <name> [desc]
 ---@comment
----@field [public|protected|private] <name> <type> <desc>
+---@field [public|protected|private] <name> <type> [desc]
 ---@see <ref>
 ```
 
 > NOTE: `---@field` and `---@see` can be used multiple times
 
+- Input
+
 ```lua
 local H = {}
 
@@ -390,12 +469,16 @@ H:create()                                                            *H:create*
 
 You can use `---@type` to document static objects, constants etc.
 
+- Syntax
+
 ```lua
 ---@comment
----@type <type> <desc>
+---@type <type> [desc]
 ---@usage `<code>`
 ```
 
+- Input
+
 ```lua
 local U = {}
 
@@ -444,6 +527,14 @@ U.chai                                                                  *U.chai*
 
 This can be used to make a type alias. It is helpful if you are using the same the type multiple times.
 
+- Syntax
+
+```lua
+---@alias <name> <type> [desc]
+```
+
+- Input
+
 ```lua
 local U = {}
 
@@ -479,6 +570,8 @@ U.get_all()                                                          *U.get_all*
 
 You can also define a (pseudo) enum using [`---@alias`](#alias).
 
+- Input
+
 ```lua
 local U = {}
 
@@ -524,6 +617,8 @@ U.VMODE                                                                *U.VMODE*
 
 You can use `---@private` tag to discard any part of the code that is exported but it is not considered to be a part of the public API
 
+- Input
+
 ```lua
 local U = {}
 

src/parser/emmy.rs

@@ -17,6 +17,7 @@ pub enum Scope {
 
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum TagType {
+    Toc(String),
     Module {
         name: String,
         desc: Option<String>,
@@ -137,6 +138,10 @@ impl Emmy {
 
         let tag = just('@').ignore_then(choice((
             private.to(TagType::Skip),
+            just("toc")
+                .then_ignore(whitespace())
+                .ignore_then(comment.clone())
+                .map(TagType::Toc),
             just("mod")
                 .then_ignore(whitespace())
                 .ignore_then(ty)

src/parser/mod.rs

@@ -120,7 +120,32 @@ impl LemmyHelp {
 impl Display for LemmyHelp {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         for node in &self.nodes {
-            writeln!(f, "{}", node)?;
+            if let Node::Toc(x) = node {
+                writeln!(
+                    f,
+                    "{}",
+                    Module {
+                        name: x.to_string(),
+                        desc: Some("Table of Contents".into())
+                    }
+                )?;
+
+                for nodde in &self.nodes {
+                    if let Node::Module(x) = nodde {
+                        let desc = x.desc.as_deref().unwrap_or_default();
+
+                        writeln!(
+                            f,
+                            "{desc}{}",
+                            format_args!("{:·>w$}", format!("|{}|", x.name), w = 80 - desc.len())
+                        )?;
+                    }
+                }
+
+                writeln!(f)?;
+            } else {
+                writeln!(f, "{node}")?;
+            }
         }
 
         Ok(())

src/parser/node.rs

@@ -18,6 +18,7 @@ pub enum Node {
     Alias(Alias),
     Type(Type),
     Export(String),
+    Toc(String),
 }
 
 parser!(Node, Option<Self>, {
@@ -30,11 +31,13 @@ parser!(Node, Option<Self>, {
         Class::parse().map(Self::Class),
         Alias::parse().map(Self::Alias),
         Type::parse().map(Self::Type),
-        // We need this to match exported types/funcs etc.
-        select! { TagType::Export(x) => Self::Export(x) },
+        select! {
+            TagType::Export(x) => Self::Export(x),
+            TagType::Toc(x) => Self::Toc(x),
+        },
     ))
     .map(Some)
-    // This will skip useless nodes
+    // Skip useless nodes
     .or(any().to(None))
 });
 

tests/basic.rs

@@ -378,6 +378,49 @@ U:create()                                                    *mod.Human:create*
     )
 }
 
+#[test]
+fn table_of_contents() {
+    let src = "
+    ---@toc my-plugin.contents
+
+    ---@mod first.module First Module
+
+    ---@mod second.module Second Module
+
+    ---@mod third.module Third Module
+
+    local U = {}
+
+    return U
+    ";
+
+    let mut lemmy = LemmyHelp::default();
+
+    lemmy.for_help(src).unwrap();
+
+    assert_eq!(
+        lemmy.to_string(),
+        "\
+================================================================================
+Table of Contents                                           *my-plugin.contents*
+
+First Module······················································|first.module|
+Second Module····················································|second.module|
+Third Module······················································|third.module|
+
+================================================================================
+First Module                                                      *first.module*
+
+================================================================================
+Second Module                                                    *second.module*
+
+================================================================================
+Third Module                                                      *third.module*
+
+"
+    );
+}
+
 #[test]
 fn alias_and_type() {
     let src = r#"

tests/test.lua

@@ -18,6 +18,8 @@
 ---
 ---@brief ]]
 
+---@toc test.contents
+
 ---@mod awesome.name Awesome module title
 
 local U = {}

todo.txt

@@ -17,12 +17,12 @@
 [x] enum via @alias
 [ ] also support string as an entry alongside path
 [x] long names
-[-] Non-Standard tags (should not interfere with LSP)
+[x] Non-Standard tags (should not interfere with LSP)
     [x] ---@module <tag> <description>
             (override the tagged name prefix like *U.comment* -> *comment-comment*)
     [x] ---@divider <char>
     [x] ---@private
-    [ ] ---@toc-entry & ---@toc-slot
+    [x] ---@toc <tag>
 [ ] Error handling
 
 ## Dropped