Functional Programming Documentation

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?

Answer 1

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.

Answer 2

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).