haddock 差异化文档

Question

如果我对我的库运行cabal build，然后更改一个文件，下次运行cabal build时，我只需要重新编译受更改影响的文件。但是，使用cabal haddock命令时，我没有得到相同的行为：当我在更改文件后运行它时，cabal/haddock最终会丢弃所有先前的工作并从头开始。这相当耗时；有没有一种方法可以获得差异更新文档的方式？

这里是生成文档所需的命令cabal发出的转储。

- crockeea

---

我不记得：如果链接到不存在的东西，haddock是否无法构建？比如使用'MyModule'而你没有可用的MyModule。因为如果它只是给出一个警告并继续运行，那么这种行为是必需的：对现有文件进行任何更改或添加文件可能会修改其他模块文档的输出。 - Bakuriu

如果我在文件顶部随机添加一个import ModuleDoesNotExist，Haddock将会短路并且不会输出任何文档。如果我强制引发任何其他编译错误（例如语法错误），Haddock会输出截止到出现错误的模块的文档，但随后也将会短路并且不会输出其他模块的文档。 - crockeea

@user5402 在问题中添加了链接。 - crockeea

cabal haddock 命令需要多长时间？ - ErikR

@user5402 在两种情况下，41秒仅适用于cabal haddock部分。构建本身需要很长时间，但我没有在上面包括这段时间。 - crockeea

Answer 1

processModules 文档说:

使用 GHC API 对模块列表进行类型检查，并使用处理后的语法树创建接口和链接环境。

这是 haddock 的核心功能。所以目前来看，答案是否定的。

cabal build 对 cabal haddock 没有任何帮助，因为 haddock 使用不同的参数对模块进行类型检查（例如启用了 __HADDOCK__ CPP 变量）。

可靠的增量式 haddock 生成很难实现，因为依赖图中后面的代码可以修改之前某一点的模块文档，特别是实例清单。可能可以转储模块接口。

查看 processModules 的代码，第一步是可能可以逐步执行的，其余部分则需全局信息。

尝试将冗长度调至最大，即--haddock-options=--verbosity=2，并检查在Creating interfaces...和Attaching instances...之间花费了多少时间。

- phadej

---

cabal haddock --haddock-options=--verbosity=2 不会打印任何关于“创建接口”或“附加实例”的内容。 - crockeea

@Erik，看起来你需要给cabal加上-v3参数才能获得haddock的详细输出。另一方面，似乎大部分时间都花在了Creating interfaces...和Attaching instances之间。也许有优化的机会。 - phadej

“附加实例”和“创建接口”都基本上是瞬间完成的，但“检查模块”的步骤对于每个模块需要一定的时间。 - crockeea

好的。有一个中间类型TypecheckedModule，看起来可以将其序列化到磁盘上并恢复，但如果在Ghc单子中发生了什么需要保留，我对GHC内部不够了解。最好从这里转向ghc-dev或haddock问题跟踪器。 - phadej