Contributing - Faust Libraries

# Contributing

If you wish to add a function to any of these libraries or if you plan to add a new library, make sure that you follow the following conventions:

## New Functions

- All functions must be preceded by a markdown documentation header respecting the following format (open the source code of any of the libraries for an example):

    //-----------------functionName--------------------
    // Description
    //
    // #### Usage
    //
    // ```
    // Usage Example
    // ```
    //
    // Where:
    //
    // * argument1: argument 1 description
    //-------------------------------------------------

- Every time a new function is added, the documentation should be updated simply by running `make doclib`.
- The environment system (e.g. `os.osc`) should be used when calling a function declared in another library (see the section on Using the Faust Libraries).
- Try to reuse existing functions as much as possible.
- If you have any question, send an e-mail to rmichon_at_ccrma_dot_stanford_dot_edu.

## New Libraries

- Any new "standard" library should be declared in `stdfaust.lib` with its own environment (2 letters - see `stdfaust.lib`).
- Any new "standard" library must be added to `generateDoc`.
- Functions must be organized by sections.
- Any new library should at least `declare` a `name` and a `version`.
- The comment based markdown documentation of each library must respect the following format (open the source code of any of the libraries for an example):

    //############### libraryName ##################
    // Description
    //
    // * Section Name 1
    // * Section Name 2
    // * ...
    //
    // It should be used using the `[...]` environment:
    //
    // ```
    // [...] = library("libraryName");
    // process = [...].functionCall;
    // ```
    //
    // Another option is to import `stdfaust.lib` which already contains the `[...]`
    // environment:
    //
    // ```
    // import("stdfaust.lib");
    // process = [...].functionCall;
    // ```
    //##############################################

    //================= Section Name ===============
    // Description
    //==============================================

- If you have any question, send an e-mail to rmichon_at_ccrma_dot_stanford_dot_edu.

## Coding Conventions

In order to have a uniformized library system, we established the following conventions (that hopefully will be followed by others when making modifications to them :-) ).

### Documentation

- All the functions that we want to be "public" are documented.
- We used the `faust2md` "standards" for each library: `//###` for main title (library name - equivalent to `#` in markdown), `//===` for section declarations (equivalent to `##` in markdown) and `//---` for function declarations (equivalent to `####` in markdown - see `basics.lib` for an example).
- Sections in function documentation should be declared as `####` markdown title.
- Each function documentation provides a "Usage" section (see `basics.lib`).

### Library Import

To prevent cross-references between libraries we generalized the use of the `library("")` system for function calls in all the libraries. This means that everytime a function declared in another library is called, the environment corresponding to this library needs to be called too. To make things easier, a `stdfaust.lib` library was created and is imported by all the libraries:

    an = library("analyzers.lib");
    ba = library("basics.lib");
    co = library("compressors.lib");
    de = library("delays.lib");
    dm = library("demos.lib");
    dx = library("dx7.lib");
    en = library("envelopes.lib");
    fi = library("filters.lib");
    ho = library("hoa.lib");
    it = library("interpolators.lib");
    ma = library("maths.lib");
    mi = library("mi.lib");
    ef = library("misceffects.lib");
    os = library("oscillators.lib");
    no = library("noises.lib");
    pf = library("phaflangers.lib");
    pm = library("physmodels.lib");
    rm = library("reducemaps.lib");
    re = library("reverbs.lib");
    ro = library("routes.lib");
    sp = library("spats.lib");
    si = library("signals.lib");
    so = library("soundfiles.lib");
    sy = library("synths.lib");
    ve = library("vaeffects.lib");
    wa = library("webaudio.lib");
    vl = library("version.lib");
    wd = library("wavedigitalfilters.lib");

For example, if we wanted to use the `smooth` function which is now declared in `signals.lib`, we would do the following:

    import("stdfaust.lib");

    process = si.smooth(0.999);

This standard is only used within the libraries: nothing prevents coders to still import `signals.lib` directly and call `smooth` without `ro.`, etc. It means symbols and function names defined within a library have to be unique to not collide with symbols of any other libraries.

### "Demo" Functions

"Demo" functions are placed in `demos.lib` and have a built-in user interface (UI). Their name ends with the `_demo` suffix. Each of these function have a `.dsp` file associated to them in the `/examples` folder.

Any function containing UI elements should be placed in this library and respect these standards.

### "Standard" Functions

"Standard" functions are here to simplify the life of new (or not so new) Faust coders. They are declared in `/libraries/doc/standardFunctions.md` and allow to point programmers to preferred functions to carry out a specific task. For example, there are many different types of lowpass filters declared in `filters.lib` and only one of them is considered to be standard, etc.

#### Search

From here you can search these documents. Enter your search terms below.

#### Keyboard Shortcuts

Keys | Action
--- | ---
`?` | Open this help
`n` | Next page
`p` | Previous page
`s` | Search