功能编程文档[关闭]

Question

是否有功能语言的标准文档（如UML for OO）？ 在下载了用erlang编写的沙发数据库并查看源代码后，我很震惊，几乎没有一行文档。 是否没有必要记录所有这些功能如何相互依赖？ 是否有更好的文档中型项目可以免费学习，如何使用这种范式完成工作？

Answer 1

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

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

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

Answer 2

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

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

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

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

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

专注的谷歌搜索将带您从这里。

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 |/
+-----------+    +-----+

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