Create Help Summary Files

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, doc, and ver 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.3 (R2017b) 24-Jul-2017 
 
  Editing and publishing
    edit                   - Edit or create a file
    grabcode               - Copy MATLAB code from published HTML
    mlint                  - Check files for possible problems
    publish                - Publish file containing cells to output file
    snapnow                - Force snapshot of image for published document
  
  Directory tools
    mlintrpt               - Run mlint for file or folder, reporting results in browser
    visdiff                - Compare two files (text, MAT, or binary) or folders

   ...

If you do not want others to see a summary of your program files, place an empty Contents.m file in the folder. An empty Contents.m file causes help foldername to report No help found for foldername. Without a Contents.m file, the help and doc commands display a generated list of all program files in the folder.

Create a Contents.m File

When you have a set of existing program files in a folder, the easiest way to create a Contents.m file is to use the Contents Report. The primary purpose of the Contents Report is to check that an existing Contents.m file is up-to-date. However, it also checks whether Contents.m exists, and can generate a new file based on the contents of the folder. Follow these steps to create a file:

In the Current Folder browser, navigate to the folder that contains your program files.
Click , and then select Reports > Contents Report.
In the report, where prompted to make a Contents.m file, click yes. The new file includes the names of all program files in the folder, using the description line (the first nonempty comment line) whenever it is available.
Open the generated file in the Editor, and modify the file so that the second comment line is in this form:
```
     % Version xxx dd-mmm-yyyy
```
Do not include any spaces in the date. This comment line enables the ver function to detect the version information.

Note

MATLAB^® does not include live scripts or functions when creating a Contents Report.

Check an Existing Contents.m File

Verify whether your Contents.m file reflects the current contents of the folder using the Contents Report, as follows:

In the Current Folder browser, navigate to the folder that contains the Contents.m file.
Click , and then select Reports > Contents Report.

Note

You cannot run reports when the path is a UNC (Universal Naming Convention) path; that is, a path that starts with \\. Instead, use an actual hard drive on your system, or a mapped network drive.

The Contents Report performs the following checks.

Check Whether the Contents.m File...	Details
Exists	If there is no `Contents.m` file in the folder, you can create one from the report.
Includes all programs in the folder	Missing programs appear in gray highlights. You do not need to add programs that you do not want to expose to end users.
Incorrectly lists nonexistent files	Listed programs that are not in the folder appear in pink highlights.
Matches the program file descriptions	The report compares file descriptions in Contents.m with the first nonempty comment line in the corresponding file. Discrepancies appear in pink highlights. You can update either the program file or the `Contents.m` file.
Uses consistent spacing between file names and descriptions	Fix the alignment by clicking fix spacing at the top of the report.

You can make all the suggested changes by clicking fix all, or open the file in the Editor by clicking edit Contents.m.

Documentation