...

In the list above, "manual" indicates that the content is created by the module developer.  "automatic" indicates that the content is generated by Audio Weaver based on information in the module m-file.

awe_help

For example, to see the generated help for the scaler smoothed module, type

...

it checks if the file <Audio Weaver>\AWEModules\Source\Examples\Doc\ScalerSmoothedExample.html exists.  The name "ScalerSmoothedExample.html" is based on the module's class name.  If the file exists, it is opened and displayed in the MATLAB HTML browser.  If it doesn't exist, then the documentation is generated on the fly using Microsoft Word and then saved in HTML format.  The process of generating new documentation is quite involved and can take several seconds to complete.

awe_generate_doc.m

Using awe_generate_doc.m directly gives you more control over the final documentation including the ability to create a single document describing an entire module library.

...

awe_generate_doc(M, FILENAME, SORT)

Selecting the Documentation Format

The global variable AWE_INFO.docControl.format determines the format of the generated documentation.  By default, this is set to

...

Note that .docControl does not affect the HTML format used by awe_help.m.

Guidelines for Documenting Modules and Subsystems

The generated documentation relies upon two manually written sections as shown above.  We suggest that you use the following guidelines when documenting modules.  Within the help comments at the start of the M-file discuss:

...

●      Scratch pin requirements and how the sizes relate to the sizes of the input and output pins.  The automatically generated information lists out the scratch pin sizes, but the values shown are only based on the current module settings.  The relationship between the scratch sizes and other pin sizes is not described in the automatically generated text.

Hilbert Subsystem Example

We now walk through the automatically generated help for the hilbert_subsystem.m and describe where each of the items shown is taken from.

...

Adding Equations to Documentation

Audio Weaver supports adding equations to the discussion section of a module.  Equations are entered as text commands within the 'discussion' portion in LaTeX format.  Equations must be enclosed between dollar signs.  For example, $\angle(out1)-\angle(out2) = 90~degrees.$ is expanded to ∠(out1) - ∠(out2) = 90 degees in the document.  If you are new to LaTeX, there are many good references available online.