Fixing "unusable help text found in..." warnings

Hi y’all.

When I do a pkg install for my Tablicious package, I get several “unusable help text found in file ‘<classdef_file>’” warnings, as described here.

>> pkg install https://github.com/apjanke/octave-tablicious/releases/download/v0.3.6/tablicious-0.3.6.tar.gz
warning: doc_cache_create: unusable help text found in file 'categorical'
warning: called from
    doc_cache_create>handle_function at line 98 column 5
    doc_cache_create>create_cache at line 118 column 36
    gen_doc_cache_in_dir>@<anonymous> at line 150 column 16
    doc_cache_create>gen_doc_cache_in_dir at line 151 column 9
    doc_cache_create at line 62 column 12
    install>generate_lookfor_cache at line 823 column 5
    install at line 235 column 7
    pkg at line 568 column 9

warning: doc_cache_create: unusable help text found in file 'datetime'
warning: called from
    doc_cache_create>handle_function at line 98 column 5
    doc_cache_create>create_cache at line 118 column 36
    gen_doc_cache_in_dir>@<anonymous> at line 150 column 16
    doc_cache_create>gen_doc_cache_in_dir at line 151 column 9
    doc_cache_create at line 62 column 12
    install>generate_lookfor_cache at line 823 column 5
    install at line 235 column 7
    pkg at line 568 column 9

This is currently happening in Octave 6.2.0, and I’m running it on macOS 10.14.6, but it’s been going on a while, and I suspect that it’s happening on other OSes too.

What exactly is this warning complaining about? What are the criteria for whether help text is “usable” or not in Octave? What are the best practices for package authors around creating help text?

And what specifically is Octave referring to by “help text” in this warning message? That is:

    ## -*- texinfo -*-
    ## @node foo.bar
    ## @deftypefn {Method} {} bar (@var{obj})
    ##
    ## Is this the "help text" here?
    ##
    ## @end deftypefn
    function bar (this)
      %BAR Or is this the "help text" here?
      disp (420);
    end

Any guidance y’all can give is appreciated.

Cheers,
Andrew

Looking at scripts/help/doc_cache_create.m, that warning can happen if the help text is empty or if makeinfo fails for some reason on text that is recognized as Texinfo or if the strip_html_tags function fails if the text is recognized as HTML. I’d add some print statements to handle_function in doc_cache_create.m to find what text is being processed.

I don’t see anything wrong with that help if I put it in a simple function file and use the help function to display it.

In Octave’s classdef files (+containers.Map, anyway) we have the help text for methods as the first block of comments inside the function definition, not before it, but either works. If both are present, the one found just before the function keyword is used.

Where does Matlab accept help text for classdef methods?

I don’t know if this is a red herring, but I’ve never seen @node used within function file documentation. It is used in the TexInfo files (*.txi) in the doc/interpreter directory but those are processed in a different manner.

Okay, here’s a weird thing. I wrote this little function to help me debug this:

function test_build_tablicious_doc_cache
  dummy_cache_file = fullfile (getenv('HOME'), 'tmp', 'tablicious-doc-cache')
  repo_dir = fullfile (getenv('HOME'), 'local', 'repos', 'octave-tablicious')
  code_dir = fullfile (repo_dir, 'inst')
  doc_cache_create (dummy_cache_file, code_dir)
endfunction

And when I run it under Octave 6.2.0 (on macOS 10.14.6), Octave crashes. Am I doing something wrong here?

Works for me on linux 6.2.93