函数式编程文档

Question

有没有针对函数式语言的标准文档(比如面向对象的UML )？在下载了用erlang编写的couch db并查看了源代码后，我震惊了，几乎没有一行文档。有没有必要记录所有这些功能是如何相互依赖的？有没有更好的文档记录的中等规模的项目也可以免费学习，如何使用这个范例来做事情？

Answer 1

无论语言如何，代码都应该被记录下来。

似乎有一个standard documentation style called EDoc。EDoc能够制作外部应用程序接口文档；引用自一个来源：

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

这在documentation section at erlang.org中被引用

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

一个focused Google search会带你离开这里。

Answer 2

在函数式语言中，如Haskell或ML，它们有类型，也可能有模块类型(在标准ML中称为“签名”)，这些类型提供了大量的文档。在像Scheme这样的函数式语言中，它们不需要编译器检查类型，而是使用"contracts“-除非它们是草率的。

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

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

Answer 3

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

有两个问题-第一个问题是注释代码和编写一些文档(以文本形式)。这应该像在OO语言中一样以通常的方式来完成。您只需编写项目中使用的所有模块、函数和类型的概述即可。在F# (一种用于.NET的函数式语言)中，您可以用与F#非常相似的方式编写XML注释，并从这些注释生成文档。我相信MSDN上的F# documentation是从这些评论中自动生成的。这里有一个来自F#源代码的例子(如果你为VS2008安装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 |/
+-----------+    +-----+

可以为许多函数库绘制类似的绘图，它们似乎非常有用(这就是您在白板上讨论某件事情时所画的东西)。然而，据我所知，目前还没有工具可以自动完成此操作(尽管应该可以使用IMHO)。