Re: Finding DOCSTRINGS in the source code

[John W. Eaton]

On 16-Jan-2011, Rik wrote:

| 
| > 
| > I noticed Attr flags in a whos command that are not in the help whos
| > documentation.  Since whos is builtin I do not know where the documentation
| > is kept.  
| 'whos' is documented in src/variables.cc.  There may be a better way to do
| it, but I use the following to find where the Texinfo strings are kept.
| 
| cd doc/interpreter
| grep 'DOCSTRING(whos)' *.txi
| --> var.texi
| grep -B 4 'deftypefn .*\<whos\>' var.texi
| -->
| 
| 
| @c src/variables.cc
| @anchor{doc-whos}
| @deftypefn  {Command} {} whos
| 
| Every function has an @c comment indicating where the Texinfo string came
| from.  If you already know that it came from a script or the src directory
| then you can skip the first grep.  Instead you can use the second grep on
| 'scripts/DOCSTRINGS' or 'src/DOCSTRINGS'.

I checked in a small change that will simplify this a bit.  Now you
should be able to do

  grep -h '@c any ' *.texi
  --> @c any src/data.cc
or

  sed -n 's/address@hidden any //p' *.texi
  --> src/data.cc

in the doc/interpreter directory of your build tree and get the result
immediately.  If you have separate build and source trees, you don't
have to worry about the two .texi files in the source tree
(octave.texi and version.texi) since they don't contain and
docstrings (if they did, they would be .txi files that are processed
to generate .texi files).

Maybe there is a better way to tag this in the .texi file, but I think
this is simple enough.  We could also add the line number for .cc
files, but that would require a little more work and I don't really
think it is necessary.  It is simple enough to search for the function
definition once you know what file to look in.

I also thought about adding an additional comment for each doc string
telling people not to edit them directly.  Maybe it should look
something like this:

  @c DO NOT EDIT the following docstring.  It was inserted in this file
  @c automatically.  To make changes, edit the docstring that appears
  @c along with the function definition in the file src/data.cc.
  @c
  @c The following line allows quick lookup of docstrings in source files.
  @c any scripts/data.cc

But now, thinking about this text, it seems a bit misleading, since it
is not OK to edit anything in the generated .texi files, and adding a
"DO NOT EDIT this file, it was generated automatically from..."
statement for every docstring seems quite redundant.  Also, I'm not
sure this is a significant problem as I don't remember seeing very
many (if any) patches that modify the .texi files.

Comments?

jwe