To live and let doc
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.
