documentation - 函数式编程文档

Question

是否有函数式语言的标准文档（如面向 OO 的 UML）？下载了用 erlang 编写的 couch db 并查看源代码后我惊呆了，几乎没有一行文档。是否不需要记录所有这些功能如何相互依赖？是否有更好的文档中型项目免费提供学习，如何使用这种范式完成工作？

Answer 1

在像 Haskell 或 ML 这样的函数式语言中，它们有类型，可能还有模块类型（在标准 ML 中称为“签名”），这些类型提供了大量的文档。在像 Scheme 这样的函数式语言中，编译器没有检查类型，它们使用“契约”来代替——除非它们是草率的。

Erlang 是在爱立信开发的，电信行业拥有非常强大的文化和测试记录。如果这些功能应该如何工作的文档在某个地方的测试套件中，我不会感到惊讶。

总结：最接近标准的两个东西是类型（对于具有静态类型系统的函数式语言）和契约（对于没有静态类型系统的函数式语言）。

Answer 2

无论语言如何，都应记录代码。

似乎有一种称为 EDoc 的标准文档样式。EDoc 能够生成外部 API 文档；引用一个来源：

EDoc 是 Erlang 标准应用程序，用于在 Erlang 代码中直接记录 Erlang API。

这在 erlang.org 的文档部分中引用：

EDoc 允许您使用“@Name ...”形式的标签将 Erlang 程序的文档编写为源代码本身的注释。源文件不必包含用于 EDoc 生成其文档的标签，但没有标签，结果将仅包含可从模块中提取的基本可用信息。

有针对性的 Google 搜索将带您从这里开始。

Answer 3

这是一个非常有趣的问题！

有两个问题 - 第一个是注释代码和编写一些文档（以文本形式）。这应该像在 OO 语言中一样以通常的方式完成。您只需编写您在项目中使用的所有模块、功能和类型的概述。在 F#（.NET 的一种函数式语言）中，您可以使用与 F# 中非常相似的方式编写 XML 注释，并从这些注释生成文档。我相信 MSDN 上的F# 文档是根据这些评论自动生成的。下面是一个来自 F# 源代码的示例（如果您为 VS 2008 安装 F#，它还将安装核心库的源代码，这可能是一个有趣的资源）：

/// Return the first element of the list.
///
/// Raises <c>System.ArgumentException</c> if <c>list</c> is empty
val head: list:'T list -> 'T

您提到的第二件事是 UML - 没有为功能语言绘制图表的标准。这似乎是一个棘手的问题。但是，当然可以为使用某些特定库的代码创建图表。许多函数库允许您通过组合几个简单的函数来编写代码。列表处理就是一个很好的例子：

let custNames = customers |> List.map (fun customer -> customer.Name) 
let empNames = employees |> List.map (fun employee -> employee.Name) 
let result = List.concat [custNames; empNames]

这可以通过绘制数据流在视觉上很好地表示：

+-----------+    +-----+
| customers |--->| map |\
+-----------+    +-----+ \ +--------+   +--------+
                          >| concat |-->| result |
+-----------+    +-----+ / +--------+   +--------+
| employees |--->| map |/
+-----------+    +-----+

可以为许多功能库完成类似的绘图，并且它们似乎非常有用（这是您在白板上讨论某事时绘制的那种东西）。但是，据我所知，没有工具可以自动执行此操作（尽管恕我直言）。