Merge pull request #647 from taminomara/fix-tags

Fix doc tag associations, warn about useless tags

Author: CppCXY

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

@@ -3,20 +3,22 @@ use crate::{
 };
 
 use super::{
-    tags::{find_owner_closure, get_owner_id},
+    tags::{find_owner_closure_or_report, get_owner_id_or_report},
     DocAnalyzer,
 };
+use crate::compilation::analyzer::doc::tags::report_orphan_tag;
 use emmylua_parser::{
-    LuaAst, LuaAstNode, LuaDocDescriptionOwner, LuaDocTagDeprecated, LuaDocTagExport,
-    LuaDocTagNodiscard, LuaDocTagSource, LuaDocTagVersion, LuaDocTagVisibility, LuaTableExpr,
+    LuaAst, LuaAstNode, LuaDocDescriptionOwner, LuaDocTagAsync, LuaDocTagDeprecated,
+    LuaDocTagExport, LuaDocTagNodiscard, LuaDocTagSource, LuaDocTagVersion, LuaDocTagVisibility,
+    LuaTableExpr,
 };
 
 pub fn analyze_visibility(
     analyzer: &mut DocAnalyzer,
     visibility: LuaDocTagVisibility,
 ) -> Option<()> {
     let visibility_kind = visibility.get_visibility_token()?.get_visibility();
-    let owner_id = get_owner_id(analyzer)?;
+    let owner_id = get_owner_id_or_report(analyzer, &visibility)?;
 
     analyzer.db.get_property_index_mut().add_visibility(
         analyzer.file_id,
@@ -28,19 +30,19 @@ pub fn analyze_visibility(
 }
 
 pub fn analyze_source(analyzer: &mut DocAnalyzer, source: LuaDocTagSource) -> Option<()> {
-    let source = source.get_path_token()?.get_path().to_string();
-    let owner_id = get_owner_id(analyzer)?;
+    let path = source.get_path_token()?.get_path().to_string();
+    let owner_id = get_owner_id_or_report(analyzer, &source)?;
 
     analyzer
         .db
         .get_property_index_mut()
-        .add_source(analyzer.file_id, owner_id, source);
+        .add_source(analyzer.file_id, owner_id, path);
 
     Some(())
 }
 
 pub fn analyze_nodiscard(analyzer: &mut DocAnalyzer, nodiscard: LuaDocTagNodiscard) -> Option<()> {
-    let closure = find_owner_closure(analyzer)?;
+    let closure = find_owner_closure_or_report(analyzer, &nodiscard)?;
     let signature_id = LuaSignatureId::from_closure(analyzer.file_id, &closure);
     let signature = analyzer
         .db
@@ -72,7 +74,7 @@ pub fn analyze_deprecated(analyzer: &mut DocAnalyzer, tag: LuaDocTagDeprecated)
     } else {
         None
     };
-    let owner_id = get_owner_id(analyzer)?;
+    let owner_id = get_owner_id_or_report(analyzer, &tag)?;
 
     analyzer
         .db
@@ -83,7 +85,7 @@ pub fn analyze_deprecated(analyzer: &mut DocAnalyzer, tag: LuaDocTagDeprecated)
 }
 
 pub fn analyze_version(analyzer: &mut DocAnalyzer, version: LuaDocTagVersion) -> Option<()> {
-    let owner_id = get_owner_id(analyzer)?;
+    let owner_id = get_owner_id_or_report(analyzer, &version)?;
 
     let mut version_set = Vec::new();
     for version in version.get_version_list() {
@@ -100,8 +102,8 @@ pub fn analyze_version(analyzer: &mut DocAnalyzer, version: LuaDocTagVersion) ->
     Some(())
 }
 
-pub fn analyze_async(analyzer: &mut DocAnalyzer) -> Option<()> {
-    let closure = find_owner_closure(analyzer)?;
+pub fn analyze_async(analyzer: &mut DocAnalyzer, tag: LuaDocTagAsync) -> Option<()> {
+    let closure = find_owner_closure_or_report(analyzer, &tag)?;
     let signature_id = LuaSignatureId::from_closure(analyzer.file_id, &closure);
     let signature = analyzer
         .db
@@ -114,7 +116,10 @@ pub fn analyze_async(analyzer: &mut DocAnalyzer) -> Option<()> {
 }
 
 pub fn analyze_export(analyzer: &mut DocAnalyzer, tag: LuaDocTagExport) -> Option<()> {
-    let owner = analyzer.comment.get_owner()?;
+    let Some(owner) = analyzer.comment.get_owner() else {
+        report_orphan_tag(analyzer, &tag);
+        return None;
+    };
     let owner_id = match owner {
         LuaAst::LuaReturnStat(return_stat) => {
             let return_table_expr = return_stat.child::<LuaTableExpr>()?;
@@ -123,7 +128,7 @@ pub fn analyze_export(analyzer: &mut DocAnalyzer, tag: LuaDocTagExport) -> Optio
                 return_table_expr.get_position(),
             ))
         }
-        _ => get_owner_id(analyzer)?,
+        _ => get_owner_id_or_report(analyzer, &tag)?,
     };
 
     let export_scope = if let Some(scope_text) = tag.get_export_scope() {

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

@@ -4,7 +4,7 @@ use emmylua_parser::{
 
 use crate::{
     db_index::{LuaMemberId, LuaSemanticDeclId, LuaSignatureId},
-    LuaDeclId,
+    AnalyzeError, DiagnosticCode, LuaDeclId,
 };
 
 use super::{
@@ -74,8 +74,8 @@ pub fn analyze_tag(analyzer: &mut DocAnalyzer, tag: LuaDocTag) -> Option<()> {
         LuaDocTag::Version(version) => {
             analyze_version(analyzer, version)?;
         }
-        LuaDocTag::Async(_) => {
-            analyze_async(analyzer)?;
+        LuaDocTag::Async(tag) => {
+            analyze_async(analyzer, tag)?;
         }
 
         // field or operator
@@ -135,7 +135,23 @@ pub fn find_owner_closure(analyzer: &DocAnalyzer) -> Option<LuaClosureExpr> {
     None
 }
 
+pub fn find_owner_closure_or_report(
+    analyzer: &mut DocAnalyzer,
+    tag: &impl LuaAstNode,
+) -> Option<LuaClosureExpr> {
+    match find_owner_closure(analyzer) {
+        Some(id) => Some(id),
+        None => {
+            report_orphan_tag(analyzer, tag);
+            None
+        }
+    }
+}
+
 pub fn get_owner_id(analyzer: &mut DocAnalyzer) -> Option<LuaSemanticDeclId> {
+    if let Some(current_type_id) = &analyzer.current_type_id {
+        return Some(LuaSemanticDeclId::TypeDecl(current_type_id.clone()));
+    }
     let owner = analyzer.comment.get_owner()?;
     match owner {
         LuaAst::LuaAssignStat(assign) => {
@@ -186,3 +202,27 @@ pub fn get_owner_id(analyzer: &mut DocAnalyzer) -> Option<LuaSemanticDeclId> {
         }
     }
 }
+
+pub fn get_owner_id_or_report(
+    analyzer: &mut DocAnalyzer,
+    tag: &impl LuaAstNode,
+) -> Option<LuaSemanticDeclId> {
+    match get_owner_id(analyzer) {
+        Some(id) => Some(id),
+        None => {
+            report_orphan_tag(analyzer, tag);
+            None
+        }
+    }
+}
+
+pub fn report_orphan_tag(analyzer: &mut DocAnalyzer, tag: &impl LuaAstNode) {
+    analyzer.db.get_diagnostic_index_mut().add_diagnostic(
+        analyzer.file_id,
+        AnalyzeError {
+            kind: DiagnosticCode::AnnotationUsageError,
+            message: t!("`@%{name}` can't be used here", name = tag.get_text()).to_string(),
+            range: tag.get_range(),
+        },
+    );
+}

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

@@ -8,16 +8,16 @@ use emmylua_parser::{
 };
 use rowan::TextRange;
 
+use super::{
+    infer_type::infer_type, preprocess_description, tags::find_owner_closure, DocAnalyzer,
+};
+use crate::compilation::analyzer::doc::tags::report_orphan_tag;
 use crate::{
     compilation::analyzer::bind_type::bind_type,
     db_index::{LuaDeclId, LuaMemberId, LuaSemanticDeclId, LuaSignatureId, LuaType},
     LuaTypeCache, LuaTypeDeclId,
 };
 
-use super::{
-    infer_type::infer_type, preprocess_description, tags::find_owner_closure, DocAnalyzer,
-};
-
 pub fn analyze_class(analyzer: &mut DocAnalyzer, tag: LuaDocTagClass) -> Option<()> {
     let file_id = analyzer.file_id;
     let name = tag.get_name_token()?.get_name_text().to_string();
@@ -324,7 +324,10 @@ fn get_global_reference_ranges(
 }
 
 pub fn analyze_func_generic(analyzer: &mut DocAnalyzer, tag: LuaDocTagGeneric) -> Option<()> {
-    let comment_owner = analyzer.comment.get_owner()?;
+    let Some(comment_owner) = analyzer.comment.get_owner() else {
+        report_orphan_tag(analyzer, &tag);
+        return None;
+    };
     let mut params_result = HashMap::new();
     let mut param_info = Vec::new();
     if let Some(params_list) = tag.get_generic_decl_list() {

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

@@ -5,6 +5,15 @@ use emmylua_parser::{
     LuaVarExpr,
 };
 
+use super::{
+    infer_type::infer_type,
+    preprocess_description,
+    tags::{find_owner_closure, get_owner_id_or_report},
+    DocAnalyzer,
+};
+use crate::compilation::analyzer::doc::tags::{
+    find_owner_closure_or_report, get_owner_id, report_orphan_tag,
+};
 use crate::{
     compilation::analyzer::{bind_type::bind_type, unresolve::UnResolveModuleRef},
     db_index::{
@@ -15,13 +24,6 @@ use crate::{
     SignatureReturnStatus, TypeOps,
 };
 
-use super::{
-    infer_type::infer_type,
-    preprocess_description,
-    tags::{find_owner_closure, get_owner_id},
-    DocAnalyzer,
-};
-
 pub fn analyze_type(analyzer: &mut DocAnalyzer, tag: LuaDocTagType) -> Option<()> {
     let description = if let Some(des) = tag.get_description() {
         Some(preprocess_description(&des.get_description_text(), None))
@@ -36,7 +38,10 @@ pub fn analyze_type(analyzer: &mut DocAnalyzer, tag: LuaDocTagType) -> Option<()
     }
 
     // bind ref type
-    let owner = analyzer.comment.get_owner()?;
+    let Some(owner) = analyzer.comment.get_owner() else {
+        report_orphan_tag(analyzer, &tag);
+        return None;
+    };
     match owner {
         LuaAst::LuaAssignStat(assign_stat) => {
             let (vars, _) = assign_stat.get_var_and_expr_list();
@@ -137,7 +142,9 @@ pub fn analyze_type(analyzer: &mut DocAnalyzer, tag: LuaDocTagType) -> Option<()
                 }
             }
         }
-        _ => {}
+        _ => {
+            report_orphan_tag(analyzer, &tag);
+        }
     }
 
     Some(())
@@ -196,6 +203,8 @@ pub fn analyze_param(analyzer: &mut DocAnalyzer, tag: LuaDocTagParam) -> Option<
                 break;
             }
         }
+    } else {
+        report_orphan_tag(analyzer, &tag);
     }
 
     Some(())
@@ -208,7 +217,7 @@ pub fn analyze_return(analyzer: &mut DocAnalyzer, tag: LuaDocTagReturn) -> Optio
         None
     };
 
-    if let Some(closure) = find_owner_closure(analyzer) {
+    if let Some(closure) = find_owner_closure_or_report(analyzer, &tag) {
         let signature_id = LuaSignatureId::from_closure(analyzer.file_id, &closure);
         let returns = tag.get_type_and_name_list();
         for (doc_type, name_token) in returns {
@@ -254,6 +263,8 @@ pub fn analyze_return_cast(analyzer: &mut DocAnalyzer, tag: LuaDocTagReturnCast)
             name.to_string(),
             cast_op_type.to_ptr(),
         );
+    } else {
+        report_orphan_tag(analyzer, &tag);
     }
 
     Some(())
@@ -275,7 +286,7 @@ pub fn analyze_overload(analyzer: &mut DocAnalyzer, tag: LuaDocTagOverload) -> O
             }
             _ => {}
         }
-    } else if let Some(closure) = find_owner_closure(analyzer) {
+    } else if let Some(closure) = find_owner_closure_or_report(analyzer, &tag) {
         let type_ref = infer_type(analyzer, tag.get_type()?);
         match type_ref {
             LuaType::DocFunction(func) => {
@@ -294,7 +305,7 @@ pub fn analyze_module(analyzer: &mut DocAnalyzer, tag: LuaDocTagModule) -> Optio
     let module_info = analyzer.db.get_module_index().find_module(&module_path)?;
     let export_type = module_info.export_type.clone();
     let module_file_id = module_info.file_id;
-    let owner_id = get_owner_id(analyzer)?;
+    let owner_id = get_owner_id_or_report(analyzer, &tag)?;
     if let Some(export_type) = export_type {
         match &owner_id {
             LuaSemanticDeclId::LuaDecl(decl_id) => {
@@ -372,7 +383,7 @@ pub fn analyze_cast(analyzer: &mut DocAnalyzer, tag: LuaDocTagCast) -> Option<()
 }
 
 pub fn analyze_see(analyzer: &mut DocAnalyzer, tag: LuaDocTagSee) -> Option<()> {
-    let owner = get_owner_id(analyzer)?;
+    let owner = get_owner_id_or_report(analyzer, &tag)?;
     let content = tag.get_see_content()?;
     let text = content.get_text();
 
@@ -385,7 +396,7 @@ pub fn analyze_see(analyzer: &mut DocAnalyzer, tag: LuaDocTagSee) -> Option<()>
 }
 
 pub fn analyze_other(analyzer: &mut DocAnalyzer, other: LuaDocTagOther) -> Option<()> {
-    let owner = get_owner_id(analyzer)?;
+    let owner = get_owner_id_or_report(analyzer, &other)?;
     let tag_name = other.get_tag_name()?;
     let description = if let Some(des) = other.get_description() {
         let description = preprocess_description(&des.get_description_text(), None);