jsdoc解析无法识别联合类型，导致解析失败

Question

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



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

 
引发闭包错误


……错误 - 类型注解无效。期望关闭}
* @param {user.(IBar|user.IMap)}


这是因为comp/resolve-types将括号视为类型标记的一部分，并且由于错误的var解析而发生了错误。此外，编译器会在 "|" 字符间发射多个已解析的类型，但不将它们放在括号中以创建有效的联合类型。

Answer 1

评论者：pkillean

此补丁包括

• comp/resolve-types现在在存在时会删除括号，并在检测到大于1个类型时会产生括号。这使括号使用变得可选，并且现有代码仍然完好无损（附带的好处是它现在可能也可以工作）

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

• 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}} 使用 Object 协议发出解析后的名称时实际上不应该这样做。例如："@implements {cljs.core.async.impl.timers.Object}" --> 错误类型注解

由于 {{Object}} 是一个特殊情况，只需将其从注释中排除即可解决问题。还有另一个补丁即将到来

Answer 6

评论者：pkillean

CLJS-1627-2.patch
deftype 和 defrecord 的 emit* 方法现在会过滤出 Object 协议。

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

Answer 7

评论者：pkillean

CLJS-1627-3.patch
修复 require extern
为 Array 和 Object 添加类型应用支持
GC 喜欢大写字母的 Object 和 Array，小写字母的字符串和数字。
支持显式可空类型、变量类型参数
* 函数类型上下文修饰符 {{this}} + {{new}}

-Missing 是 GC 的 'record type'。还可能需要填写常见类型的节点 extern。

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

第六版补丁
通过 comp/emit-comment 处理对 JS 评论的路由，该代码已修改以处理内联注释。
支持的标签：param, return, type, implements, typedef, enum, extends, throws, lends, const, this
添加宏核心/goog-typedef。这允许您命名自定义类型，并在注解中引用它。

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

Answer 12

评论者：mfikes

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

Answer 13

评论者：pkillean

应该先喝杯咖啡

Answer 14

评论者：mfikes

CLJS-1627-7.patch不适用于当前master

Answer 15

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