Re: Major change in C++ doc strings

[John W. Eaton]

On 06/22/2016 07:51 AM, Olaf Till wrote:
> On Wed, Jun 22, 2016 at 09:42:10AM +0200, Olaf Till wrote:
> > On Tue, Jun 21, 2016 at 04:33:40PM -0400, John W. Eaton wrote:
> > > I checked in the following changeset so now docstrings in C++ files are
> > > comments rather than C strings.
> > >
> > >    http://hg.savannah.gnu.org/hgweb/octave/rev/112b20240c87
> > >
> > > This is quite a disruptive change,
> >
> > Packages may have more difficulties with such changes than core
> > Octave, because they may attempt to be compatible with different
> > versions of Octave.
>
> Sorry, I didn't look at the code before writing. It seems that outside
> core Octave DEFUN_DLD works as before, with C strings for docs. Is
> that right?

Yes.

Here is a summary.  Since there is no change for existing code outside 
of Octave, I didn't think to post it before.

  For all .m files, doc strings are loaded when the function is parsed 
and stored in memory along with the function definition.

  For dynamically loaded functions in .oct files (defined using the 
DEFUN_DLD macro) that are defined outside of core Octave, doc strings 
are written as C-style quoted strings.  They are stored in the .oct file 
as program text and loaded into memory when the .oct file is loaded.

  For C++ functions in core Octave (defined using any of the the DEFUN 
or DEFUN_DLD macros) doc strings are written in comments as plain text. 
 The Octave build system extracts these strings from the program source 
files and stores them in a single file (libinterp/DOCSTRINGS in the 
build tree).  Octave's help function reads individual doc strings from 
this file as needed.  They are not stored in memory unless they are 
used.  The help function has worked like this for some time now.  My 
change was more about making it easier to edit the help strings.

  For MEX files, you must define a corresponding .m file with the same 
base name that contains the doc string for your function.

jwe