How do I use the help command to display multi-line comments?

Multi-line comments can be achieved using:

%{
 random foobars
%}

However, whenever I place this at the top of a new script and try to call the help command, the output keeps on resulting in just:

 {

Does this mean that the help command is limited to only single-line comments? I would assume that this was the case and call it a day but a textbook on MATLAB shows an example that prints out a multi-line comment using 'help'.

[Walter Roberson]

It is interpreting "random foobars" as a command, and so proceeding to foobar??

[Benjamin Wong]

All of the content between "%{" and "%{" is all green. For example:

%{

      conevol Computes volume of a cone.
      Creates variables radius and height.
      Result is assigned to variable volume and displayed.
      The script was written by Blaise Pascal
      on the year 1660

%}

All of that text would be displayed in green font to signify it being a comment so I don't think the problem is that.

[Walter Roberson]

Sigh. I feel so old some days, my culture lost in time, like tears in the rain.

Answer 1

[Abhinav Gurram]

The ability to add block comments to the help text of a function is not available in MATLAB.

MATLAB considers the group of consecutive lines immediately following the H1 line and those beginning with a % sign to be the online help text for the function. The H1 line is the first help text line that consists of comment text. Therefore, the H1 line begins with a % sign. The first line without a % sign as the left-most character ends the help.

In this case, as a block comment using the operators %{ and %} is added, the lines inside the block do not start with a % sign. Therefore, MATLAB considers the %{ line as the end of the help.

As an alternative, use a % sign at the beginning of each line instead of block comments. You can comment multiple lines by selecting them and using Ctrl + R. To uncomment them, select the group of lines, and use Ctrl + T.

Hope this helps!

[Aaron Kaw]

Yes this definitely helps.

But doesn't address ease of use. This multiline documentation feature exists in so many other languages already. The pain of manually adding a % for each newline I make gets irritating.

And using CTRL + R means we have to keep toggling with CTRL + T whenever we need to make major edits to the help documentation of each function/class/etc.

Additionally, CTRL + R places the comment symbol at the beginning of each line, not indented to the the needed position.

[Andrew Sandeman]

Building on the above comment by Aaron with an example, say you would like to document your function as closely as possible to how MATLAB documents it (down to the whitespacing and indentation), see example below:

%CAT Concatenate arrays.
%   CAT(DIM,A,B) concatenates the arrays A and B along
%   the dimension DIM.  
%   CAT(2,A,B) is the same as [A,B].
%   CAT(1,A,B) is the same as [A;B].
%
%   B = CAT(DIM,A1,A2,A3,A4,...) concatenates the input
%   arrays A1, A2, etc. along the dimension DIM.

I currently struggle to have a quick way to do this, for the reasons in the above comment.

(MATLAB 2023a)