Functional Programming Documentation [closed]

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

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

Answer 2

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.