Merge pull request #665 from taminomara/doc-hl

Support highlighting Markdown/RST in comments

Author: CppCXY

Cargo.lock

@@ -9,6 +9,7 @@ members = [
 # local
 emmylua_code_analysis = { path = "crates/emmylua_code_analysis", version = "0.10.0" }
 emmylua_parser = { path = "crates/emmylua_parser", version = "0.12.0" }
+emmylua_parser_desc = { path = "crates/emmylua_parser_desc", version = "0.12.0" }
 emmylua_diagnostic_macro = { path = "crates/emmylua_diagnostic_macro", version = "0.5.0" }
 
 # external
@@ -51,3 +52,4 @@ ansi_term = "0.12.1"
 num-traits = { version = "0.2", features = ["std"] }
 mimalloc = "0.1.47"
 googletest = "0.14.2"
+unicode-general-category = "1.0.0"

Cargo.toml

@@ -79,13 +79,14 @@
 
 Our project is meticulously organized into specialized crates, each serving a critical role in the Lua analysis ecosystem:
 
-| Crate | Badge | Description |
-| ----- | ----- | ----------- |
-| [🔍 **emmylua_parser**](./crates/emmylua_parser) | [![emmylua_parser](https://img.shields.io/crates/v/emmylua_parser.svg?style=flat-square)](https://crates.io/crates/emmylua_parser) | The foundational Rust-based Lua parser engineered for maximum efficiency and accuracy. Powers all downstream analysis tools. |
+| Crate                                                          | Badge                                                                                                                                                   | Description |
+|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| ----------- |
+| [🔍 **emmylua_parser**](./crates/emmylua_parser)               | [![emmylua_parser](https://img.shields.io/crates/v/emmylua_parser.svg?style=flat-square)](https://crates.io/crates/emmylua_parser)                      | The foundational Rust-based Lua parser engineered for maximum efficiency and accuracy. Powers all downstream analysis tools. |
+| [📑 **emmylua_parser_desc**](./crates/emmylua_parser_desc)     | [![emmylua_parser_desc](https://img.shields.io/crates/v/emmylua_parser_desc.svg?style=flat-square)](https://crates.io/crates/emmylua_parser_desc)       | Extension for EmmyLua-Parser that handles Markdown/RST highlighting in comments. |
 | [🧠 **emmylua_code_analysis**](./crates/emmylua_code_analysis) | [![emmylua_code_analysis](https://img.shields.io/crates/v/emmylua_code_analysis.svg?style=flat-square)](https://crates.io/crates/emmylua_code_analysis) | Advanced semantic analysis engine providing deep code understanding, type inference, and cross-reference resolution. |
-| [🖥️ **emmylua_ls**](./crates/emmylua_ls) | [![emmylua_ls](https://img.shields.io/crates/v/emmylua_ls.svg?style=flat-square)](https://crates.io/crates/emmylua_ls) | The complete Language Server Protocol implementation offering rich IDE features across all major editors. |
-| [📚 **emmylua_doc_cli**](./crates/emmylua_doc_cli/) | [![emmylua_doc_cli](https://img.shields.io/crates/v/emmylua_doc_cli.svg?style=flat-square)](https://crates.io/crates/emmylua_doc_cli) | Professional documentation generator creating beautiful, searchable API docs from your Lua code and annotations. |
-| [✅ **emmylua_check**](./crates/emmylua_check) | [![emmylua_check](https://img.shields.io/crates/v/emmylua_check.svg?style=flat-square)](https://crates.io/crates/emmylua_check) | Comprehensive static analysis tool for code quality assurance, catching bugs before they reach production. |
+| [🖥️ **emmylua_ls**](./crates/emmylua_ls)                       | [![emmylua_ls](https://img.shields.io/crates/v/emmylua_ls.svg?style=flat-square)](https://crates.io/crates/emmylua_ls)                                  | The complete Language Server Protocol implementation offering rich IDE features across all major editors. |
+| [📚 **emmylua_doc_cli**](./crates/emmylua_doc_cli/)            | [![emmylua_doc_cli](https://img.shields.io/crates/v/emmylua_doc_cli.svg?style=flat-square)](https://crates.io/crates/emmylua_doc_cli)                   | Professional documentation generator creating beautiful, searchable API docs from your Lua code and annotations. |
+| [✅ **emmylua_check**](./crates/emmylua_check)                 | [![emmylua_check](https://img.shields.io/crates/v/emmylua_check.svg?style=flat-square)](https://crates.io/crates/emmylua_check)                         | Comprehensive static analysis tool for code quality assurance, catching bugs before they reach production. |
 
 
 ---

README.md

@@ -50,7 +50,8 @@
       "$ref": "#/$defs/EmmyrcDoc",
       "default": {
         "knownTags": [],
-        "privateName": []
+        "privateName": [],
+        "syntax": "none"
       }
     },
     "documentColor": {
@@ -123,7 +124,8 @@
     "semanticTokens": {
       "$ref": "#/$defs/EmmyrcSemanticToken",
       "default": {
-        "enable": true
+        "enable": true,
+        "renderDocumentationMarkup": false
       }
     },
     "signature": {
@@ -442,6 +444,15 @@
         }
       ]
     },
+    "DocSyntax": {
+      "type": "string",
+      "enum": [
+        "none",
+        "md",
+        "myst",
+        "rst"
+      ]
+    },
     "EmmyrcCodeAction": {
       "type": "object",
       "properties": {
@@ -611,6 +622,25 @@
           "items": {
             "type": "string"
           }
+        },
+        "rstDefaultRole": {
+          "description": "When `syntax` is `Myst` or `Rst`, specifies default role used\nwith RST processor.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "rstPrimaryDomain": {
+          "description": "When `syntax` is `Myst` or `Rst`, specifies primary domain used\nwith RST processor.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "syntax": {
+          "description": "Syntax for highlighting documentation.",
+          "$ref": "#/$defs/DocSyntax",
+          "default": "none"
         }
       }
     },
@@ -934,6 +964,12 @@
           "type": "boolean",
           "default": true,
           "x-vscode-setting": true
+        },
+        "renderDocumentationMarkup": {
+          "description": "Render Markdown/RST in documentation. Set `doc.syntax` for this option to have effect.",
+          "type": "boolean",
+          "default": false,
+          "x-vscode-setting": true
         }
       }
     },

crates/emmylua_code_analysis/resources/schema.json

@@ -4,20 +4,52 @@ use serde::{Deserialize, Serialize};
 #[derive(Serialize, Deserialize, Debug, JsonSchema, Clone)]
 #[serde(rename_all = "camelCase")]
 pub struct EmmyrcDoc {
-    #[serde(default)]
     /// Treat specific field names as private, e.g. `m_*` means `XXX.m_id` and `XXX.m_type` are private, witch can only be accessed in the class where the definition is located.
+    #[serde(default)]
     pub private_name: Vec<String>,
 
     /// List of known documentation tags.
     #[serde(default)]
     pub known_tags: Vec<String>,
+
+    /// Syntax for highlighting documentation.
+    #[serde(default)]
+    pub syntax: DocSyntax,
+
+    /// When `syntax` is `Myst` or `Rst`, specifies primary domain used
+    /// with RST processor.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub rst_primary_domain: Option<String>,
+
+    /// When `syntax` is `Myst` or `Rst`, specifies default role used
+    /// with RST processor.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub rst_default_role: Option<String>,
 }
 
 impl Default for EmmyrcDoc {
     fn default() -> Self {
         Self {
             private_name: Default::default(),
             known_tags: Default::default(),
+            syntax: Default::default(),
+            rst_primary_domain: None,
+            rst_default_role: None,
         }
     }
 }
+
+#[derive(Serialize, Deserialize, Debug, JsonSchema, Clone)]
+#[serde(rename_all = "kebab-case")]
+pub enum DocSyntax {
+    None,
+    Md,
+    Myst,
+    Rst,
+}
+
+impl Default for DocSyntax {
+    fn default() -> Self {
+        DocSyntax::None
+    }
+}

crates/emmylua_code_analysis/src/config/configs/doc.rs

@@ -20,7 +20,7 @@ pub use code_action::EmmyrcCodeAction;
 pub use codelen::EmmyrcCodeLens;
 pub use completion::{EmmyrcCompletion, EmmyrcFilenameConvention};
 pub use diagnostics::EmmyrcDiagnostic;
-pub use doc::EmmyrcDoc;
+pub use doc::{DocSyntax, EmmyrcDoc};
 pub use document_color::EmmyrcDocumentColor;
 pub use hover::EmmyrcHover;
 pub use inlayhint::EmmyrcInlayHint;

crates/emmylua_code_analysis/src/config/configs/mod.rs

@@ -8,12 +8,18 @@ pub struct EmmyrcSemanticToken {
     #[serde(default = "default_true")]
     #[schemars(extend("x-vscode-setting" = true))]
     pub enable: bool,
+
+    /// Render Markdown/RST in documentation. Set `doc.syntax` for this option to have effect.
+    #[serde(default)]
+    #[schemars(extend("x-vscode-setting" = true))]
+    pub render_documentation_markup: bool,
 }
 
 impl Default for EmmyrcSemanticToken {
     fn default() -> Self {
         Self {
             enable: default_true(),
+            render_documentation_markup: false,
         }
     }
 }

crates/emmylua_code_analysis/src/config/configs/semantictoken.rs

@@ -9,13 +9,13 @@ use std::{
 
 pub use crate::config::configs::{EmmyrcExternalTool, EmmyrcReformat};
 pub use config_loader::{load_configs, load_configs_raw};
+pub use configs::{DocSyntax, EmmyrcFilenameConvention, EmmyrcLuaVersion};
 use configs::{
     EmmyrcCodeAction, EmmyrcCodeLens, EmmyrcCompletion, EmmyrcDiagnostic, EmmyrcDoc,
     EmmyrcDocumentColor, EmmyrcHover, EmmyrcInlayHint, EmmyrcInlineValues, EmmyrcReference,
     EmmyrcResource, EmmyrcRuntime, EmmyrcSemanticToken, EmmyrcSignature, EmmyrcStrict,
     EmmyrcWorkspace,
 };
-pub use configs::{EmmyrcFilenameConvention, EmmyrcLuaVersion};
 use emmylua_parser::{LuaLanguageLevel, LuaNonStdSymbolSet, ParserConfig, SpecialFunction};
 use regex::Regex;
 use rowan::NodeCache;

crates/emmylua_code_analysis/src/config/mod.rs

@@ -40,7 +40,7 @@ pub use visibility::check_export_visibility;
 use visibility::check_visibility;
 
 use crate::semantic::member::find_members_with_key;
-use crate::{Emmyrc, LuaDocument, LuaSemanticDeclId, db_index::LuaTypeDeclId};
+use crate::{Emmyrc, LuaDocument, LuaSemanticDeclId, ModuleInfo, db_index::LuaTypeDeclId};
 use crate::{
     FileId,
     db_index::{DbIndex, LuaType},
@@ -87,6 +87,10 @@ impl<'a> SemanticModel<'a> {
         self.db.get_vfs().get_document(&self.file_id).unwrap()
     }
 
+    pub fn get_module(&self) -> Option<&ModuleInfo> {
+        self.db.get_module_index().get_module(self.file_id)
+    }
+
     pub fn get_document_by_file_id(&self, file_id: FileId) -> Option<LuaDocument> {
         self.db.get_vfs().get_document(&file_id)
     }
@@ -256,6 +260,10 @@ impl<'a> SemanticModel<'a> {
         &self.emmyrc
     }
 
+    pub fn get_emmyrc_arc(&self) -> Arc<Emmyrc> {
+        self.emmyrc.clone()
+    }
+
     pub fn get_root(&self) -> &LuaChunk {
         &self.root
     }

crates/emmylua_code_analysis/src/semantic/mod.rs

@@ -14,6 +14,7 @@ categories = ["development-tools"]
 # local
 emmylua_code_analysis.workspace = true
 emmylua_parser.workspace = true
+emmylua_parser_desc.workspace = true
 
 # external
 lsp-server.workspace = true