Skip to content

Fix doc tag associations, warn about useless tags #647

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 18, 2025
Merged

Fix doc tag associations, warn about useless tags #647

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 19 additions & 14 deletions crates/emmylua_code_analysis/src/compilation/analyzer/doc/property_tags.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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() {
Expand All @@ -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
Expand All @@ -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>()?;
Expand All @@ -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() {
Expand Down
46 changes: 43 additions & 3 deletions crates/emmylua_code_analysis/src/compilation/analyzer/doc/tags.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ use emmylua_parser::{

use crate::{
db_index::{LuaMemberId, LuaSemanticDeclId, LuaSignatureId},
LuaDeclId,
AnalyzeError, DiagnosticCode, LuaDeclId,
};

use super::{
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: this is the main change, the rest is just error reporting.

return Some(LuaSemanticDeclId::TypeDecl(current_type_id.clone()));
}
let owner = analyzer.comment.get_owner()?;
match owner {
LuaAst::LuaAssignStat(assign) => {
Expand Down Expand Up @@ -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(),
},
);
}
13 changes: 8 additions & 5 deletions crates/emmylua_code_analysis/src/compilation/analyzer/doc/type_def_tags.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down Expand Up @@ -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() {
Expand Down
39 changes: 25 additions & 14 deletions crates/emmylua_code_analysis/src/compilation/analyzer/doc/type_ref_tags.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::{
Expand All @@ -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))
Expand All @@ -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();
Expand Down Expand Up @@ -137,7 +142,9 @@ pub fn analyze_type(analyzer: &mut DocAnalyzer, tag: LuaDocTagType) -> Option<()
}
}
}
_ => {}
_ => {
report_orphan_tag(analyzer, &tag);
}
}

Some(())
Expand Down Expand Up @@ -196,6 +203,8 @@ pub fn analyze_param(analyzer: &mut DocAnalyzer, tag: LuaDocTagParam) -> Option<
break;
}
}
} else {
report_orphan_tag(analyzer, &tag);
}

Some(())
Expand All @@ -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 {
Expand Down Expand Up @@ -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(())
Expand All @@ -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) => {
Expand All @@ -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) => {
Expand Down Expand Up @@ -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();

Expand All @@ -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);
Expand Down
Loading