fix(overload): prioritize explicitly documented signatures

fix #1162

Author: xuhuanzy

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

@@ -213,6 +213,7 @@ pub fn analyze_param(analyzer: &mut DocAnalyzer, tag: LuaDocTagParam) -> Option<
             .get_db()
             .get_signature_index_mut()
             .get_or_create(id);
+        signature.has_explicit_docs = true;
         let param_info = LuaDocParamInfo {
             name: name.clone(),
             type_ref: type_ref.clone(),
@@ -261,6 +262,7 @@ pub fn analyze_return(analyzer: &mut DocAnalyzer, tag: LuaDocTagReturn) -> Optio
         .collect::<Vec<_>>();
 
     bind_signature_return_docs(analyzer, &tag, |signature| {
+        signature.has_explicit_docs = true;
         signature.return_docs.extend(return_infos);
     })
 }

crates/emmylua_code_analysis/src/db_index/signature/signature.rs

@@ -21,6 +21,7 @@ use crate::{
 pub struct LuaSignature {
     pub generic_params: Vec<GenericParam>,
     pub overloads: Vec<Arc<LuaFunctionType>>,
+    pub has_explicit_docs: bool,
     pub param_docs: HashMap<usize, LuaDocParamInfo>,
     pub params: Vec<String>,
     pub return_docs: Vec<LuaDocReturnInfo>,
@@ -49,6 +50,7 @@ impl LuaSignature {
         Self {
             generic_params: Vec::new(),
             overloads: Vec::new(),
+            has_explicit_docs: false,
             param_docs: HashMap::new(),
             params: Vec::new(),
             return_docs: Vec::new(),

crates/emmylua_code_analysis/src/diagnostic/test/assign_type_mismatch_test.rs

@@ -891,6 +891,70 @@ return t
         ));
     }
 
+    #[test]
+    fn test_literal_argument_selects_overload_return_type() {
+        let mut ws = VirtualWorkspace::new();
+        assert!(ws.has_no_diagnostic(
+            DiagnosticCode::AssignTypeMismatch,
+            r#"
+            ---@class A
+            ---@class B
+            local C
+
+            ---@overload fun(): A
+            ---@overload fun(type: "fluid"): B
+            function C.name(type) end
+
+            local tmp = C.name("fluid")
+        "#
+        ));
+    }
+
+    #[test]
+    fn test_explicit_signature_param_keeps_main_return_priority() {
+        let mut ws = VirtualWorkspace::new();
+        assert!(ws.has_no_diagnostic(
+            DiagnosticCode::AssignTypeMismatch,
+            r#"
+            ---@class A
+            ---@class B
+            local C
+            local a ---@type A
+
+            ---@overload fun(type: "fluid"): B
+            ---@param type "fluid"
+            function C.name(type)
+                return a
+            end
+
+            local tmp = C.name("fluid")
+        "#
+        ));
+    }
+
+    #[test]
+    fn test_table_field_explicit_signature_param_keeps_main_return_priority() {
+        let mut ws = VirtualWorkspace::new();
+        assert!(ws.has_no_diagnostic(
+            DiagnosticCode::AssignTypeMismatch,
+            r#"
+            ---@class A
+            ---@class B
+            local a ---@type A
+
+            local C = {
+                ---@overload fun(type: "fluid"): B
+                ---@param type "fluid"
+                name = function(type)
+                    return a
+                end
+            }
+
+            local tmp = C.name("fluid")
+        "#
+        ));
+    }
+
     #[test]
     fn test_table_pack_in_function() {
         let mut ws = VirtualWorkspace::new_with_init_std_lib();

crates/emmylua_code_analysis/src/semantic/overload_resolve/collect_overloads.rs

@@ -91,9 +91,14 @@ fn collect_callable_overload_groups_inner(
             let Some(signature) = db.get_signature_index().get(sig_id) else {
                 return Ok(());
             };
-            // 主签名描述了函数实现本身, 当它和 overload 同时可匹配时应作为同等匹配下的优先候选.
-            let mut overloads = vec![signature.to_doc_func_type()];
-            overloads.extend(signature.overloads.iter().cloned());
+            let main_signature = signature.to_doc_func_type();
+            let mut overloads = signature.overloads.clone();
+            // 显式声明参数或返回值的主签名, 在匹配程度相同时优先于 overload.
+            if signature.has_explicit_docs {
+                overloads.insert(0, main_signature);
+            } else {
+                overloads.push(main_signature);
+            }
             groups.push(overloads);
         }
         LuaType::Instance(instance) => {
@@ -136,7 +141,9 @@ fn push_call_operator_overload_group(
     };
 
     // 同一个 owner 的 call operators 作为一个 overload group, 由调用方再做参数匹配.
-    let mut overloads = Vec::new();
+    let mut declared_signatures = Vec::new();
+    let mut doc_functions = Vec::new();
+    let mut undeclared_signatures = Vec::new();
     for operator_id in operator_ids {
         let Some(operator) = db.get_operator_index().get_operator(operator_id) else {
             continue;
@@ -148,22 +155,29 @@ fn push_call_operator_overload_group(
         }
 
         match func_type {
-            LuaType::DocFunction(func) => overloads.push(func),
+            LuaType::DocFunction(func) => doc_functions.push(func),
             LuaType::Signature(signature_id) => {
                 let Some(signature) = db.get_signature_index().get(&signature_id) else {
                     continue;
                 };
                 // 未解析返回的 signature 不能安全转换成候选, 这里先跳过.
                 if signature.is_resolve_return() {
-                    overloads.push(signature.to_call_operator_func_type());
+                    let function = signature.to_call_operator_func_type();
+                    if signature.has_explicit_docs {
+                        declared_signatures.push(function);
+                    } else {
+                        undeclared_signatures.push(function);
+                    }
                 }
             }
             _ => {}
         }
     }
 
-    if !overloads.is_empty() {
-        groups.push(overloads);
+    declared_signatures.extend(doc_functions);
+    declared_signatures.extend(undeclared_signatures);
+    if !declared_signatures.is_empty() {
+        groups.push(declared_signatures);
     }
 }