In my last post, I described how to create and display the Contents.m for a folder. I admit to having an agenda with that post. The Contents.m is one technique MathWorks toolbox authors (such as yours truly) use to differentiate functions that are meant to be used publicly, from helper functions that the toolbox author didn’t intend to expose.

If you take a look at the Contents.m in toolbox/matlab/graph2d:

edit(fullfile(matlabroot,'toolbox','matlab','graph2d','Contents.m'))

you might see one contiguous paragraph of comments at the top, followed by a blank line, followed by more comments. When there is a break in comment lines, anything below that break will be excluded by the help command.

help graph2d

In a toolbox Contents.m file, the toolbox helper files and copyright statement will usually be below the break in comment lines, and the main functions (the ones that show up in the Function Browser and Documentation) will be above that break.

The reason why I’m pointing out these “listed but unlisted” files is that I don’t want you to rely on these functions. They are there for you to look at and study; they are a good place to go if you want to get your brown belt in MATLAB hacking. The caveat when using helper functions is they are subject to change without notice, which is why you should not build code that relies on them.

For a function listed in the documentation, function browser, on the web site, or at the top of Contents.m, we have a very strict procedure for deleting or changing how it works. Changes take several releases and involve creating documentation and warnings, possibly even M-Lint messages. For the functions we don’t advertise, including the ones listed in the bottom portion of a Contents.m, we reserve the right to change without notice or with a less precise process. This doesn’t mean that we will do so willy-nilly, but it could happen.

In fact, I’m in the process now of refactoring some old code to improve quality and increase functionality in the codetools folder of the MATLAB toolbox. As part of this process, I’m going to delete some of the helper functions listed below the comment break in the Contents.m. And some of the remaining helper files I can guarantee will change again in the next release as I’m rolling out my changes over several releases. As far as I can tell from online search and calls to tech support, these files aren’t being used out in the wild, but I’d hate for your code to stop working without warning… So I guess this your warning.

If when you upgrade and have a problem continuing to use an undocumented function, give us a shout here on the blog or email tech support, and we’ll give you a good-faith effort to come up with a workaround, but I make no guarantees: especially with desktop code.

Finally, just for fun and to keep this post from being all text, a gratuitous MATLAB figure brought to you by the xpbombs demo: