Comments before the H1 line in help text

Is it possible to specify where exactly the help text begins in an m-file? OR, is there a way to put a comment at the beginning of an m-file that won't get picked up when I ask for the help text on the command line?

Context: If there's some boilerplate that I absolutely need to put at the beginning of my files, The former will show up instead of the desired help text:

% Boilerplate text << what gets returned, but I can't move it

%FOO  An example function. << what I'd like to return
function [] = foo()
    % Does something
end

Thanks!

[DGM]

Who needs to use these files? If it's only for yourself, then you can make a wrapper for help(). If you're trying to make your file synopsis usable for other people, then making some bespoke help() wrapper or replacement isn't much of a solution.

Bear in mind that the optional text output from help() won't support the inline links help would normally provide. You'd have to dig into the undocumented tools behind help() in order to see if you can get to that. Things appear to have changed since R2019b, so any patchjob I make is likely to break in newer versions.

Alternatively, just leave the boilerplate attached to the top of the synopsis like a giant looming monument to unquestionable rules as artificial impediments.

[Walter Roberson]

I just dug into the code, and no there is no option in the code to extract anything other than starting from the first comment.

[Frank Pesta]

Thanks folks; that's what I was afraid of. I was holding out hope that there was some undocumented help() functionality similar to python docstrings that I wasn't yet aware of.

Yes, I could wrap help(), but I'd think that would open the door to further unintended consequences downstream. For my paricular case I'll just leave the boilerplate per DGM; it'll remain a minor inconvenience as opposed to wrapping around base MATLAB behavior for the sake of pretty appearance whilst possibly causing other issues.

Answer 1

[Image Analyst]

I don't believe so. It does not look like it. The help function just takes all the comments at the beginning of the file. If you want it to skip some comment lines and spaces, then I think you'd have to write your own help function that had a "SkipLines" option or somehow found the help comments immediately prior to the function, skipping any boilerplate text and blank lines at the beginning. However, I would call that function something else, not help.m so you don't confuse MATLAB at other times when the standard help function may be needed.

[Paul]

Though undocumented, and it doesn't help in this case, I thought it might help to point out that calling help with function syntax with an output argument returns the help text in a char that would be displayed in the comand window when help is called using command syntax or function sytnax without output argument.

h = help('plus');
h

h = 
    ' +   Plus.
         X + Y adds matrices X and Y. X and Y must have compatible sizes. In the
         simplest cases, they can be the same size or one can be a scalar. Two
         inputs have compatible sizes if, for every dimension, the dimension
         sizes of the inputs are either the same or one of them is 1.
      
         C = PLUS(A,B) is called for the syntax 'A + B' when A or B is an object.
      
         See MATLAB Operators and Special Characters for more details.
     
         Documentation for plus
            doc plus
     
         Other uses of plus
     
            antenna/plus
            calendarDuration/plus
            codistributed/plus
            datetime/plus
            dlarray/plus
            duration/plus
            embedded.fi/plus
            gpuArray/plus
            icsignal/plus
            InputOutputModel/plus
            LagOp/plus
            laurentPolynomial/plus
            laurmat/plus
            laurpoly/plus
            lib.pointer/plus
            matlab.automation.internal.diagnostics.FormattableString/plus
            matlab.coverage.Result/plus
            string/plus
            sym/plus
            symbolic/plus
            tabular/plus
            tall/plus
            timeseries/plus
            tokenizedDocument/plus
     '

[DGM]

I was going to object to the claim that support for output arguments was undocumented, but when I went to check, I found out you're right. It used to be, though (at least the first argument). From the synopsis in R2009b:

T = HELP(TOPIC) returns the help text for TOPIC as a string, with

each line separated by \n. TOPIC is any allowable argument for HELP.

I don't know how I even remembered that.

[Paul]

That 2009b synopsis reads vaguely familiar. Perhaps that's why I was aware of that feature and was surprised to see that it's not documented now. I wonder why it's not documented anymore. Maybe that's covered in release notes, but I'm not motivated enough to check.

Based on "at least the first argument" I checked and learned that there is a second output argument from help. Interesting.

[Image Analyst]

Like I said and demonstrated below in my answer, it would be easier to use readlines than parsing what help returns (a single long string) if you want to extract out just certain lines of the file.

[DGM]

I would think that an ideal wrapper/replacement would have behavior identical to help() in the cases where no custom processing is required. That's why I would expect investigation of how help() operates (e.g. how it adds docs links)

Answer 2

[Image Analyst]

You could try using readlines and writing your own help function PrintHelp. Something like this:

% Test code for PrintHelp
filename = 'foo.m';
PrintHelp(filename)

% function to print the first non-boilerplate batch of comments.
function PrintHelp(filename)
allLines = readlines(filename);
% Skip first batch of comments and look for the blank space
startsWithPercent = startsWith(allLines, '%');
firstLineOfDescription = find(startsWithPercent == 0, 3) + 1;
startsWithFunction = find(startsWith(allLines, 'function'), 1, 'first');
description = allLines(firstLineOfDescription(1) : (startsWithFunction - 1));
fprintf('===================================================================\n');
fprintf('Help for %s:\n', filename)
for k = 1 : numel(description)
	fprintf('%s\n', description(k));
end
fprintf('===================================================================\n');
end

Prints to the command window this:

===================================================================

Help for foo.m:

%FOO An example function. << what I'd like to return

% stuff1

% stuff2

===================================================================