Helping your help
MATLAB files that are a part of the public API of MATLAB all have nice help comments in them. The files we ship with MATLAB follow a standard format: function line, summary/description line (commonly referred to as the H1 line), description of what the function does along with examples describing the inputs and outputs, and then finally a list of related functions followed by a copyright. In order to make sure that our files have these help parts, we developed a program to analyze all the files in a folder and report on their help completeness. For many years this report has been available for your use as well, in the form of the Help Report in the Folder Reports.
You can obtain the Help Report for a folder through the Current Folder Browser Action button under the Reports sub-menu:
After choosing the “Help Report” item, the MATLAB Web Browser will open with a table that lists each MATLAB file in the current folder and reports the existence of the help parts for them. If an item is present, it will be shown on the right column of the table. Some of the items (such as “See Also” and “Copyright”) have line number links that will open the file to that section of its help.
Here is an example entry of a script with no help comments. Highlighted in pink are all the missing items: description line (H1), help body, examples, see also, and copyright:
For files that do have help comments, you might see an entry more like the following. This file has a help block and a “see also”, but does not have copyrights or examples:
If you don’t care about copyrights, examples, or only care about help on class methods, you can control which parts appear in the report with the checkboxes at the top of the page:
If you have any great stories about the help comments of your functions, let us know!
To leave a comment, please click here to sign in to your MathWorks Account or create a new one.