Re: Major change in C++ doc strings

[John W. Eaton]

On 06/22/2016 11:51 AM, Mike Miller wrote:

> A few questions on behalf of users and maintainers of external oct
> files:
>
>   • Can external code also start using comments for doc strings?
>   • Does this new technique require Octave 4.2?
>   • Are there scripts or Octave functions that packages can use to
>     extract doc strings in a similar manner to Octave?

No, there is currently no mechanism for handling docstrings in external 
.oct files other than having them embedded in the .oct file as program 
text.  We could discuss options, but I think that whatever we do that 
involves storing them separately will lead to fairly complicated 
solutions and possibly confusion because of mismatched files (.oct and 
whatever is used to store the doc strings).  OTOH, maybe I'm being too 
pessimistic, as this is already the situation with .mex files.

> They are also built into liboctinterp, right? Because I can run with
> --doc-cache-file=/dev/null and still get help strings for builtins.

Oops, I was afraid that I might have a detail wrong here...

The doc-cache file is used for the lookup function.

There is a separate built-in docstrings file for the others, and it is 
loaded when Octave starts.  If you set that to /dev/null, then you will 
just see something like "external-doc" for built-in functions and core 
.oct files.  I think we should fix that so things work more like I 
described earlier and the file is only read and searched as needed.

jwe