Thread Subject: commentary help lines

Hi!

I have many matlab files with comment lines at the
beginning. With the syntax 'help <m_file>' you get these
comment lines. This is all well known of course, but I have
some files which seem to be coded in the same way but which
does not give any help when 'evoked' as above. Only a 'No
help comments found in <m_file>.' comes up. Any idea how to
change this behaviour?

"Norman " <norman.nospam.violet@tu-berlin.de> wrote in
message <g2ta6d$ni9$1@fred.mathworks.com>...
> Hi!
>
> I have many matlab files with comment lines at the
> beginning. With the syntax 'help <m_file>' you get these
> comment lines. This is all well known of course, but I have
> some files which seem to be coded in the same way but which
> does not give any help when 'evoked' as above. Only a 'No
> help comments found in <m_file>.' comes up. Any idea how to
> change this behaviour?

edit the m-file

jos

"Jos " <DELjos@jasenDEL.nl> wrote:
> > Any idea how to change this behaviour?
>
> edit the m-file

Well, I just added those comment lines this morning ... and
it still does not work. I even restarted Matlab (2007b) to
force to update its path and file informations without
success, and changing into the folder of the file doesn't
help either.

I have written many m-files where it does work, but I have
encountered some, like the one this morning, where it does
not work. Is there any other undocumented condition for the
comment lines which must be fulfilled to be accepted as help
documentation? I know only that the lines in question must
be in the first, continous block of comment lines in the
file. E.g:
function exit = foo(argument_one, varargin)
% This shall be shown if 'help foo' is entered
% in the command window

Norman

"Norman " <norman.nospam.violet@tu-berlin.de> wrote in
message <g2tddi$1g3$1@fred.mathworks.com>...
> "Jos " <DELjos@jasenDEL.nl> wrote:
> > > Any idea how to change this behaviour?
> >
> > edit the m-file
>
> Well, I just added those comment lines this morning ... and
> it still does not work. I even restarted Matlab (2007b) to
> force to update its path and file informations without
> success, and changing into the folder of the file doesn't
> help either.
>
> I have written many m-files where it does work, but I have
> encountered some, like the one this morning, where it does
> not work. Is there any other undocumented condition for the
> comment lines which must be fulfilled to be accepted as help
> documentation? I know only that the lines in question must
> be in the first, continous block of comment lines in the
> file. E.g:
> function exit = foo(argument_one, varargin)
> % This shall be shown if 'help foo' is entered
> % in the command window
>
> Norman


Strange. Check if

1) the help format is still wrong.
2) you've edited the wrong file. Note that there can be
multiple files with the same name on your matlab-path. What
does:

  which mymfile -all

give you?

hth
Jos

"Jos " <DELjos@jasenDEL.nl> wrote

> Strange. Check if
>
> 1) the help format is still wrong.
> 2) you've edited the wrong file. Note that there can be
> multiple files with the same name on your matlab-path. What
> does:
>
> which mymfile -all
>
> give you?

Weired .... I did nothing, but restarted Matlab again, now
the help functionality is there (and, to answer your 2nd
question; yes there's only one file with that name).

Hey, I think I got it, well, partly: Sometimes you need to
give the m-filename including the '.m', sometimes not.

"Norman ":
<SNIP strange help-problems...

> Hey, I think I got it, well, partly: Sometimes you need to
> give the m-filename including the '.m', sometimes not...

this may happen if your files reside on a server;

     help rehash;

could give some insights...
also, i've never encountered a situation where help only
worked with the .m extension(?)... can you show an
example...

us

"us " <us@neurol.unizh.ch> wrote:

> > Hey, I think I got it, well, partly: Sometimes you need to
> > give the m-filename including the '.m', sometimes not...
>
> this may happen if your files reside on a server;
>
> help rehash;

A restarted matlab should do the trick too, or don't?
I did not try that today, but I seem to remember to have
tried it the last time it happened.

> also, i've never encountered a situation where help only
> worked with the .m extension(?)... can you show an
> example...

Shall I copy my matlab program packet here? *lol* I really
don't know how to show an example .... but look here (just
typed into the command window):

---------snip------------
>> help questdlgtout

No help comments found in questdlgtout.m.

Use the Help browser Search tab to search the documentation, or
type "help help" for help command options, such as help for
methods.
---------snip------------

As it seems Matlab already looks into questdlgtout.m (with
extension), but does not find any help lines. Now again with
'.m' in the command:

---------snip------------
>> help questdlgtout.m
 QuestDlgTOut Question dialog with time out box.
 [... complete help follows]
---------snip------------

So, how to explain that?

In this case 'questdlgtout' is a modified questdlg (original
from mathworks), but I had unique m-files without
predecessor, so this shouldn't be an important fact here.

Norman

"Norman " <norman.nospam.violet@tu-berlin.de> wrote in message
<g2tddi$1g3$1@fred.mathworks.com>...
> "Jos " <DELjos@jasenDEL.nl> wrote:
> > > Any idea how to change this behaviour?
> >
> > edit the m-file
>
> Well, I just added those comment lines this morning ... and
> it still does not work. I even restarted Matlab (2007b) to
> force to update its path and file informations without
> success, and changing into the folder of the file doesn't
> help either.
>
> I have written many m-files where it does work, but I have
> encountered some, like the one this morning, where it does
> not work. Is there any other undocumented condition for the
> comment lines which must be fulfilled to be accepted as help
> documentation? I know only that the lines in question must
> be in the first, continous block of comment lines in the
> file. E.g:
> function exit = foo(argument_one, varargin)
> % This shall be shown if 'help foo' is entered
> % in the command window
>
> Norman

Are you sure that you do not have multiple
copies of the file and you edited one of the
copies that was lower on the search path?

I've never heard of a case where the .m was
required in the help command. Never.

The only other possibility I can think of is
disk corruption.

John

"John D'Errico" <woodchips@rochester.rr.com> wrote:

> Are you sure that you do not have multiple
> copies of the file and you edited one of the
> copies that was lower on the search path?

Yes, absolutely sure.

> I've never heard of a case where the .m was
> required in the help command. Never.

see above (message #7)

> The only other possibility I can think of is
> disk corruption.

Hm, possible of course, but unlikely I think. Also I
couldn't think of a way how this behaviour could be
accomplished by a corrupted disk (by the way; it's a RAID 1
drive, that's why a hard disk failure seems unlikely to me);
everything else works.

"Norman " <norman.nospam.violet@tu-berlin.de> wrote in message
<g2tmph$554$1@fred.mathworks.com>...
> "John D'Errico" <woodchips@rochester.rr.com> wrote:
>
> > Are you sure that you do not have multiple
> > copies of the file and you edited one of the
> > copies that was lower on the search path?
>
> Yes, absolutely sure.
>
> > I've never heard of a case where the .m was
> > required in the help command. Never.
>
> see above (message #7)
>
> > The only other possibility I can think of is
> > disk corruption.
>
> Hm, possible of course, but unlikely I think. Also I
> couldn't think of a way how this behaviour could be
> accomplished by a corrupted disk (by the way; it's a RAID 1
> drive, that's why a hard disk failure seems unlikely to me);
> everything else works.

Ok. You also mentioned that these files were
on a server.

Temporarily move them off, onto a local drive.
Test if the problem is with the location.

John

"Norman ":
<SNIP interesting help-failure...

> So, how to explain that?

just for the sake of it:

     clear all; % !!!!!
     a=inmem
% a = Empty cell array: 0-by-1
     help your_program
     a=inmem
% do you find your function in the list?
     help your_program.m
     a=inmem
% again?
     ver
% ?

us

"Norman " <norman.nospam.violet@tu-berlin.de> wrote in
message <g2tmph$554$1@fred.mathworks.com>...
> "John D'Errico" <woodchips@rochester.rr.com> wrote:
>
> > Are you sure that you do not have multiple
> > copies of the file and you edited one of the
> > copies that was lower on the search path?
>
> Yes, absolutely sure.
>
> > I've never heard of a case where the .m was
> > required in the help command. Never.
>
> see above (message #7)
>
> > The only other possibility I can think of is
> > disk corruption.
>
> Hm, possible of course, but unlikely I think. Also I
> couldn't think of a way how this behaviour could be
> accomplished by a corrupted disk (by the way; it's a RAID 1
> drive, that's why a hard disk failure seems unlikely to me);
> everything else works.


may the help.m itself is corrupted?

Jos

"John D'Errico" <woodchips@rochester.rr.com> wrote in

> Ok. You also mentioned that these files were
> on a server.

No, _I_ did not. That was an idea of 'us'. Sorry for the
confusion. All my files, including Matlab are on my local
drive(s)

Norman

 
> just for the sake of it:

okay, I've done that, but everything seems to be okay for me
(see below). inmem shows my program everytime (w and w/o '.m').

Norman

---------snip---------


>> clear all
>> a=inmem
a =
    'path'
    'mltimerpackage'

>> help questdlgtout

No help comments found in questdlgtout.m.

Use the Help browser Search tab to search the documentation, or
type "help help" for help command options, such as help for
methods.

>> a=inmem
a =
    'ispc'
    'filesep'
    'path'
    'iscellstr'
    'fileparts'
    'fliplr'
    'help'
    'questdlgtout'
    'mltimerpackage'
    'helptools\private\splitClassInformation'
    'helptools\private\safeWhich'
    'helptools\private\hashedDirInfo'
    'helptools\private\fixLocalFunctionCase'
    'helptools\private\fixFileNameCase'
    'helpDisplayCollector'
>> help questdlgtout.m
 QuestDlgTOut Question dialog with time out box.
 
[...]

>> a=inmem
a =
    'ispc'
    'filesep'
    'usejava'
    'figure'
    'path'
    'iscellstr'
    'fileparts'
    'fullfile'
    'errordlg'
    'msgbox'
    'fliplr'
    'helpdlg'
    'dialog'
    'textwrap'
    'help'
    'questdlgtout'
    'uiwait'
    'uiresume'
    'timer.timer'
    'mltimerpackage'
    'warndlg'
    'helptools\private\splitClassInformation'
    'helptools\private\safeWhich'
    'helptools\private\minimizePath'
    'helptools\private\makehelphyper'
    'helptools\private\hashedDirInfo'
    'helptools\private\fixLocalFunctionCase'
    'helptools\private\fixFileNameCase'
    'helptools\private\findSeeAlso'
    'helptools\private\extractCaseCorrectedName'
    'helpDisplayCollector'
    'helpClassWrapper'
    'listdlg'
    'inputdlg'

"Norman " <norman.nospam.violet@tu-berlin.de> wrote in
message <g2tr9u$6vt$1@fred.mathworks.com>...
>
> > just for the sake of it:
>
> okay, I've done that, but everything seems to be okay for me
> (see below). inmem shows my program everytime (w and w/o
'.m').
>
Maybe it has something about the RAID/filesystem and
matlab's caching of functions to do after all. Maybe you can
test by writing a simple test function without help, run it,
then add help and see if matlab doesn't display said help.
If so test if matlab displays the help after a 'rehash',
after a 'clear functions'.

HTH,
Bjeorn

"Norman ":
<SNIP interesting help-conundrum continued...

well, there is clearly a difference in the modules
used/needed to find the help...
what version do you run...

if(f) you have r2008a, you might try this and show the
results for both <your_fcn> and <your_fcn.m>...

     d=helpUtils.hashedDirInfo(cd)
     p=helpUtils.helpProcess(0,1,{'your_fcn'});
     p.getHelpText;
     p.helpStr

us

"us " <us@neurol.unizh.ch> wrote in message
<g2tvoe$2k5$1@ginger.mathworks.com>...
> "Norman ":
> <SNIP interesting help-conundrum continued...

> if(f) you have r2008a, you might try this and show the
> results for both <your_fcn> and <your_fcn.m>...

No, sorry, I still use 2007b. In the meantime I had sent the
file to some friends and on their computers (also matlab
2007b) it worked as usual, so it has to do with my paths or
something else specific with my computer/matlab. The thing I
am wondering about is: I have plenty of self-written m-files
(also in the same places) where it works as usual too.

@Bjeorn (is that really spelled that way?):
I did as you asked: new test function w/o help, than added
help and it does as requested. No hint why it does not with
'questdlgtout.m'.

I will continue to observe this in future, but since a) it's
not a really important matter, b) I don't know what else to
check and c) weekend's coming fast, I will drop this now
until monday at least. Thanks for all your help so far.

"Norman " <norman.nospam.violet@tu-berlin.de> wrote in message
news:g2ta6d$ni9$1@fred.mathworks.com...
> Hi!
>
> I have many matlab files with comment lines at the
> beginning. With the syntax 'help <m_file>' you get these
> comment lines. This is all well known of course, but I have
> some files which seem to be coded in the same way but which
> does not give any help when 'evoked' as above. Only a 'No
> help comments found in <m_file>.' comes up. Any idea how to
> change this behaviour?

From the documentation for HELP:

http://www.mathworks.com/access/helpdesk/help/techdoc/ref/help.html

Create self-documenting online help for your own M-files by entering text on
one or more contiguous comment lines, beginning with the second line of the
file (first line if it is a script). For example, the function soundspeed.m
begins with

*snip*

Are you certain that the help comment lines start on the second line of your
function file, with nothing but the function declaration line before it?
Even putting a semicolon before that first comment character causes HELP not
to consider that comment as M-file help.

Windows, Linux, Mac, or Solaris?

If you're on a non-Windows platform, are you matching the casing of the
M-file name in your call to HELP?


--
Steve Lord
slord@mathworks.com

"Steven Lord" <slord@mathworks.com> wrote...

> From the documentation for HELP:
> *snip*
>
> Are you certain that the help comment lines start on the
> second line of your function file, with nothing but the
> function declaration line before it?

Yes, I am. And there's nothing like a semicolon at the end.
The only difference might be different unprintable
characters - like CR/LF instead of only CR at the end of
line. I can't check that right now, but I will see into
that on Monday. I will also try to run a file monitor to
see what 'help' does exactly (which files are touched in
the search process).

> Windows, Linux, Mac, or Solaris?

WinXP SP3, so no case-sensitivity to behold. But I checked
it nevertheless, and also I checked if 'help' maybe can't
handle long filename (longer than 8.3 file format), but it
can.

Norman

In article <g2ta6d$ni9$1@fred.mathworks.com>, norman.nospam.violet@tu-
berlin.de says...
> Hi!
>
> I have many matlab files with comment lines at the
> beginning. With the syntax 'help <m_file>' you get these
> comment lines. This is all well known of course, but I have
> some files which seem to be coded in the same way but which
> does not give any help when 'evoked' as above. Only a 'No
> help comments found in <m_file>.' comes up. Any idea how to
> change this behaviour?
>

are your files sitting under the MATLAB toolbox directory? We recommend
NOT placing your files there since MATLAB caches the contents so it can
speed up. If your files are there, try rehash toolboxcache. Also, move
them into a different directory outside the MATLAB tree.

--
Loren
http://blogs.mathworks.com/loren/

Loren Shure <loren@mathworks.com> wrote:

> are your files sitting under the MATLAB toolbox
directory? We recommend
> NOT placing your files there since MATLAB caches the
contents so it can
> speed up. If your files are there, try rehash
toolboxcache. Also, move
> them into a different directory outside the MATLAB tree.

My files are not located in or under the Matlab toolbox
path. But I thought about some cache problem here too: I
noticed (but this is a different matter), that Matlab
sometimes does not notice new files (even if definitely
created within Matlab itself); I had to change to the
directory where the new file is located before Matlab knows
about its existence (and sometimes even not after leaving
that directory again). That might be explainable - somehow
- by the amount of files which are located within my file
structure. 'Rehash' won't work neither in these cases, but
removing and adding all my pathes again will do.
(Directories with a few thousands of files are slowing down
the computer too, but that is most probably a problem
caused by Windows - but if you have any advice here too; I
am all ears !).
But this can't explain my primary question here of course,
because Matlab can access the file if named with its
extension, but not without extension.

Norman

"Norman " <norman.nospam.violet@tu-berlin.de> wrote in
message <g36npl$ap2$1@fred.mathworks.com>...
> Loren Shure <loren@mathworks.com> wrote:
>
> > are your files sitting under the MATLAB toolbox
> directory? We recommend
> > NOT placing your files there since MATLAB caches the
> contents so it can
> > speed up. If your files are there, try rehash
> toolboxcache. Also, move
> > them into a different directory outside the MATLAB tree.
>
> My files are not located in or under the Matlab toolbox
> path. But I thought about some cache problem here too: I
> noticed (but this is a different matter), that Matlab
> sometimes does not notice new files (even if definitely
> created within Matlab itself); I had to change to the
> directory where the new file is located before Matlab knows
> about its existence (and sometimes even not after leaving
> that directory again). That might be explainable - somehow
> - by the amount of files which are located within my file
> structure. 'Rehash' won't work neither in these cases, but
> removing and adding all my pathes again will do.
> (Directories with a few thousands of files are slowing down
> the computer too, but that is most probably a problem
> caused by Windows - but if you have any advice here too; I
> am all ears !).
> But this can't explain my primary question here of course,
> because Matlab can access the file if named with its
> extension, but not without extension.
>
> Norman