Mercurial > hg > octave-nkf
changeset 12546:39ca02387a32
Improve docstrings for a number of functions.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Mon, 28 Mar 2011 16:38:13 -0700 |
parents | e4a22302dc97 |
children | 17997376291b |
files | doc/ChangeLog doc/interpreter/expr.txi doc/interpreter/intro.txi doc/interpreter/io.txi doc/interpreter/tips.txi scripts/ChangeLog scripts/linear-algebra/cross.m scripts/plot/ishold.m scripts/signal/fftfilt.m src/ChangeLog src/DLD-FUNCTIONS/inv.cc src/DLD-FUNCTIONS/tril.cc src/data.cc src/file-io.cc src/ov-typeinfo.cc src/ov-usr-fcn.cc src/utils.cc src/variables.cc |
diffstat | 18 files changed, 86 insertions(+), 31 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,11 @@ +2011-03-28 Rik <octave@nomad.inbox5.com> + + * 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 <octave@nomad.inbox5.com> * interpreter/basics.txi: Add do_braindead_shortcircuit_evaluation to
--- a/doc/interpreter/expr.txi +++ b/doc/interpreter/expr.txi @@ -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
--- a/doc/interpreter/intro.txi +++ b/doc/interpreter/intro.txi @@ -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}
--- a/doc/interpreter/io.txi +++ b/doc/interpreter/io.txi @@ -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.
--- a/doc/interpreter/tips.txi +++ b/doc/interpreter/tips.txi @@ -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
--- a/scripts/ChangeLog +++ b/scripts/ChangeLog @@ -1,3 +1,8 @@ +2011-03-28 Rik <octave@nomad.inbox5.com> + + * linear-algebra/cross.m, plot/ishold.m, signal/fftfilt.m: Improve + docstrings. + 2011-03-26 Robert T. Short <octave@phaselockedsystems.com.com> * signal/ifftshift.m: Add tests.
--- a/scripts/linear-algebra/cross.m +++ b/scripts/linear-algebra/cross.m @@ -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 <Kurt.Hornik@wu-wien.ac.at>
--- a/scripts/plot/ishold.m +++ b/scripts/plot/ishold.m @@ -17,9 +17,13 @@ ## <http://www.gnu.org/licenses/>. ## -*- 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
--- a/scripts/signal/fftfilt.m +++ b/scripts/signal/fftfilt.m @@ -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 <Kurt.Hornik@wu-wien.ac.at>
--- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,10 @@ +2011-03-28 Rik <octave@nomad.inbox5.com> + + * 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 <jwe@octave.org> * file-io.cc (Fmkstemp): Use gnulib::mkstemp.
--- a/src/DLD-FUNCTIONS/inv.cc +++ b/src/DLD-FUNCTIONS/inv.cc @@ -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") {
--- a/src/DLD-FUNCTIONS/tril.cc +++ b/src/DLD-FUNCTIONS/tril.cc @@ -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);
--- a/src/data.cc +++ b/src/data.cc @@ -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\
--- a/src/file-io.cc +++ b/src/file-io.cc @@ -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\
--- a/src/ov-typeinfo.cc +++ b/src/ov-typeinfo.cc @@ -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\
--- a/src/ov-usr-fcn.cc +++ b/src/ov-usr-fcn.cc @@ -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;
--- a/src/utils.cc +++ b/src/utils.cc @@ -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 ();