Results for
MATLAB interprets the first block of uninterupted comments in a function file as documentation. Consider a simple example.
% myfunc This is my function
%
% See also sin
function z = myfunc(x, y)
z = x + y;
end
Those comments are printed in the command window with "help myfunc" and displayed in a separate window with "doc myfunc". A lot of useful things happen behind the scenes as well.
- Hyperlinks are automatically added for valid file names after "See also".
- When dealing with classes, the doc command automatically appends the comment block with a lists of properties and methods.
All this is very handy and as been around for quite some time. However, the doc browser isn't great (forward/back feature was removed several versons ago), the text formatting isn't great, and there is no way to display math.
Although pretty text/math can be displayed in a live document, the traditional *.mlx file format does not always play nice with Git and I have avoided them. However, live documents can now (since 2025a?) be saved in a pure text format, so I began to wonder if all functions should be written in this style. Turns out that all you have to do is append these lines:
%[appendix]{"version":"1.0"}
%---
to the end of any function file to make it a live function. Doing so changes how MATLAB manages that first comment block. The help command seems to be unaffacted, although [text] may appear at the start of each comment line (depending on if the file was create as a live function or subsequently converted). The doc command behaves very different: instead of bringing up the traditional window for custom documentation, the comment block looks like it gets published to HTML and looks more similar to standard MATLAB help. This is a win in some ways, but the "See also" capabilitity is lost.
Curiously, the same text can be appended to the end of a class definition file with some affect. It does not change how the file shows up in the editor, but as in live functions, comments are published when using the doc command. So we are partway to something like a "live class", but not quite.
Should one stick with traditional *.m files or make everything live? Neither does a great job for functions/classes in a namespace--references must explicitly know absolute location in traditional functions, and there is no "See also" concept in a live function. Do we need a command, like cdoc (custom documentation), that pulls out the comment block, publishing formatted text to HTML while simultaneously resolving "See also" references as hyperlinks? If so, it would be great if there were other special commands like "See examples" that would automatically copy and then open an example script for the end user.
Have you ever learned that something you were doing manually in MATLAB was already possible using a built-in feature? Have you ever written a function only to later realize (or be told) that a built-in function already did what you needed?
Two such moments come to mind for me.
1. Did you realize that you can set conditional breakpoints? Neither did I, until someone showed me that feature. To do that, open or create a file in the editor, right click on a line number for any line that contains code, and select Set Conditional Breakpoint... This will bring up a dialog wherein you can type any logical condition for which execution should be paused. Before I learned about this, I would manually insert if-statements during debugging. Then, after fixing each bug, I would have to delete those statements. This built-in feature is so much better.
2. Have you ever needed to plot horizontal or vertical lines in a plot? For the longest time, I would manually code such lines. Then, I learned about xline() and yline(). Not only is less code required, these lines automatically span the entire axes while zooming, panning, or adjusting axis limits!
Share your own Aha! moments below. This will help everyone learn about MATLAB functionality that may not be obvious or front and center.
(Note: While File Exchange contains many great contributions, the intent of this thread is to focus on built-in MATLAB functionality.)
