Support for Descriptions Above and After Tags

Author: CppCXY

CHANGELOG.md

@@ -5,6 +5,19 @@
 ---
 ## [0.8.2] - Unreleased
 
+### ✨ Added
+- **Support for Descriptions Above and After Tags**: You can now add descriptions both above a tag (as a preceding comment) and after a tag (inline). The description will be associated with the corresponding tag.
+  ```lua
+  ---@class A
+  --- Description below (applies to the @field a)
+  ---@field a integer inline-description
+  ---@field b integer # description after hash
+  --- Description above (applies to the @field b)
+  ---@field c integer inline-description
+  local a = {}
+  ```
+
+
 ### 🐛 Fixed
 - **Enum Variable Parameter Issue**: Fixed a crash issue when checking enum variable as parameter
 

Cargo.lock

@@ -8,7 +8,7 @@ members = [
 [workspace.dependencies]
 # local
 emmylua_code_analysis = { path = "crates/emmylua_code_analysis", version = "0.8.1" }
-emmylua_parser = { path = "crates/emmylua_parser", version = "0.10.8" }
+emmylua_parser = { path = "crates/emmylua_parser", version = "0.11.0" }
 emmylua_diagnostic_macro = { path = "crates/emmylua_diagnostic_macro", version = "0.4.0" }
 
 # external

Cargo.toml

@@ -6,6 +6,7 @@ use emmylua_parser::{
 };
 
 use crate::{
+    compilation::analyzer::doc::preprocess_description,
     db_index::{
         LuaMember, LuaMemberKey, LuaMemberOwner, LuaOperator, LuaOperatorMetaMethod,
         LuaSemanticDeclId, LuaType,
@@ -60,11 +61,19 @@ pub fn analyze_field(analyzer: &mut DocAnalyzer, tag: LuaDocTagField) -> Option<
         field_type = TypeOps::Union.apply(analyzer.db, &field_type, &LuaType::Nil);
     }
 
-    let description = if let Some(description) = tag.get_description() {
-        Some(description.get_description_text().to_string())
-    } else {
-        None
-    };
+    let mut description = String::new();
+
+    for desc in tag.get_descriptions() {
+        let mut desc_text = desc.get_description_text().to_string();
+        if !desc_text.is_empty() {
+            let text = preprocess_description(&mut desc_text);
+            if !description.is_empty() {
+                description.push_str("\n\n");
+            }
+
+            description.push_str(&text);
+        }
+    }
 
     let field_key = tag.get_field_key()?;
     let key = match field_key {
@@ -134,7 +143,7 @@ pub fn analyze_field(analyzer: &mut DocAnalyzer, tag: LuaDocTagField) -> Option<
         );
     }
 
-    if let Some(description) = description {
+    if !description.is_empty() {
         analyzer.db.get_property_index_mut().add_description(
             analyzer.file_id,
             property_owner.clone(),

crates/emmylua_code_analysis/src/compilation/analyzer/doc/field_or_operator_def_tags.rs

@@ -13,7 +13,7 @@ use crate::{
     profile::Profile,
     FileId,
 };
-use emmylua_parser::{LuaAstNode, LuaComment, LuaDocDescriptionOwner, LuaSyntaxNode};
+use emmylua_parser::{LuaAstNode, LuaComment, LuaSyntaxNode};
 use file_generic_index::FileGenericIndex;
 use tags::get_owner_id;
 

crates/emmylua_code_analysis/src/compilation/analyzer/doc/mod.rs

@@ -61,7 +61,7 @@ pub fn analyze_class(analyzer: &mut DocAnalyzer, tag: LuaDocTagClass) -> Option<
         }
     }
 
-    add_description_for_type_decl(analyzer, &class_decl_id, tag.get_description());
+    add_description_for_type_decl(analyzer, &class_decl_id, tag.get_descriptions());
 
     bind_def_type(analyzer, LuaType::Def(class_decl_id.clone()));
     Some(())
@@ -70,19 +70,11 @@ pub fn analyze_class(analyzer: &mut DocAnalyzer, tag: LuaDocTagClass) -> Option<
 fn add_description_for_type_decl(
     analyzer: &mut DocAnalyzer,
     type_decl_id: &LuaTypeDeclId,
-    description: Option<LuaDocDescription>,
+    descriptions: Vec<LuaDocDescription>,
 ) {
     let mut description_text = String::new();
 
-    let comment = analyzer.comment.clone();
-    if let Some(description) = comment.get_description() {
-        let description = preprocess_description(&description.get_description_text());
-        if !description.is_empty() {
-            description_text.push_str(&description);
-        }
-    }
-
-    if let Some(description) = description {
+    for description in descriptions {
         let description = preprocess_description(&description.get_description_text());
         if !description.is_empty() {
             if !description_text.is_empty() {
@@ -130,8 +122,7 @@ pub fn analyze_enum(analyzer: &mut DocAnalyzer, tag: LuaDocTagEnum) -> Option<()
         enum_decl.add_enum_base(base_type);
     }
 
-    let description = tag.get_description();
-    add_description_for_type_decl(analyzer, &enum_decl_id, description);
+    add_description_for_type_decl(analyzer, &enum_decl_id, tag.get_descriptions());
 
     bind_def_type(analyzer, LuaType::Def(enum_decl_id.clone()));
 
@@ -182,8 +173,7 @@ pub fn analyze_alias(analyzer: &mut DocAnalyzer, tag: LuaDocTagAlias) -> Option<
 
     alias.add_alias_origin(origin_type);
 
-    let description = tag.get_description();
-    add_description_for_type_decl(analyzer, &alias_decl_id, description);
+    add_description_for_type_decl(analyzer, &alias_decl_id, tag.get_descriptions());
 
     Some(())
 }

crates/emmylua_code_analysis/src/compilation/analyzer/doc/type_def_tags.rs

@@ -1,6 +1,6 @@
 [package]
 name = "emmylua_parser"
-version = "0.10.8"
+version = "0.11.0"
 edition = "2021"
 authors = ["CppCXY"]
 description = "A parser for EmmyLua and luals"