why does help ignore my comments?

i am not sure when this change was introduced, but it seems that from Matlab 2019a onward (and maybe before), the "help" function is ignoring information i've provided at the top of my function file.

eg,

function [v,d,z]=eof(u)
% EOF empirical orthogonal functions 
% [v,d,z]=eof(u)
% time series components stored as column vectors in u.
% v is the matrix of eigenvectors
% d is a diagonal matrix of eigenvalues
% z is the time series of mode amplitudes, stored as column vectors

and i type >> help eof, i get:

eof is a function.
    [v, d, z] = eof(u)

rather than the explanation of the function i've included in the top of the m-file. this has always worked (since version 1) so i am not sure what is happening or if this is a bug...

-Derek

[dpb]

I don't see such w/ R2019b nor in any of the releases have installed prior...

Which OS?

[dpb]

BTW, a new function behaves as expected as well as existing...

Have you tried something as simple as

clear help

and/or

which -all help

in case you've somehow managed to alias the builtin TMW function?

[Derek Fong]

oh, and this is Mac OSX 10.15 Catalina... i wonder if that's the problem?

(i think it was fine in Mojave but i just noticed this problem recently so i don't know when it began...this happens on any function i have written and many of these functions are 10-20 years old, so nothing has changed)

[Derek Fong]

thanks for fast replies. i have no clue when this began...but here is what i find:

which -all help

/Applications/MATLAB_R2019a.app/toolbox/matlab/helptools/help.m

so i have no clue what is happening. this is very strange... i've never encountered this in all of my years of MATLAB use.

[dpb]

That would definitely seem to be an install/OS issue, then. That's the right path...seems worth a bug report.

[Derek Fong]

i submitted one and hope they can comment on it. i did see that there were some help browser issues with Catalina, so maybe that's it. bizarre but and a frustrating one.

[Steven Lord]

My suspicion is that you've shadowed a function that help calls to locate the file whose help text you're trying to display. I don't have a complete list off the top of my head, but maybe check if the what or where functions are shadowed and rename, remove, or move the shadowing functions?

which -all what
which -all where

[Walter Roberson]

These days, help() directly calls

• evalin
• inputname
• isempty
• isscalar
• onCleanup

and some internal functions that I did not track through.

[dpb]

Steven, wouldn't those go away on restart though -- unless it's caused by a startup.m file which should be pretty easy to check?

Wonder if his lookfor finds the H1 line?

[Walter Roberson]

... There appear to be entire classes devoted to processing help information.

Answer 1

[Image Analyst]

The comments need to be the first thing in the file, not within the body of the function (because there are likely to be tons of those):

% EOF empirical orthogonal functions 
% [v,d,z]=eof(u)
% time series components stored as column vectors in u.
% v is the matrix of eigenvectors
% d is a diagonal matrix of eigenvalues
% z is the time series of mode amplitudes, stored as column vectors
function [v,d,z]=eof(u)

[Derek Fong]

moving the function specification does not solve the problem (puttin the function line below the function encapsulation).

the example code i posted has worked perfectly since written for MATLAB in the 1990s and only recently has had this issue. as indicated by another person here, my code works fine on their computer so i'm guessing it's somehow related to the a bug in the release for the latest Mac operating system.

[Image Analyst]

Worked for me. If it's:

% EOF empirical orthogonal functions 
% [v,d,z]=eof(u)
% time series components stored as column vectors in u.
% v is the matrix of eigenvectors
% d is a diagonal matrix of eigenvalues
% z is the time series of mode amplitudes, stored as column vectors
function [v,d,z]=eof(u)

then I see this in R2020a:

>> help eof

eof empirical orthogonal functions

[v,d,z]=eof(u)

time series components stored as column vectors in u.

v is the matrix of eigenvectors

d is a diagonal matrix of eigenvalues

z is the time series of mode amplitudes, stored as column vectors

Actually I can put it after the function line, and I still see the same thing. So I think it's just you Derek. Call tech support and ask them.

[Derek Fong]

thanks! yes, i don't get that whether i place it before or after the funciton line. so yes, it's just me and my set up... what OS are you using?

i have a message into the help desk so i will see what they share...

[dpb]

That's not what the doc says (nor what TMW-supplied functions do and I didn't realize that would ever work that way).

"Create help text by inserting comments at the beginning of your program. If your program includes a function, position the help text immediately below the function definition line (the line with the function keyword). ..."

lookfor uses the H1 line; and the help text stops with the first blank line (no comment character). Comments beyond that are ignored.

See <Add-help-for-your-program>

[Rik]

@Image Analyst:

I just tested it on Matlab 6.5, and even on that release it works if you put the help text inside the first function. I can't recall this ever having been an issue for me, can you elaborate on what issues might arise if you don't use your proposed layout?

[Derek Fong]

i have no clue why this has broken for my setup, but as i have said previously, i've used MATLAB since version 1 (back in 1988) and i have never had this issue.

i tried the exact example given by Mathworks as hinted at above by dpb and i get the following output:

addme is a function.

c = addme(a, b)

so, something is broken. my only recollection is that this worked with MacOS10.14 last summer using 2019a on this same computer because i teach a MATLAB class and tell students how to properly set up the help on their computers just like the ADDME example and i would have noticed this odd behavior if it was broken then. so it's highly likely something broke when i upgraded my machine to MacOS10.15 last December.

[Derek Fong]

the only restriction (prior to this) i believe existed is that the help "displayed" stops with the first line without a comment.

[dpb]

Since it also works for scripts, I suppose it simply starts with the first comment line in the file and ignores whether there is/isn't a function statement entirely. Hence it would work with whichever sequence is used; I just had always followed the suggested pattern and never tried anything different with functions.

Coming from Fortran, nothing exists outside a program unit so having comments in a file outside a function is "just wrong!" :)