Create Help Summary Files - Contents.m

Create Help Summary Files — `Contents.m`

What Is a `Contents.m` File?

A Contents.m file provides a summary of the programs in a particular folder. The help and doc functions refer to Contents.m files to display information about folders.

Contents.m files contain only comment lines. The first two lines are headers that describe the folder. Subsequent lines list the program files in the folder, along with their descriptions. Optionally, you can group files and include category descriptions. For example, view the functions available in the codetools folder:

help codetools

  Commands for creating and debugging code
  MATLAB Version 9.14 (R2023a) 19-Nov-2022 
 
  Editing and publishing
    edit                   - Edit or create a file
    grabcode               - Copy MATLAB code from published HTML
    checkcode              - Check files for possible problems
    publish                - Publish file containing cells to output file
    snapnow                - Force snapshot of image for published document
  
  Directory tools
    visdiff                - Compare two files (text, MAT, or binary) or folders

   ...

If no Contents.m file exists in a folder, the help and doc functions display a generated list of all program files in the folder. For example, the folder myfiles contains five program files and no Contents.m file. When you call the help function on the folder, it displays the list of program files in the folder and a brief description for each one.

help myfiles

Contents of myfiles:

    estimatePanelOutput - Calculate Solar Time
           lengthofline - Calculates the length of a line object
        solarCorrection - The function solarCorrection calculates the difference between local and
SolarPanelEstimatorForm - is a live script.
       WeatherDashboard - is a live script.

If you do not want the help and doc functions to display the generated list, place an empty Contents.m file in the folder. If a folder contains an empty Contents.m file, the help and doc functions display foldername is a folder. If there is another folder with the same name, the help and doc functions display the information for that folder instead.

Create a `Contents.m` File

To customize what the help and doc functions display for a folder, create a customized Contents.m file.

In the folder that contains your program files, create a file named Contents.m.

Copy this template into the Contents.m file.

% Folder summary
% Version xxx dd-mmm-yyyy 
%
% Description of first group of files
%   file1                   - file1 description
%   file2                   - file2 description
% 
% Description of second group of files
%   file3                   - file3 description
%   file4                   - file4 description

Modify the template to match the contents of your folder. When modifying the template, do not include any spaces in the date field in the second comment line.

For example, this Contents.m file describes the contents of the myfiles folder.

% Folder containing my program files
% Version 1.2.0 09-Nov-2022 
%
% My Functions
%   estimatePanelOutput            - Calculate solar time
%   lengthofline                   - Calculate the length of a line object
%   solarCorrection                - Calculate the difference between local and solar time
% 
% My Live Scripts
%   SolarPanelEstimatorForm        - Estimate solar panel output
%   WeatherDashboard               - Display weather data for Natick, MA

Optionally, you can include See also links in the Contents.m file. To include See also links, add a line at the end of the file that begins with % See also followed by a list of function names. If the functions exist on the search path or in the current folder, the help and doc functions display each of these function names as a hyperlink to its help. Otherwise, the help and doc functions print the function names as they appear in the Contents.m file.
For example, this code adds See also links to the files myfile1.m and myfile2.m, which are on the path.
```
% 
% See also MYFILE1, MYFILE2
```
You also can include hyperlinks (in the form of URLs) to websites in your help text. Create hyperlinks by including an HTML <a></a> anchor element. Within the anchor, use a matlab: statement to execute a web command.
For example, this code adds a hyperlink to the MathWorks website.
```
% For more information, see the <a href="matlab: 
% web('https://www.mathworks.com')">MathWorks website</a>.
```

Once you have created your Contents.m file, use the help and doc functions to display the contents of your folder. For example, display the contents of the myfiles folder.

help myfiles

  Folder containing my program files
  Version 1.2.0 09-Nov-2022 
 
  My Functions
    estimatePanelOutput            - Calculate solar time
    lengthofline                   - Calculate the length of a line object
    solarCorrection                - Calculate the difference between local and solar time
  
  My Live Scripts
    SolarPanelEstimatorForm        - Estimate solar panel output
    WeatherDashboard               - Display weather data for Natick, MA

  See also myfile1, myfile2

  For more information, see the MathWorks website.