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. 检查解析的变量是否为协议，如果不是则发出警告。这比闭包的标准未识别类型错误更有信息量

• 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 提供

这揭示了一个问题，即使用Object协议的{{deftype}} + {{defrecord}}实际上不应该发出已解析的名称。例如："@implements {cljs.core.async.impl.timers.Object}" —— 错误的类型注解

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

Answer 6

评论由：pkillean 提供

CLJS-1627-2.patch
对于deftype和defrecord的emit*方法现在筛选出Object协议。

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

Answer 7

评论由：pkillean 提供

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

缺少GC 'record类型'。填充常见类型的节点externs也可能很有用。

Answer 8

评论由：pkillean 提供

CLJS-1627-4.patch
修复上一个补丁中的几个问题
添加record类型支持。应涵盖一切（链接：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个补丁
通过comp/emit-comment将js注释路由，该组件已被修改以处理内联注释。
支持的标签：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不存在

Answer 15

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