Generating Documentation
- Luis Casarrubias
In addition to generating source and header files, Audio Weaver also generates documentation for modules and subsystems in Microsoft Word format. The generated documentation is shown as item 5 in Overall Development Environment. The information in the documentation is pulled from several different places:
● The help comments at the start of the MATLAB M-file. [manual]
● Inserted code markers. [manual]
● Variable and module information. [automatic]
● Input, output, and scratch pins. [automatic]
● Subsystem drawings. [automatic]
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
awe_help scaler_smoothed_example_module
at the MATLAB command line. The documentation appears (shown in the figure below).
Behind the scenes, MATLAB checks if documentation already exists for the module. Since the scaler_smoothed_example_module.m function exists in the directory
<Audio Weaver>\AWEmodules\Source\Examples
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)
Generates help documentation for an audio module in a specified format. Arguments:
M — @awe_module object.
FILENAME — file in which to store the resulting Word document in. This needs to have a .doc extension.
The audio module must already have been through the code generation process and have suitable code markers added.
If M is a cell array containing modules, then the function generates documentation for the entire library. By default, modules appear in the documentation in the same order as in the cell array M. An optional third argument, SORT, allows you to specify that the modules should be sorted by their classNames.
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
AWE_INFO.docControl.format='html';
and documentation is displayed as HTML. Switching to
AWE_INFO.docControl.format='doc';
causes the documentation to be displayed in Microsoft Word format. In both cases, Microsoft Word is used to generate the underlying document and the ‘.format’ variable controls which format the document is saved in. Generating documentation requires that you have Microsoft Word installed.
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:
● A brief summary of the module.
● The purpose of each argument to the M-file and its default value.
The module field .docInfo.discussion (or a code marker named 'discussion') contains the text which is inserted under the "Discussion" section of the documentation. The discussion should contain:
● A lengthy description of how the module operates.
● Whether the module has a fixed or variable number of pins.
● 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.