更改重新导出的类型和值的文档

Question

假设我有一个从内部模块重新导出值的模块：

module My.Cool.Module (SomeType, someValue) where
import My.Cool.Module.Internal (SomeType, someValue)

我想在 My-Cool-Module.html 和 My-Cool-Module-Internal.html 中显示 SomeType 和 someValue 的不同文档，以便前者可以讨论 public API，后者可以讨论它们与其余内部结构的关系。

有没有办法用黑线鳕做到这一点？

我试过了：

module My.Cool.Module (SomeType, someValue) where
import My.Cool.Module.Internal
  ( SomeType -- ^ a serious type for serious people
  , someValue -- ^ a serious value for serious people
  )

但是黑线鳕给我一个解析错误：

parse error on input ‘-- ^ a serious type for serious people’

Answer 1

好的，这是我可以接受的技巧。

Haddock 允许您插入 named chunks of documentation，它们按定义的顺序显示。这些命名块仅针对它们所在的模块显示，而不显示在该模块中 re-exports 值或类型的任何文件中。

所以在内部模块中，我可以在 public API 文档之后插入包含内部文档的命名块：

-- | Have you welcomed internal modules into your life?
module Public.Private where

-- | Here's the public API information for 'SomeType'
type SomeType = ()
-- $
-- Here's the internal information about 'SomeType': it's really just a stand-in
-- for San Francisco

-- | Here's the public API information for 'someValue'
someValue :: SomeType
-- $ Here's the internal information about 'someValue': it loves cheese.
someValue = ()

然后正常导出类型和值

-- | This is a very serious public API
module Public ( SomeType, someValue) where
import Public.Private ( SomeType , someValue)

现在为 Public.Private 生成的文档在 public 文档之后显示内部文档：

虽然导出项目的 Public 文档没有显示内部文档：

这只允许我附加私人文档，但这总比没有好。

更改重新导出的类型和值的文档

Changing the documentation for re-exported types and values

haskell

haddock