标签: haddock

目前我只使用Haddock,但在看到一些有文化的Haskell的一些非常有趣的例子(例如这个要点)之后,我有兴趣在一个项目中尝试它.

我得到的问题是:

• 你怎么写Haddock评论,你在文学部分写什么？

• 如何将识字编程扩展到多个文件？有人能指出我在一个包含多个模块的程序包中使用文字编程的例子吗？您在大型软件包中使用文字编程的经验是什么？

• 有文化的Haskell的哪种口味(降价,乳胶,...)是首选？

• 你为什么要用文字的Haskell或普通的Hillaell编程？你是在两种风格的编程,如果是这样,为什么？

• 你喜欢block-style(\begin{code})还是Bird-style(>)？为什么？

我看到Haskell多行注释有时候会开始{- |而不仅仅是{-.

引用注释中的管道符号是否符合惯例？

如何使用haddock文档工具继续编号列表？黑线鳕的以下几行

--  1. First line.
-- 
--  2. Second line with instructions to do something 
-- 
--     >>> command-linecmd param
--
--  3. Third line..
--

生成下一个html:

</p><ol><li> First line.
</li><li> Second line with instructions to do something 
</li></ol><pre class="screen"><code class="prompt">&gt;&gt;&gt; </code><strong         class="userinput"><code>command-linecmd param
</code></strong></pre><ol><li> Third line..
</li></ol>

这打破了编号.有没有办法让黑线鳕继续使用HTML中的第三个数字,或者我应该尝试其他的东西(>>>给出一个很好的格式,我为什么要使用它)？

我已经用Haddock样式注释了我的代码,并希望生成可浏览的文档.由于我也使用堆栈,我想将文档生成集成到工作流程中.但是,我还没有能够产生任何有用的东西.

我可以跑

stack haddock

它将生成我想要的样式的文档(深入内部~/.stack/),但它似乎只生成我依赖的包的文档,而不是我自己的代码.

我跑的时候

stack haddock --help

我得到的印象是,我可以使用附加参数--haddock为我自己的项目生成文档,并--no-haddock-deps省略我的依赖项的文档.但是,当我跑

stack haddock --haddock --no-haddock-deps

似乎什么也没发生.如果我stack clean首先它将重新编译我的所有代码,但没有生成输出,似乎以任何方式与文档相关.

作为一个中间解决方案,我也试过自己运行Haddock,即

haddock my-source.hs

但后来我得到一个错误,它无法找到文件依赖的模块(由堆栈本地安装).这让我觉得文档生成必须以某种方式通过堆栈.我已经找了,但没有真正找到任何与配置文档.cabal和stack.yaml文件相关的解释.

TL; DR

如何使用stack和Haddock为我自己的包中的代码生成文档？

我是操作包的作者,其中包括示例代码.我想这个示例代码是hscolored并与由Haddock生成的API文档一起安装.

我可能必须使用自定义Cabal构建类型并为Haddock阶段创建用户钩子.但是,我从未设法做到这一点.因此,我的问题是:

如何将完整模块作为示例代码包含在Haddock中？

你能给出一个Cabal用户钩子的例子,它将hscolor应用于另一个源代码文件example.hs并将结果与​​生成的Haddock文档连接起来吗？

如何在本地Haddock文档中嵌入图像？

我看到例如在lens包装只是使用的外部链接的图像,但我想在本地存储的图像.

(这个问题与邮件列表上的(未答复的)问题非常相似).

该命令cabal haddock非常有用--hyperlink-source选项.我希望在构建文档时使用超链接来源cabal install.

机票#517似乎就是这样:http://hackage.haskell.org/trac/hackage/ticket/517

但是,也许可以通过〜/ .cabal/config文件设置这个标志？

如果没有,我如何使用来自#517的补丁进行cabal-install构建,而不安装目前强制要求的Cabal-1.9(由于12月的一个补丁)？

在许多Haddock生成的模块文档(例如Prelude)中,可以看到右上角的一个小框,包含可移植性,稳定性和维护者信息:

从查看源代码到这些模块和实验,我确认此信息是从模块描述中的以下行生成的:

-- Maintainer  :  libraries@haskell.org
-- Stability   :  stable
-- Portability :  portable

这有几个奇怪的事情:

• 这些字段似乎只按此顺序工作 - 任何按顺序排列的字段都只是作为模块描述本身的一部分.尽管源文件中的顺序与生成的文档中的顺序相反,但这是事实!

• 我一直无法找到这些字段的任何官方文档.有一个名为Cabal包的属性stability,其示例值与我在等效的Haddock字段中看到的值相匹配,但除此之外,我什么也没找到.

那么:这些字段是如何使用的,是否可以在任何地方记录？

特别是,我想知道:

• 对于常用值的完整列表Portability和Stability.这个HaskellWiki页面有一个列表,但我想知道这个列表的起源.

• 决定模块是便携式还是非便携式的标准.特别是,我希望这些问题的答案,acme-strfry,是一个FFI绑定strfry,一个只在glibc中可用的函数.包是不可移植的,因为它只适用于glibc系统或可移植,因为它不使用任何Haskell语言扩展？常见的用法似乎意味着后者.

• 为什么源文件中需要特定的字段顺序,以及为什么它与生成的文档中的顺序相反.

链接到URL时,可以提供一个标签,指明读者将看到的内容; 例如,<http://www.haskell.org haskell>链接文本将具有"haskell".不幸的是,文档没有提供标记链接到锚点的明显方法; 链接"Data.FooBar#foo"将为链接文本提供"Data.FooBar",这样读者就不会明白此链接是否会发送到锚点.

所以我的问题是:是否有一个技巧来标记链接到黑线鳕的锚点,或者这是不可能的？

我查看了GHC.Prim的模块,发现似乎GHC.Prim中的所有数据都被定义为data Float#没有类似的东西=A|B,并且GHC.Prim中的所有函数都被定义为gtFloat# = let x = x in x.

我的问题是这些定义是否有意义以及它们的含义.

我检查了GHC.Prim的标题,如下所示

{-
This is a generated file (generated by genprimopcode).
It is not code to actually be used. Its only purpose is to be
consumed by haddock.
-}

我想它可能与问题有一些关系,谁可以向我解释.