The tool faust2md provides an ultra simple documentation system for Faust. It extracts the comments from a Faust file and creates a documentation file based on the lightweight markup language markdown.

The basic usage is faust2md [-t 4] [-c] [-f] foo.dsp > foo.md. The option -t n can be used to change the default tab setting. The option -c can be used to include the faust code itself into the generated file. The option -f adds a YAML front matter at the begin of the documentation file.

The structure of the comments to annotate the source code is the following :

//------------ foo(x,y) ----------------
//  markdown formatted text....
//  markdown formatted text....
//---------------------------------------

Everything else is considered Faust code. The resulting translation is:

# foo(x,y)
markdown formatted text....
markdown formatted text....

Practical example

The convention for the comments was chosen to be as close as possible from the current practice in documenting Faust libraries. Here is the actual documentation of the zita_rev_fdn in effect.lib:

//------------------------------- zita_rev_fdn -------------------------------
// Internal 8x8 late-reverberation FDN used in the FOSS Linux reverb zita-rev1
// by Fons Adriaensen <fons@linuxaudio.org>.  This is an FDN reverb with
// allpass comb filters in each feedback delay in addition to the
// damping filters.
//
// USAGE:
//   bus(8) : zita_rev_fdn(f1,f2,t60dc,t60m,fsmax) : bus(8)
//
// WHERE
//   f1    = crossover frequency (Hz) separating dc and midrange frequencies
//   f2    = frequency (Hz) above f1 where T60 = t60m/2 (see below)
//   t60dc = desired decay time (t60) at frequency 0 (sec)
//   t60m  = desired decay time (t60) at midrange frequencies (sec)
//   fsmax = maximum sampling rate to be used (Hz)
//
// REFERENCES:
//   http://www.kokkinizita.net/linuxaudio/zita-rev1-doc/quickguide.html
//   https://ccrma.stanford.edu/~jos/pasp/Zita_Rev1.html
//
// DEPENDENCIES:
//   filter.lib (allpass_comb, lowpass, smooth)
//   math.lib (hadamard, take, etc.)

And here is my editing to add some markdown formatting :

//------------------------------- zita_rev_fdn -----------------------------
// Internal 8x8 late-reverberation FDN used in the FOSS Linux reverb zita-rev1
// by Fons Adriaensen <fons@linuxaudio.org>.  This is an FDN reverb with
// allpass comb filters in each feedback delay in addition to the
// damping filters.
//
// ### USAGE:
//   `bus(8) : zita_rev_fdn(f1,f2,t60dc,t60m,fsmax) : bus(8)`
//
// #### WHERE
// + f1    = crossover frequency (Hz) separating dc and midrange frequencies
// + f2    = frequency (Hz) above f1 where T60 = t60m/2 (see below)
// + t60dc = desired decay time (t60) at frequency 0 (sec)
// + t60m  = desired decay time (t60) at midrange frequencies (sec)
// + fsmax = maximum sampling rate to be used (Hz)
//
// ### REFERENCES:
//   <http://www.kokkinizita.net/linuxaudio/zita-rev1-doc/quickguide.html>
//   <https://ccrma.stanford.edu/~jos/pasp/Zita_Rev1.html>
//
// ### DEPENDENCIES:
// + filter.lib (allpass_comb, lowpass, smooth)
// + math.lib (hadamard, take, etc.)
//--------------------------------------------------------------------------

The translation produced by faust2md is the following :

---
file: t2.txt
date: 2015-08-06
---

# zita_rev_fdn
Internal 8x8 late-reverberation FDN used in the FOSS Linux reverb zita-rev1
by Fons Adriaensen <fons@linuxaudio.org>.  This is an FDN reverb with
allpass comb filters in each feedback delay in addition to the
damping filters.

### USAGE:
  `bus(8) : zita_rev_fdn(f1,f2,t60dc,t60m,fsmax) : bus(8)`

#### WHERE
+ f1    = crossover frequency (Hz) separating dc and midrange frequencies
+ f2    = frequency (Hz) above f1 where T60 = t60m/2 (see below)
+ t60dc = desired decay time (t60) at frequency 0 (sec)
+ t60m  = desired decay time (t60) at midrange frequencies (sec)
+ fsmax = maximum sampling rate to be used (Hz)

### REFERENCES:
  <http://www.kokkinizita.net/linuxaudio/zita-rev1-doc/quickguide.html>
  <https://ccrma.stanford.edu/~jos/pasp/Zita_Rev1.html>

### DEPENDENCIES:
+ filter.lib (allpass_comb, lowpass, smooth)
+ math.lib (hadamard, take, etc.)

To conclude, here is the formatted result:

zita_rev_fdn

Internal 8x8 late-reverberation FDN used in the FOSS Linux reverb zita-rev1 by Fons Adriaensen fons@linuxaudio.org. This is an FDN reverb with allpass comb filters in each feedback delay in addition to the damping filters.

USAGE:

bus(8) : zita_rev_fdn(f1,f2,t60dc,t60m,fsmax) : bus(8)

WHERE

  • f1 = crossover frequency (Hz) separating dc and midrange frequencies
  • f2 = frequency (Hz) above f1 where T60 = t60m/2 (see below)
  • t60dc = desired decay time (t60) at frequency 0 (sec)
  • t60m = desired decay time (t60) at midrange frequencies (sec)
  • fsmax = maximum sampling rate to be used (Hz)

REFERENCES:

http://www.kokkinizita.net/linuxaudio/zita-rev1-doc/quickguide.html https://ccrma.stanford.edu/~jos/pasp/Zita_Rev1.html

DEPENDENCIES:

  • filter.lib (allpass_comb, lowpass, smooth)
  • math.lib (hadamard, take, etc.)