Reasons for undocumented Matlab aspects

Why are there so many undocumented aspects in Matlab?
This is a great question, recently asked by a reader of this blog, and I wanted to expand on it in today’s article.

Unofficial explanations

There appear to be several different reasons for Matlab’s undocumented/unsupported features, whose types I categorized in last week’s article. Note that the following are all my personal interpretation and are not officially sanctioned in any manner:

• Pre-release (beta mode)
  MathWorks takes pride in only releasing features/functions for mass use after extensive quality testing. Some features/functions are simply not at the requested level for public use under this criterion. For example, they may work only in a certain situation and not another; may not have bullet-proof error handling etc.
• Internal use within Matlab
  These are functions or properties which are used by other (documented) Matlab functions, but deemed unsuitable for mass use for similar reasons, or because TMW did not believe they might be of any practical use to users.
• Grandfathered (deprecated)
  Some features and functions are replaced with newer versions in newer Matlab versions. The old features/functions are often preserved for the sake of backward compatibility, for one or more such future Matlab versions.
• Mis-documentation / documentation error / oversight
  Matlab is an extensively documented product, and as in any such technical documentation of a rapidly-evolving product, documentation errors are bound to appear. Unfortunately, Matlab users rely on this documentation in order to use Matlab, so any mis- or un-documentation directly affects usage.
• Java
  This is perhaps the largest source of undocumented features within Matlab. For a variety of reasons, the Matlab-Java interface has not been documented to the same extent as the interface with other programming languages like Fortran or C/C++. Matlab itself is based on Java to a large extent, and perhaps TMW does not feel comfortable with users playing around with Matlab internals. Or perhaps TMW is afraid that improper use of the EDT (discussed later in this book) would result in system hangs or crashes and/or an overall bad user experience.
• Mex
  Mex is the Matlab interface to pre-compiled external functions, typically coded in C/C++. Mex functions have access to important Matlab engine functionality, but many of these functionalities are undocumented.

Official explanations

Here is an important CSSM thread snippet about the official reasons, with a rare addendum from Cleve Moler – Matlab’s inventor and TMW founder & chairman. It is over a decade old, yet still just as relevant today as it was back then:

There are parts of MATLAB that we *don’t* want users to use. This includes new functionality that’s not yet completely implemented, experimental code, and code that we know will change in the future.
The functionality that we don’t document is not ready for use and *shouldn’t* be used unless its users are aware of its experimental nature. These undocumented functions/options are ones whose behavior is likely to change between versions. Future uses of it may be either invalid or produce completely different results, even between minor revisions of MATLAB. These functions are essentially “developmentally unstable;” they are not fit for use by anyone who needs a reliable development environment.
We have absolutely no plans to document these under-development areas of MATLAB until we feel they are ready for general use. Until then, we only share these features to our test audience and interested parties on CSSM. Both of these groups consist of our most dedicated MATLAB users who give excellent feedback concerning their use. But it would be irresponsible of us to document these features to the general MATLAB public when we know their use and implementation may change dramatically in the short term, making the development environment unstable. We don’t want to mislead you into using features we know not to be properly implemented.
This situation is not unique to The MathWorks. What is unique to us, however, is our honesty in letting you know these features are there. If you are in a situation where you may need to use a yet unsupported feature and we feel that it’s appropriate for us to do so, we’ll let you know that it exists. We have no intention of trying to make you look foolish; pointing out these hidden functions is meant to be helpful. We could adopt the policies taken by other software companies and simply not reveal any of these features in a public forum such as this one. However, we feel that would be counterproductive to our intentions. So instead we document the features we support, and are very willing to discuss with you unsupported and experimental features that we feel may be useful to you in your work. But we won’t document functionality whose use we aren’t sure about supporting.
We also have a responsibility to our customers to make sure that MATLAB is a stable development environment that can be used consistently from version to version. It’s difficult enough for us to advance the functionality of the code that we do support while still remaining backwards compatible with code written 10-15 years ago (check comments made in a few earlier threads). The last thing we’d want is for the general population of MATLAB users to rely on code that we don’t intend to fully support even in the near future. These undocumented features/ functions/etc fall into that category.
Naturally, this isn’t the only stance we could take. We could document everything or just not even include these features in released versions. But we’ve chosen to provide them to individuals on a case-by-case basis as we see fit; this seems to be most in line with our goals. You may not agree that this is the best choice, but it’s the one we’ve currently taken. Naturally, this could change in the future.
…
— Nabeel
 
It’s not so much the time to do complete documention. Rather, it’s the committment to continued support of a particular feature. We have things in MATLAB that are experimental, unfinished or incomplete. They may be good ideas, but they may not. If we fully advertise and document them, then we feel strongly obligated to support them, and to keep them in MATLAB forever.
— Cleve Moler

 
A not unsimilar explanation was provided by Doug Hull in a comment on one of Matlab’s official blogs:

UITable was undocumented, but available, for some releases in the past.
Some features like this are available, but undocumented, for various reasons. Sometimes they are there so that we can use them in making tools for MATLAB. These features are undocumented because we need the flexibility to change the interface for a while. If you find undocumented features, you need to be aware that the interface can change or be removed in future releases.
-Doug

---

Note: For all the people who have noted about cprintf‘s issues with R2011b, a new version was uploaded on Monday (November 28), that fixes those problems, as well as the issue of the space (on R2011b only). In R2011b, colored text can now be placed immediately adjacent to each other, without the technical need for an intervening space character. Unfortunately, this relies on a fix that MathWorks made to the Command Window in R2011b, and which is not available in R2011a and earlier. cprintf automatically checks the Matlab release version and adds a space if necessary.
While I was at it, I also updated the findjobj utility (a few bug fixes).

---

<pre lang="matlab">
a = magic(3);
disp(sum(a))
</pre>