Functional Programming Documentation [closed]

Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.

---

We don’t allow questions seeking recommendations for books, tools, software libraries, an开发者_JAVA百科d more. You can edit the question so it can be answered with facts and citations.

Closed 4 years ago.

Improve this question

Is there any standard documentation (like UML for OO) for functional languages? After downloading couch db which is written in erlang and looking at the source code I was shocked, there is hardly a line of documentation. Is there no need to document how all these functions depend on each other? Are there better documented medium size projects freely available too learn, how things are done using this paradigm?

---

In functional languages like Haskell or ML, which have types and maybe module types (called "signatures" in Standard ML), the types provide an awful lot of documentation. In functional languages like Scheme, which don't have types checked by the compiler, they use "contracts" instead—except when they are sloppy.

Erlang was developed at Ericsson, and the telecoms industry has a very strong culture and record of testing. It wouldn't surprise me if the documentation of how those functions are supposed to work is in a test suite somewhere.

Summary: the two closest things to a standard are types (for functional languages with static type systems) and contracts (for functional languages that don't have static type systems).

---

The code should be documented, regardless of language.

There seems to be a standard documentation style called EDoc. EDoc is able to produce external API documentation; quoting from one source:

EDoc is the Erlang standard application to document the Erlang API directly inside the Erlang code.

This is referenced in the documentation section at erlang.org:

EDoc lets you write the documentation of an Erlang program as comments in the source code itself, using tags on the form "@Name ...". A source file does not have to contain tags for EDoc to generate its documentation, but without tags the result will only contain the basic available information that can be extracted from the module.

A focused Google search will take you from here.

---

This is a very interesting problem!

There are two issues - the first one is commenting the code and writing some documentation (in a textual form). This should be done in the usual way as in OO languages. You'd just write overview of all modules, functions and types that you use in your project. In F# (a functional language for .NET), you can write XML comments in a pretty similar way as in F# and generate documentation from these comments. I believe the F# documentation on MSDN is generated automatically from these comments. Here is an example from F# source code (if you install F# for VS 2008, it will also install source code of core libraries, which could be an interesting resource):

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

The second thing you mentioned is UML - there is no standard for drawing diagrams for functional languages. This seems to be a tricky problem. However, it is certainly possible to create diagram for code that uses some specific library. Many functional libraries allow you to compose code by composing several simple functions. List processing is a good example:

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

This could be nicely visually represented by drawing the data flow:

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

Similar drawings can be done for many functional libraries and they seem to be pretty useful (it's the kind of thing you draw when discussing something by the whiteboard). However, as far as I know there are no tools to do this automatically (though it should be possible IMHO).