It is sometimes said that functional programs are self-documenting. Sadly, although functional programming languages may produce programs that are more readable, complex programs are not self-documenting, let alone obvious to understand. Free text comments in program modules, if kept up-to-date, are a first step in describing a program. However, they have the disadvantage of lacking structure as well as being difficult to scan, search, and read independently of the program text.
EDoc provides a documentation framework for Erlang that overcomes these disadvantages and generates documentation from information you have inserted in your modules:
EDoc provides a structure for comments,
spec information as well as textual comments
EDoc is a documentation generator: a standard style of HTML document is generated from the structured information in each module.
EDoc provides a framework for adding information covering a whole set of modules (e.g., in an application or a package), providing an overview of the larger-scale structure or assumptions for the whole system.
EDoc is part of the standard Erlang distribution, and it has a lot in common with similar systems such as Haddock (for Haskell), Javadoc, pydoc, and RDoc (for Ruby). In this section, we will introduce you to many of EDoc’s features by documenting the mobile user database example from Chapter 10.
It is intended that in later releases of Erlang/OTP, EDoc will share information ...