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

Question

The Closure [Spec For Union Types|https://developers.google.com/closure/compiler/docs/js-for-compiler#unions] 指出，联合类型表达式需要用到括号。尝试这样做...



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

 
引发 Closure 错误


...ERROR - 类型注解错误。期望闭括号}
* @param {user.(IBar|user.IMap)}


这是因为comp/resolve-types将括号视为类型标记的一部分，因此发生了错误的变量解析。此外，编译器使用“|”字符分隔多个已解析的类型，但未将它们括起来，以创建有效的联合类型。

Answer 1

评论者：pkillean

此补丁包含

• comp/resolve-types现在在存在的情况下移除括号，并在检测到大于1个类型时发布它们。这使得括号的使用是可选的，并且现有代码不会中断（此外的好处是它可能现在可以工作了）

• 对comp/resolve-type的更改
  1. 检查由closure识别的js全局变量如document或window
  1. 允许.dot.delimited.forms通过，这样我们就可以使用在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
解决外部require
添加数组与对象的类型应用支持
GC喜欢大写Object & Array，小写string和number。
支持显式可空类型，变量类型参数
函数类型上下文修饰符{{this}} + {{new}}

-Missing是GC的“记录类型”。也可能有用填充节点外部的常见类型。

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个补丁
将js注释通过comp/emit-comment进行路由，该操作已被修改以处理内联注释。
支持标签：param, return, type, implements, typedef, enum, extends, throws, lends, const, this
添加了宏core/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 报告）