One of MATLAB's strengths is how easy it is to document a custom function/class. The first continuous comment block is automatially displayed by the help and doc functions, with some neat automatic formatting. For example:
% myFunc My example function
%
% This function does not do anything yet, but one day will be great. For
% example, you will be able to type:
% out=myFunc(in1,in2);
% and something cool will happen.
%
% See also otherFunc
function varargout=myFunc(varargin)
% actual code
end
will have a link to the documentation for "otherFunc", assuming that file exists. Class documentation is nicely broken up into a header (with "See also" support) followed by a property and method summary.
All the above works great with one big exception: apart from highlighting uses of the file's name, there is no way to display anything but pure text. No Markdown, no LateX, and so forth. It is possible to sneak an HTML link into the comment block, calling a MATLAB command that can display a live script with fancy formatting. I have done this in the past, although it can be a little tricky for files inside a package/namespace (folders beginning with '+').
I can envision a system where fancy documentation would be buried inside an "example" subfolder where "myFunc.m" is located. Invoking "showExample myFunc", where "showExample" is a to-be-written utility, would look for a live script inside the appropriate subfolder, make a local copy for the user to tinker with, and then display that local copy in the MATLAB editor. Since the actual function function and its example woulld obviously inside a Git repository, text-based live scripts would be used instead of an *.mlx file.
Again, this all works fine on its fine on its own, but it would be very difficult to replicate the "See also" capability or the other features of the standard doc function. So what are we to do? Is there a clever way to add another block to a standard comment block "See examples" that would automatically detect scripts in a subfolder of function/class being queried?
I know there is a way to incorporate custom documentation into MATLAB help system. This is much too cumbersome for my purposes, where many functions/classes are being added/edited all the time. The existing doc system covers maybe 80% of my needs, but sometimes a little math (LaTeX) would go a long way on explaining how things work.
9 Comments
Time Descending
Some formatting such as bold and hyperlinks are supported in the help text of an m-file.
@Adam Danz Yes, that is a wonderful aspect of MATLAB's help/doc system. The problem is that you lose those features switching over to a live document, which is the only way to get equations or formatted text. So I find myself trapped: do I stick with the traditional route (comment block with minimal format control) or switch over to live functions (no class support or automatic hyperlinks)?
Another approach would be to create my own documentation function, say "superdoc" that looks for live scripts inside a doc subfolder of the target function/class/method. If such a script is found, it could either be published for the user to look at or opened (as a local copy) in the MATLAB editor. When no such script is found, it would invoke the standard doc function. Namespaces can be a little tricky, particularly if an existing hierarcy (myTool.myFunc) gets buried inside another one (yourTool.myTool.myFunc). Loaded script files also lack automatic hyperlinks provided by the "See also" block.
It would be incredibly handy if the MATLAB's doc command could automatically hyperlink to scripts in a local subdirectory, much like the "See also" block. There are a lot of underdocumented features to this process. In addition to bold fonts and hyperlinks, it recognizes and separates "Note" as a section after "See also".
Try Live Functions: https://www.mathworks.com/help/matlab/matlab_prog/create-live-functions.html
Starting in R2025a, the Live Editor supports a new plain text Live Code file format (.m). Live Functions saved as plain text Live Code supports git (they are plain text) and have all advantages of classic Live Functions (.mlx).
Jan,
I can see how might help in some situations, but it does not really address my use case. For one thing, classes cannot be created in live documents--the editor really freaks out about this and will keep generating error dialogs to let you know this is forbidden. It is entirely possible to keep a live script/file tucked away within a class file, given some helper function to access that fancy documentation. I have done this in the past, though it can be incredibly tedious if the namespace changes.
Another problem with live functions is that they are not automatically linked with adjacent files. The "See also" feature does not work inside a live document--you have to manually link files. This gets old very fast.
There is also a philosophical problem with having documentation load within the MATLAB editor: users can make changes. Sure, one can be clever about created a local copy for the end user to play with, but it's a lot of heavy lifting to reimplement the entire documentation scheme of a large project just so you can display an equation from time to time.
Dan
I'm sorry, I missed that you need solution working with classes too. As you said, classes are not supported by Live Editor. However, you can have methods in separate files and I believe, these separate files can be Live Functions. File with classdef block would be "classic" MATLAB Code file and methods in the same folder would be Live Code files.
I'm not sure if I understand correctly to this: "There is also a philosophical problem with having documentation load within the MATLAB editor: users can make changes."
You can call "doc" command on Live Function the same way as on classical function. So, documentation doesn't load within th MATLAB editor.
@Jan Studnicka I strive to maintain strict separation between the end user can see and what damage they might do to a code library. The doc function transfers that first comment block into separate window with no edit capability. There is a hyperlink in the top right corner to "View code for *.m", but that requires at least a second action before users can make changes. If I am going to show a live document to the end user, I make sure to make a local copy so that they can't mess up the library version.
I did not realize that doc preserved the format of the initial text block in a live function. This seems like a step in the right direction, although the automatical hyperlinking of "See also" does not work (yet?) and manual hyperlinks don't function correctly outside of the editor. It does not appear that users can access the code directly from documentation generated this way; this is a mixed blessing.
Class support obviously still needs some work. I will have to test your method suggestion--I usually keep these as separate files as much as possible. It may be a little weird for the class documentation and the method documentation to look so very different.
To be frank, I see live documents as a bit of a toy. They are fine for little snippets of code, but I prefer the standard editor for longer files. Honestly, live documents remind me too much of Mathematica cells, which I loathed as a student so many years ago...
More info about the new plain text Live Code file format can be found here: https://www.mathworks.com/help/matlab/matlab_prog/plain-text-file-format-for-live-scripts.html
Sign in to participate
