在Haddock中隐藏类型同义词的声明

Question

我正在编写一个库，在其中我定义并导出了一些（非常复杂的）类型同义词T。

-- | A type
type T a b i o = ReaderT (WriterT i a X) (WriterT i b o)

库的内部，类型是有道理的。然而，对于用户来说，它是不必要的并且令人困惑。出于这个原因，我宁愿在Haddock页面中隐藏该类型的实际声明。

I.E。，我更喜欢Haddock页面看起来像这样......

type T a b i o
    A type

......而不是这个。

type T a b i o = ReaderT (WriterT i a X) (WriterT i b o)
    A type

这可能吗？如果是这样，怎么样？

Answer 1

如果您的用户真的不需要了解底层的内容，则应使用newtype而不导出构造函数。 GeneralizedNewtypeDeriving可以帮助缓解这种方法的痛苦。如果您的某些用户可能想要躲在窗帘后面，您可以从基础模块公开newtype构造函数，但将其隐藏在主模块中。类型同义词通常是一种非常弱的抽象工具。 lens库使用它们效果很好，允许包定义镜头而不依赖lens，但这有点奇怪。

我认为没有办法告诉Haddock隐藏类型同义词的含义。但是，这并不意味着你无法做你想做的事。

Cabal在构建文档时定义__HADDOCK_VERSION__ CPP宏。如果你这么倾向，你可以检测到这一点并用newtype替换类型同义词。当然，这不会编译，但我不认为这会导致Haddock出现任何问题。不过，我认为这根本不是明智的。