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](
https://en.wikipedia.org/wiki/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 <f...@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 <f...@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 <f...@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 <f...@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.)
Cheers
Yann
------------------------------------------------------------------------------
_______________________________________________
Faudiostream-devel mailing list
Faudiostream-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/faudiostream-devel
