# HG changeset patch # User Rik # Date 1301355493 25200 # Node ID 39ca02387a320fade9682082c841eb2cdb6a3eb7 # Parent e4a22302dc97d7b53189d735f4b653d7941a9b99 Improve docstrings for a number of functions. diff -r e4a22302dc97 -r 39ca02387a32 doc/ChangeLog --- a/doc/ChangeLog Mon Mar 28 14:53:07 2011 -0700 +++ b/doc/ChangeLog Mon Mar 28 16:38:13 2011 -0700 @@ -1,3 +1,11 @@ +2011-03-28 Rik + + * interpreter/expr.txi: Eliminate space between variable and + parenthesis when using indexing. + * interpreter/intro.txi, interpreter/io.txi: Fix typos in docstring. + * interpreter/tips.txi: Add new recommendations for double spaces at + start of sentences and suggested variable names. + 2011-03-28 Rik * interpreter/basics.txi: Add do_braindead_shortcircuit_evaluation to diff -r e4a22302dc97 -r 39ca02387a32 doc/interpreter/expr.txi --- a/doc/interpreter/expr.txi Mon Mar 28 14:53:07 2011 -0700 +++ b/doc/interpreter/expr.txi Mon Mar 28 16:38:13 2011 -0700 @@ -63,9 +63,9 @@ @example @group -a (2) # a scalar -a (1:2) # a row vector -a ([1; 2]) # a column vector +a(2) # a scalar +a(1:2) # a row vector +a([1; 2]) # a column vector @end group @end example @@ -74,7 +74,7 @@ For example: @example -a (:) # a column vector +a(:) # a column vector @end example Given the matrix @@ -88,9 +88,9 @@ @example @group -a (1, [1, 2]) -a (1, 1:2) -a (1, :) +a(1, [1, 2]) +a(1, 1:2) +a(1, :) @end group @end example @@ -114,7 +114,7 @@ @example @group a = 13; -a (ones (1, 4)) +a(ones (1, 4)) @end group @end example @@ -127,7 +127,7 @@ @example @group a = 13; -a (ones (1, 2), ones (1, 3)) +a(ones (1, 2), ones (1, 3)) @end group @end example diff -r e4a22302dc97 -r 39ca02387a32 doc/interpreter/intro.txi --- a/doc/interpreter/intro.txi Mon Mar 28 14:53:07 2011 -0700 +++ b/doc/interpreter/intro.txi Mon Mar 28 16:38:13 2011 -0700 @@ -385,7 +385,7 @@ In order to get good help you first need to know the name of the command that you want to use. This name of the function may not always be -obvious, but a good place to start is to just type @code{help --list}. +obvious, but a good place to start is to type @code{help --list}. This will show you all the operators, keywords, built-in functions, and loadable functions available in the current session of Octave. An alternative is to search the documentation using the @code{lookfor} diff -r e4a22302dc97 -r 39ca02387a32 doc/interpreter/io.txi --- a/doc/interpreter/io.txi Mon Mar 28 14:53:07 2011 -0700 +++ b/doc/interpreter/io.txi Mon Mar 28 16:38:13 2011 -0700 @@ -21,7 +21,7 @@ Octave supports several ways of reading and writing data to or from the prompt or a file. The simplest functions for data Input and Output -(I/O) are easy to use, but only provides limited control of how +(I/O) are easy to use, but only provide limited control of how data is processed. For more control, a set of functions modelled after the C standard library are also provided by Octave. diff -r e4a22302dc97 -r 39ca02387a32 doc/interpreter/tips.txi --- a/doc/interpreter/tips.txi Mon Mar 28 14:53:07 2011 -0700 +++ b/doc/interpreter/tips.txi Mon Mar 28 16:38:13 2011 -0700 @@ -463,16 +463,21 @@ @item Avoid using the word ``cause'' (or its equivalents) unnecessarily. -Instead of, ``Cause Octave to display text in boldface,'' write just +Instead of, ``Cause Octave to display text in boldface,'' just write ``Display text in boldface.'' @item +Use two spaces between the period marking the end of a sentence and the +word which opens the next sentence. This convention has no effect for +typeset formats like @TeX{}, but improves the readability of the documentation +in fixed-width environments such as the Info reader. + +@item Do not start or end a documentation string with whitespace. @item -Format the documentation string so that it fits in an Emacs window on an -80-column screen. It is a good idea for most lines to be no wider than -60 characters. +Format the documentation string so that it fits within an 80-column screen. +It is a good idea for most lines to be no wider than 60 characters. However, rather than simply filling the entire documentation string, you can make it much more readable by choosing line breaks with care. @@ -486,6 +491,26 @@ starting double-quote is not part of the string! @item +When choosing variable names try to adhere to the following guidelines. + +@table @asis +@item +vectors : x,y,z,t,w + +@item +matrices : A,B,M + +@item +strings : str,s + +@item +filenames : fname + +@item +cells,cellstrs : c,cstr +@end table + +@item The documentation string for a variable that is a yes-or-no flag should start with words such as ``Nonzero means@dots{}'', to make it clear that all nonzero values are equivalent and indicate explicitly what zero and @@ -650,7 +675,7 @@ @example @group -*- texinfo -*- -@@deftypefn@{Function File@} @{@@var@{a@} =@} fn (@@var@{x@}, @dots{}) +@@deftypefn @{Function File@} @{@@var@{a@} =@} fn (@@var@{x@}, @dots{}) @@deftypefnx@{Function File@} @{@@var@{a@} =@} fn (@@var@{y@}, @dots{}) Help text in Texinfo format. @@end deftypefn diff -r e4a22302dc97 -r 39ca02387a32 scripts/ChangeLog --- a/scripts/ChangeLog Mon Mar 28 14:53:07 2011 -0700 +++ b/scripts/ChangeLog Mon Mar 28 16:38:13 2011 -0700 @@ -1,3 +1,8 @@ +2011-03-28 Rik + + * linear-algebra/cross.m, plot/ishold.m, signal/fftfilt.m: Improve + docstrings. + 2011-03-26 Robert T. Short * signal/ifftshift.m: Add tests. diff -r e4a22302dc97 -r 39ca02387a32 scripts/linear-algebra/cross.m --- a/scripts/linear-algebra/cross.m Mon Mar 28 14:53:07 2011 -0700 +++ b/scripts/linear-algebra/cross.m Mon Mar 28 16:38:13 2011 -0700 @@ -33,7 +33,7 @@ ## along the first dimension with 3 elements. The optional argument ## @var{dim} forces the cross product to be calculated along ## the specified dimension. -## @seealso{dot, curl} +## @seealso{dot, curl, divergence} ## @end deftypefn ## Author: Kurt Hornik diff -r e4a22302dc97 -r 39ca02387a32 scripts/plot/ishold.m --- a/scripts/plot/ishold.m Mon Mar 28 14:53:07 2011 -0700 +++ b/scripts/plot/ishold.m Mon Mar 28 16:38:13 2011 -0700 @@ -17,9 +17,13 @@ ## . ## -*- texinfo -*- -## @deftypefn {Command} {} ishold +## @deftypefn {Command} {} ishold +## @deftypefnx {Function File} {} ishold (@var{h}) ## Return true if the next plot will be added to the current plot, or ## false if the plot device will be cleared before drawing the next plot. +## +## Optionally, operate on the graphics handle @var{h} rather than the current +## plot. ## @seealso{hold} ## @end deftypefn diff -r e4a22302dc97 -r 39ca02387a32 scripts/signal/fftfilt.m --- a/scripts/signal/fftfilt.m Mon Mar 28 14:53:07 2011 -0700 +++ b/scripts/signal/fftfilt.m Mon Mar 28 16:38:13 2011 -0700 @@ -26,6 +26,7 @@ ## overlap-add method to filter @var{x} with @var{b} using an N-point FFT. ## ## If @var{x} is a matrix, filter each column of the matrix. +## @seealso{filter, filter2} ## @end deftypefn ## Author: Kurt Hornik diff -r e4a22302dc97 -r 39ca02387a32 src/ChangeLog --- a/src/ChangeLog Mon Mar 28 14:53:07 2011 -0700 +++ b/src/ChangeLog Mon Mar 28 16:38:13 2011 -0700 @@ -1,3 +1,10 @@ +2011-03-28 Rik + + * DLD-FUNCTIONS/inv.cc (inv, inverse), DLD-FUNCTIONS/tril.cc (tril), + data.cc (cumsum, szie), file-io.cc (fgets), ov-typeinfo.cc (typeinfo), + ov-usr-fcn.cc (nargout), utils.cc (make_absolute_filename), + variables.cc (who): Improve docstrings + 2011-03-25 John W. Eaton * file-io.cc (Fmkstemp): Use gnulib::mkstemp. diff -r e4a22302dc97 -r 39ca02387a32 src/DLD-FUNCTIONS/inv.cc --- a/src/DLD-FUNCTIONS/inv.cc Mon Mar 28 14:53:07 2011 -0700 +++ b/src/DLD-FUNCTIONS/inv.cc Mon Mar 28 16:38:13 2011 -0700 @@ -38,7 +38,7 @@ DEFUN_DLD (inv, args, nargout, "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {[@var{x} =} inv (@var{A})\n\ +@deftypefn {Loadable Function} {@var{x} =} inv (@var{A})\n\ @deftypefnx {Loadable Function} {[@var{x}, @var{rcond}] =} inv (@var{A})\n\ Compute the inverse of the square matrix @var{A}. Return an estimate\n\ of the reciprocal condition number if requested, otherwise warn of an\n\ @@ -240,9 +240,11 @@ DEFUN_DLD (inverse, args, nargout, "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {[@var{x} =} inverse (@var{A})\n\ +@deftypefn {Loadable Function} {@var{x} =} inverse (@var{A})\n\ @deftypefnx {Loadable Function} {[@var{x}, @var{rcond}] =} inverse (@var{A})\n\ -This in an alias for @code{inv}.\n\ +Compute the inverse of the square matrix @var{A}.\n\ +\n\ +This is an alias for @code{inv}.\n\ @seealso{inv}\n\ @end deftypefn") { diff -r e4a22302dc97 -r 39ca02387a32 src/DLD-FUNCTIONS/tril.cc --- a/src/DLD-FUNCTIONS/tril.cc Mon Mar 28 14:53:07 2011 -0700 +++ b/src/DLD-FUNCTIONS/tril.cc Mon Mar 28 16:38:13 2011 -0700 @@ -400,7 +400,7 @@ @deftypefn {Function File} {} triu (@var{A})\n\ @deftypefnx {Function File} {} triu (@var{A}, @var{k})\n\ @deftypefnx {Function File} {} triu (@var{A}, @var{k}, @var{pack})\n\ -@xref{tril}.\n\ +See the documentation for the @code{tril} function (@pxref{tril}).\n\ @end deftypefn") { return do_trilu ("triu", args); diff -r e4a22302dc97 -r 39ca02387a32 src/data.cc --- a/src/data.cc Mon Mar 28 14:53:07 2011 -0700 +++ b/src/data.cc Mon Mar 28 16:38:13 2011 -0700 @@ -1076,12 +1076,13 @@ @deftypefn {Built-in Function} {} cumsum (@var{x})\n\ @deftypefnx {Built-in Function} {} cumsum (@var{x}, @var{dim})\n\ @deftypefnx {Built-in Function} {} cumsum (@dots{}, 'native')\n\ +@deftypefnx {Built-in Function} {} cumsum (@dots{}, 'double')\n\ +@deftypefnx {Built-in Function} {} cumsum (@dots{}, 'extra')\n\ Cumulative sum of elements along dimension @var{dim}. If @var{dim}\n\ is omitted, it defaults to the first non-singleton dimension.\n\ \n\ -The \"native\" argument implies the summation is performed in native type.\n\ - See @code{sum} for a complete description and example of the use of\n\ -\"native\".\n\ +See @code{sum} for an explanation of the optional parameters 'native',\n\ +'double', and 'extra'.\n\ @seealso{sum, cumprod}\n\ @end deftypefn") { @@ -2039,7 +2040,7 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} size (@var{a})\n\ @deftypefnx {Built-in Function} {} size (@var{a}, @var{dim})\n\ -Return the number rows and columns of @var{a}.\n\ +Return the number of rows and columns of @var{a}.\n\ \n\ With one input argument and one output argument, the result is returned\n\ in a row vector. If there are multiple output arguments, the number of\n\ @@ -2255,7 +2256,6 @@ @end group\n\ @end example\n\ \n\ - \n\ On the contrary, if 'double' is given, the sum is performed in double\n\ precision even for single precision inputs.\n\ \n\ diff -r e4a22302dc97 -r 39ca02387a32 src/file-io.cc --- a/src/file-io.cc Mon Mar 28 14:53:07 2011 -0700 +++ b/src/file-io.cc Mon Mar 28 16:38:13 2011 -0700 @@ -345,7 +345,8 @@ DEFUN (fgets, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} fgets (@var{fid}, @var{len})\n\ +@deftypefn {Built-in Function} {} fgets (@var{fid})\n\ +@deftypefnx {Built-in Function} {} fgets (@var{fid}, @var{len})\n\ Read characters from a file, stopping after a newline, or EOF,\n\ or @var{len} characters have been read. The characters read, including\n\ the possible trailing newline, are returned as a string.\n\ diff -r e4a22302dc97 -r 39ca02387a32 src/ov-typeinfo.cc --- a/src/ov-typeinfo.cc Mon Mar 28 14:53:07 2011 -0700 +++ b/src/ov-typeinfo.cc Mon Mar 28 16:38:13 2011 -0700 @@ -591,7 +591,8 @@ DEFUN (typeinfo, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} typeinfo (@var{expr})\n\ +@deftypefn {Built-in Function} {} typeinfo ()\n\ +@deftypefnx {Built-in Function} {} typeinfo (@var{expr})\n\ \n\ Return the type of the expression @var{expr}, as a string. If\n\ @var{expr} is omitted, return an array of strings containing all the\n\ diff -r e4a22302dc97 -r 39ca02387a32 src/ov-usr-fcn.cc --- a/src/ov-usr-fcn.cc Mon Mar 28 14:53:07 2011 -0700 +++ b/src/ov-usr-fcn.cc Mon Mar 28 16:38:13 2011 -0700 @@ -681,7 +681,7 @@ @code{f}.\n\ \n\ At the top level, @code{nargout} is undefined.\n\ -@seealso{nargin, varargin, varargout}\n\ +@seealso{nargin, isargout, varargin, varargout}\n\ @end deftypefn") { octave_value retval; diff -r e4a22302dc97 -r 39ca02387a32 src/utils.cc --- a/src/utils.cc Mon Mar 28 14:53:07 2011 -0700 +++ b/src/utils.cc Mon Mar 28 16:38:13 2011 -0700 @@ -769,6 +769,7 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} make_absolute_filename (@var{file})\n\ Return the full name of @var{file}, relative to the current directory.\n\ +@seealso{is_absolute_filename, is_rooted_relative_filename, isdir}\n\ @end deftypefn") { octave_value retval = std::string (); diff -r e4a22302dc97 -r 39ca02387a32 src/variables.cc --- a/src/variables.cc Mon Mar 28 14:53:07 2011 -0700 +++ b/src/variables.cc Mon Mar 28 16:38:13 2011 -0700 @@ -1755,7 +1755,7 @@ \n\ If called as a function, return a cell array of defined variable names\n\ matching the given patterns.\n\ -@seealso{whos, regexp}\n\ +@seealso{whos, isglobal, isvarname, exist, regexp}\n\ @end deftypefn") { octave_value retval;