fix(overload): prioritize explicitly documented signatures

fix #1162

Author: xuhuanzy

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

@@ -1,8 +1,12 @@
+use emmylua_parser::{
+    LuaAstNode, LuaClosureExpr, LuaCommentOwner, LuaDocTagParam, LuaDocTagReturn, LuaStat,
+    LuaTableField,
+};
 use hashbrown::HashSet;
 use std::sync::Arc;
 
 use crate::{
-    DbIndex, LuaOperatorMetaMethod, LuaOperatorOwner, LuaTypeDeclId, LuaUnionType,
+    DbIndex, LuaOperatorMetaMethod, LuaOperatorOwner, LuaSignatureId, LuaTypeDeclId, LuaUnionType,
     db_index::{LuaFunctionType, LuaType},
     semantic::{
         generic::{TypeSubstitutor, instantiate_type_generic},
@@ -91,9 +95,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();
+            // 如果存在参数/返回值签名, 那么他的优先级在同等条件下是更高的
+            if signature_has_declared_docs(db, sig_id) {
+                overloads.insert(0, main_signature);
+            } else {
+                overloads.push(main_signature);
+            }
             groups.push(overloads);
         }
         LuaType::Instance(instance) => {
@@ -136,7 +145,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 +159,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_declared_docs(db, &signature_id) {
+                        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);
     }
 }
 
@@ -260,3 +278,35 @@ fn call_operator_self_for_type_id(
     visiting_aliases.remove(type_id);
     has_call.then(|| ty.clone())
 }
+
+fn signature_has_declared_docs(db: &DbIndex, signature_id: &LuaSignatureId) -> bool {
+    let Some(tree) = db.get_vfs().get_syntax_tree(&signature_id.get_file_id()) else {
+        return false;
+    };
+    let Some(token) = tree
+        .get_red_root()
+        .token_at_offset(signature_id.get_position())
+        .right_biased()
+    else {
+        return false;
+    };
+    let Some(closure) = token
+        .parent_ancestors()
+        .find_map(LuaClosureExpr::cast)
+        .filter(|closure| closure.get_position() == signature_id.get_position())
+    else {
+        return false;
+    };
+    let comments = if let Some(table_field) = closure.get_parent::<LuaTableField>() {
+        table_field.get_comments()
+    } else if let Some(stat) = closure.ancestors::<LuaStat>().next() {
+        stat.get_comments()
+    } else {
+        return false;
+    };
+
+    comments.into_iter().any(|comment| {
+        comment.children::<LuaDocTagParam>().next().is_some()
+            || comment.children::<LuaDocTagReturn>().next().is_some()
+    })
+}