jsdoc 解析无法识别联合类型，导致解析中断

Question

闭包[联合类型规范|https://developers.google.com/closure/compiler/docs/js-for-compiler#unions] 指出，联合类型表达式需要括号。尝试如下...



(defn foo
  "@param {(IBar|IMap)} x"
  [x]
  ...)

 
引发闭包错误


...ERROR - 错误的类型注释。期望闭合}
* @param {user.(IBar|user.IMap)}


这是因为在 comp/resolve-types 中，括号被视为类型标记的一部分，因此导致错误的变量解析。此外，编译器通过 "|" 字符分隔多个解析类型，但未将它们括起来以创建有效的联合类型。

Answer 1

评论者：pkillean

此补丁包括

• comp/resolve-types 现在在存在时移除括号，并在检测到大于1个类型时发出它们。这使得括号使用成为可选的，并且现有代码保持不变（增加的好处是它可能现在可以工作了）

• 对 comp/resolve-type 的更改
  1. 检查闭包识别的 js 全局，如 document 或 window
  1. 允许点分隔的形式通过，以便我们可以在 externs 中使用类型并避免不必要的解析
  1. 使用 ana/resolve-existing-var 并发出“未解析的jsdoc类型”警告
  1. 检查解析的变量是否是协议，并在不是协议时发出警告。这比 Closure 的标准未识别类型错误更有信息量

• 对 comp/resolve-types 的测试

Answer 2

评论者：dnolen

谢谢，明天我会更仔细地看看这个问题。

Answer 3

评论者：dnolen

补丁正在逐步改进，请移除 js-doc-type 元数据内容。只需扩展 {{resolve-existing-var}} 的签名，添加一个额外的参数 - {{confirm-var-exists}} 处理器。

Answer 4

评论者：pkillean

CLJS-1627-1.patch
{{resolve-existing-var}} 现在有了一个额外的参数数，它接受传递给 {{confirm-existing-var}} 的缺少变量处理器。

Answer 5

评论者：pkillean

这揭示了一个问题，即使用对象协议的 {{deftype}} 和 {{defrecord}} 在实际上不应发出解析名称。例如：“@implements {cljs.core.async.impl.timers.Object}” --> 错误类型注解

由于 {{Object}} 是一个特殊情况，仅从注释中排除它应该可以解决这个问题。还有另一个补丁即将到来

Answer 6

评论者：pkillean

CLJS-1627-2.patch
现在，deftype 和 defrecord 的 emit* 方法将过滤掉对象协议。

这产生了一个有趣的成果！没有更多错误的类型注解后，静态分析现在可以继续...而且它有很多话要说。现在有关于参数不一致的各种信息（尤其是 cljs.core.IndexedSeq），类型不匹配，等等。它还包括类型覆盖率百分比。这里有很多东西需要解析，但非常酷。

Answer 7

评论者：pkillean

CLJS-1627-3.patch
修复合并外部需求
添加了对 Array 和 Object 的类型应用支持
垃圾收集器喜欢大小写为 Object 和 Array，小写为 string 和 number。
支持显式的可空类型，可变类型参数
* 函数类型上下文修饰符 {{this}} + {{new}}

-Missing 是 GC 的 'record type' - 。也可能需要完成节点外部的常见类型填写

Answer 8

评论者：pkillean

CLJS-1627-4.patch
修复上次补丁中的一些问题
添加记录类型支持。所有内容（链接：https://developers.google.com/closure/compiler/docs/js-for-compiler#types 文本：见下文）都应被包含在内

Answer 9

评论者：pkillean

更新补丁

Answer 10

评论者：mfikes

CLJS-1627-5.patch不再适用

Answer 11

评论者：pkillean

第6个补丁
通过 comparition/emit-comment 处理 js 注释，该接口已修改以处理内联注释
支持的标签：param, return, type, implements, typedef, enum, extends, throws, lends, const, this
添加宏 core/goog-typedef，这允许您命名自定义类型并在注释中引用它。

还需要更多的工作来支持多参数函数，但我认为这几乎解锁了基本的静态类型检查 :-)

Answer 12

评论者：mfikes

Hey Patrick，CLJS-1627-6.patch不适用于master。

Answer 13

评论者：pkillean

应该喝完咖啡再来进行

Answer 14

评论者：mfikes

CLJS-1627-7.patch 补丁不适用于当前主分支

Answer 15

参考： https://clojure.atlassian.net/browse/CLJS-1627（由pkillean提出）