Currently, each built-in function or variable has a doc string that is
written in a C string that is an argument to the DEFUN (or DEFVAR or
similar) macro. The problem with this is that when writing the doc
string, we have to remember to add extra "\" escapes to make the
compiler happy.
I copied this method of defining the doc strings from Emacs. It's
always annoyed me that you have to be careful to get the escapes
right, but I wasn't sure of a better solution. Now I see that Emacs
has switched to using something like this:
DEFUN ("file-name-nondirectory", Ffile_name_nondirectory,
Sfile_name_nondirectory, 1, 1, 0,
doc: /* Return file name FILENAME sans its directory.
For example, in a Unix-syntax file name,
this is everything after the last slash,
or the entire name if it contains no slash. */)
...
apparently with a way to extract these comments and put them in an
external file so that they can be found by Emacs at run time
(actually, I think it has been doing that for a long time).
It seems to me that doing something similar would be useful for
Octave. Mostly it would make it easier to write the doc strings, but
it would also make the binary a little bit smaller if the doc strings
were stored in separate files. We could have mkoctfile do something
useful like strip the comments out and put them in a corresponding
.hlp file (or similar). I think Matlab puts the doc strings for
built-in functions in .m files, but we'd need to be careful about
having mkoctfile do that (it would need to avoid writing over the .m
file of the same name that you are working on converting to C++).
Comments?
jwe