当将带 JSDoc 注释的函数作为属性赋值给对象（如 style = {border}）时，部分 IDE 或工具可能无法正确继承原函数的类型与参数说明，导致提示显示为 ANY；根本原因常在于变量声明缺失或作用域解析异常。
当将带 jsdoc 注释的函数作为属性赋值给对象（如 `style = {border}`）时，部分 ide 或工具可能无法正确继承原函数的类型与参数说明，导致提示显示为 `any`；根本原因常在于变量声明缺失或作用域解析异常。
在 JavaScript 模块化组织中，我们常希望将一组相关函数归入命名空间对象（如 style），以提升可维护性与语义清晰度。但若直接使用 style = {border} 这类简写形式，TypeScript 编译器或主流编辑器（VS Code、WebStorm）在类型推导时可能丢失原始函数的 JSDoc 元信息——尤其当 style 变量未显式声明类型或缺少 const/let 声明时，工具链会将其视为无类型动态对象，从而降级为 any 提示。
✅ 正确做法是：显式声明变量，并确保函数引用保持原始定义上下文。以下是优化后的完整示例：
var GDL = (function () {
// 配置默认值
const border_style = ["solid"];
const border_width = [2];
const border_color = "black";
const border_radius = 0;
/**
* 添加边框样式到 canvas 元素。
* 支持 1 个值（四边统一）、2 个值（上下 / 左右）、4 个值（左/上/右/下）的数组传入。
* @param {string|string[]} [style=["solid"]] 边框样式，如 'solid'、'dashed'
* @param {number|number[]} [width=[2]] 边框宽度（px）
* @param {string} [color="black"] 边框颜色
* @param {number} [borderRadius=0] 圆角半径（px）
* @returns {void}
*/
function border(style = border_style, width = border_width, color = border_color, borderRadius = border_radius) {
// 实际实现逻辑（略）
}
// ✅ 关键修复：显式声明 style 变量，并直接引用函数（不破坏签名）
const style = { border }; // 使用 const + 解构赋值，保留函数元数据
return { style };
})();
// 此时调用可获得完整 JSDoc 提示
GDL.style.border(/* ⬅️ 鼠标悬停将显示完整参数说明 */);
⚠️ 注意事项：
-
避免隐式全局变量：原代码中
style = {border}缺少const/let/var声明，会导致style成为意外的全局变量，破坏模块封闭性，也干扰类型推断； -
不要重命名或包装函数：如
border: function(...){}或border: (...args) => border(...args)会切断 JSDoc 关联，应始终使用直接属性引用border； -
TypeScript 用户建议补充类型声明（可选增强）：
interface StyleAPI { border: typeof border; } const style: StyleAPI = { border };
总结：JSDoc 的可见性依赖于工具对函数引用路径的静态分析能力。只要保证函数以“未包装、未重命名、显式声明”的方式挂载到对象上，主流开发环境即可准确映射参数文档。结构化组织与良好注释并不冲突——关键在于遵循语言规范与工具链的最佳实践。
