| MATLAB® | |
| On this page… |
|---|
See also another Directory Report, M-Lint Code Check Report, and the File Comparisons tool.
Directory reports help you refine the M-files in a directory and improve their performance. They are also useful for when you prepare files for use by others, such as for a finished project, to share on MATLAB Central, or for a toolbox to be distributed.
Access directory reports from the MATLAB® Current Directory browser, as follows:
Select Desktop > Current Directory.
For more information, see Current Directory Browser.
Navigate to the directory containing the M-files for which you want to produce reports. Then, in the Current Directory browser toolbar, click the down arrow button and select the type of report you want to run for all the M-files in the current directory.
The report you selected appears as an HTML document in the MATLAB Web Browser:
In a report, click a file name to open that file in the Editor, where you can view it or make changes to it. Click a line number to open the file at that line.
To update a report after making changes to the report options, or after changing any files in the directory, click Rerun This Report. Note that this reruns the report for the directory shown in the report, not for the MATLAB current directory.
While a report is displayed, you can change the MATLAB current directory and then click Run Report on Current Directory to generate the same type of report for the new current directory.
When you run a report, it replaces the report currently
displayed. Use the Back
and Forward
buttons in the toolbar to see a previously
run report and then return to the most recent. If the toolbar is not
visible, select Desktop >
Web Browser Toolbar.
You cannot run directory reports when the path is a UNC (Universal Naming Convention) path, that is, starts with \\. Instead, use an actual hard drive on your system, or a mapped network drive.
The TODO/FIXME Report shows M-files that contain text strings you included as notes to yourself, such as TODO. Use this report to easily identify M-files that still require work or some other actions.
To access this report, follow the instructions in Accessing and Using Directory Reports.
In the report, select one or more check boxes to display lines containing the specified strings (TODO and FIXME), and click Rerun This Report. You can also select the check box for the text field and enter any text string in the field, such as NOTE or TBD to identify lines containing that string.
The Help Report presents a summary view of the help component of your M-files. In MATLAB, the M-file help component is all contiguous nonexecutable lines (comment lines and blank lines), starting with the second line of a function M-file or the first line of a script M-file. For more information about creating help for your own M-files, see the reference page for the help function.
To access this report, follow the instructions in Accessing and Using Directory Reports.
Select one or more check boxes to display the specified help information and click Rerun This Report.
Use this information to help you identify files of interest or files that lack help information. It is a good practice to provide help for your files not only to help you recall their purpose, but to help others who might use the files.
With Show subfunctions selected, the Help Report displays help information for all subfunctions called by each function. Help information for subfunctions is highlighted in gray.
With Description selected, the Help Report displays the first line of help in the M-file. If the first comment line is empty, or if there is not a comment before the executable code, No description line, highlighted in pink, appears instead.
With Examples selected, the Help Report displays the line number where the examples section of the M-file help begins. The Help Report looks for a line in the M-file help that begins with the string example or Example and displays any subsequent nonblank comment lines. Select this option to easily locate and go to examples in your M-files.
It is a good practice to include examples in the help for your M-files. If you do not have examples in the help for all your M-files, use this option to identify those without examples. If the report does not find examples in the M-file help, No example, highlighted in pink, appears.
With Show all help selected, the Help Report displays complete M-file help, which is all contiguous nonexecutable lines (comment lines and blank lines), starting with the second line of a function M-file, or the first line of a script M-file. The M-file help shown also includes overloaded functions and methods, which are not actually part of the M-file help comments, but are automatically generated when help runs.
If the comment lines before the executable code are empty, or if there are no comments before the executable code, No help, highlighted in pink, appears instead.
With See Also selected, the Help Report displays the line number for the see also line in the M-file help. The see also line in M-file help lists related functions. When the MATLAB Command Window displays the help for an M-file, any function name listed on the see also line appears as a link you can click to display its help. It is a good practice to include a see also line in the help for your M-files.
The report looks for a line in the M-file help that begins with the string See also. If the report does not find a see also line in the M-file help, No see-also line, highlighted in pink, appears. This helps you identify those M-files without a see also line, should you want to include one in each M-file.
The report also indicates when an M-file noted in the see also line is not in a directory on the search path. You might want to move that file to a directory that is on the search path. If not, you will not be able to click the link to get help for the file, unless you then add its directory to the path or make its directory become the current directory.
With Copyright selected, the Help Report displays the line number for the copyright line in the M-file. The report looks for a comment line in the M-file that begins with the string Copyright and is followed by year1-year2 (with no spaces between the years and the hyphen that separates them). It also notes if the end of the date range is not the current year.
It is a good practice to include a copyright line in the help for your M-files, that notes the year you created the file and the current year. For example, for an M-file you created in 2001, include this line
% Copyright 2001-2006
If the report does not find a copyright line in the M-file help, No copyright line, highlighted in pink, appears. This helps you identify those files without a copyright line, should you want to include one in each M-file.
The Contents Report displays information about the integrity of the Contents.m file for the directory. A Contents.m file includes the file name and a brief description of each M-file in the directory. When you type help followed by the directory name, such as help mydemos, The MATLAB Command window displays the information contained within the mydemos/Contents.m file. For more information, see Providing Help for Your Program in the MATLAB Programming documentation.
To access this report, follow the instructions in Accessing and Using Directory Reports.
If there is no Contents.m file for the directory and you run the Contents Report, the report tells you the Contents.m file does not exist and asks if you want to create one. Click yes to automatically create the Contents.m file. Edit the Contents.m file in the Editor to include the names of files you plan to create, or to remove files that you do not want to expose when displaying help for the directory, such as files for internal use.
You need to update the Contents.m file to reflect changes you make to files in the directory. For example, when you remove a file from a directory, remove its entry from the Contents.m file. The Contents Report helps you to maintain the Contents.m file. It displays discrepancies between the Contents.m file and the M-files in the directory.
Use the links displayed for each line, or edit the Contents.m file directly, or edit the M-files to make the changes. To make all of the suggested changes at once, click fix all. To automatically align the file names and descriptions in the Contents.m file, click fix spacing.
If you always want the Contents.m file to reflect all files in the directory, you can automatically generate a new Contents.m file rather than changing the file based on the Contents Report. To do this, first delete the existing Contents.m file, run the Contents Report, and click yes when prompted for MATLAB to automatically create one.
No Contents File. This message appears if there is no Contents.m file in the directory. Click yes to automatically create a Contents.m file, which contains the file names and descriptions for all M-files in the directory.
No Contents.m file. Make one? [ yes ]
File Not Found. This message appears when a file included in Contents.m is not in the directory. These messages are highlighted in pink. For example, a message such as
File helloworld does not appear in this directory. Remove it from Contents.m? [ yes ]
means the Contents.m file includes an entry for helloworld, but that file is not in the directory. This might be because you removed the file helloworld, or you manually added it to Contents.m because you planned to create the file but have not as yet, or you renamed helloworld.
Description Lines Do Not Match. This message appears when the description line in the M-file help does not match the description provided for the M-file in Contents.m. These messages are highlighted in pink. Click yes to replace the description in the Contents.m file with the description from the M-file. Or select the option to replace the description line in the M-file help using the description for that file in Contents.m.
Description lines do not match for file logo5. Use this description from the file? (default) [ yes ] logo5 - This is the basic logo image for MATLAB V5 Or put this description from the Contents into the file? [ yes ] logo5 - This is the basic logo image for MATLAB
Files Not In Contents.m. This message appears when a file in the directory is not in Contents.m. These messages are highlighted in gray. Click yes to add the file name and its description line from the M-file help to the Contents.m file.
collatzall is in the directory but not Contents.m collatzall - Plot length of sequence for Collatz problem Add the line shown above? [ yes ]
The Dependency Report shows dependencies among M-files in a directory. This helps you determine all the M-files you need to provide when you tell someone to run a particular M-file. If you do not provide all the dependent M-files along with the M-file you want them to run, they will not be able run the file. The report does not list as dependencies the M-files in the toolbox/matlab directory because every MATLAB user already has those files.
To access this report, follow the instructions in Accessing and Using Directory Reports. You can also access the report from the Editor Tools menu.
Select Show child functions to see a list of all M-files (children) called by each M-file in the directory (parent). The report also indicates where each child function resides, for example, in a specified toolbox. If a child function's location is listed as unknown, it could be because the child function is not on the search path or in the current directory.
The Dependency Report is similar to running the depfun function, although the two do not provide the exact same results. For performance purposes, the Dependency Report limits the functions considered.
Select Show parent functions to list the M-files that call each M-file. The report limits the parent (calling) functions to those in the current directory. Select Show subfunctions to include subfunctions in the report. Subfunctions are listed directly after the main function and are highlighted in gray.
Run the Coverage Report after you run the Profiler to identify how much of a file ran when it was profiled. For example, when you have an if statement in your code, that section might not run during profiling, depending on conditions.
You can run the Coverage Report from the Profiler, or follow these steps:
In the MATLAB desktop, select Desktop > Profiler. Profile an M-file in the Profiler. For detailed instructions, see Profiling for Improving Performance.
In the Current Directory browser, select Coverage Report. The Coverage Report appears, providing a summary of coverage for the M-file you profiled.
Click the Coverage link to see the Profile Detail Report for the file.
| Tuning and Managing M-Files | M-Lint Code Check Report | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |