Mercurial > hg > octave-lojdl
changeset 14093:050bc580cb60 stable
doc: Various docstring improvements before 3.6.0 release.
* NEWS, aspell-octave.en.pws, intro.txi, oop.txi, testfun.txi, tips.txi,
FIRfilter.m, FIRfilter_aggregation.m, polynomial.m, polynomial_superiorto.m,
usejava.m, pcg.m, pcr.m, nchoosek.m, validatestring.m, assert.m, weekday.m,
cellfun.cc, error.cc, strfns.cc: Various docstring improvements before 3.6.0
release.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Wed, 21 Dec 2011 19:46:57 -0800 |
parents | 22c50cbad2ce |
children | 595ee644fa6f |
files | NEWS doc/interpreter/doccheck/aspell-octave.en.pws doc/interpreter/intro.txi doc/interpreter/oop.txi doc/interpreter/testfun.txi doc/interpreter/tips.txi examples/@FIRfilter/FIRfilter.m examples/@FIRfilter/FIRfilter_aggregation.m examples/@polynomial/polynomial.m examples/@polynomial/polynomial_superiorto.m scripts/miscellaneous/usejava.m scripts/sparse/pcg.m scripts/sparse/pcr.m scripts/specfun/nchoosek.m scripts/strings/validatestring.m scripts/testfun/assert.m scripts/time/weekday.m src/DLD-FUNCTIONS/cellfun.cc src/error.cc src/strfns.cc |
diffstat | 20 files changed, 198 insertions(+), 117 deletions(-) [+] |
line wrap: on
line diff
--- a/NEWS +++ b/NEWS @@ -80,7 +80,7 @@ ** All .m string functions have been modified for better performance or greater Matlab compatibility. Performance gains of 15X-30X have - been demonstrated. Operations on cell array of strings no longer pay + been demonstrated. Operations on cell array of strings no longer pay quite as high a penalty as those on 2-D character arrays. deblank: Now requires character or cellstr input. @@ -518,7 +518,7 @@ which is no longer a mere dummy. Consequently, nzmax and nnz are no longer always equal in Octave. Octave may also produce a matrix with nnz < nzmax as a result of other operations, so you should - consistently use nnz unless you really want to use nzmax (i.e. the + consistently use nnz unless you really want to use nzmax (i.e., the space allocated for nonzero elements). Sparse concatenation is also affected, and concatenating sparse @@ -555,7 +555,7 @@ pkg install -forge general will automatically download the latest release of the general - package and attempt to install it. No automatic resolving of + package and attempt to install it. No automatic resolving of dependencies is provided. Further, pkg list -forge @@ -928,7 +928,7 @@ For some operations on ranges, Octave will attempt to keep the result as a range. These include negation, adding a scalar, - subtracting a scalar, and multiplying by a scalar. Ranges with zero + subtracting a scalar, and multiplying by a scalar. Ranges with zero increment are allowed and can be constructed using the built-in function `ones'.
--- a/doc/interpreter/doccheck/aspell-octave.en.pws +++ b/doc/interpreter/doccheck/aspell-octave.en.pws @@ -43,6 +43,7 @@ autoscaled AutoScaling AWK +awt backend Backends backends @@ -350,6 +351,7 @@ Graz griddata gswin +GUIs gunzipped gz gzip @@ -438,6 +440,7 @@ jpeg JPEG jpg +jvm keybindings keypress Kolmogorov @@ -978,6 +981,8 @@ voronoi Voronoi Wa +waitbar +waitbars wallis wblcdf wblinv
--- a/doc/interpreter/intro.txi +++ b/doc/interpreter/intro.txi @@ -562,9 +562,9 @@ Here is a description of an imaginary function @code{foo}: -@deftypefn {Function} {} foo (@var{x}) -@deftypefnx {Function} {} foo (@var{x}, @var{y}) -@deftypefnx {Function} {} foo (@var{x}, @var{y}, @dots{}) +@deftypefn {Function File} {} foo (@var{x}) +@deftypefnx {Function File} {} foo (@var{x}, @var{y}) +@deftypefnx {Function File} {} foo (@var{x}, @var{y}, @dots{}) The function @code{foo} subtracts @var{x} from @var{y}, then adds the remaining arguments to the result. If @var{y} is not supplied, then the number 19 is used by default.
--- a/doc/interpreter/oop.txi +++ b/doc/interpreter/oop.txi @@ -54,18 +54,18 @@ fully grasp the techniques described. The polynomial class is used to represent polynomials of the form +@tex +$$ +a_0 + a_1 x + a_2 x^2 + \ldots a_n x^n +$$ +@end tex +@ifnottex @example -@group -@tex -$a_0 + a_1 x + a_2 x^2 + \ldots a_n x^n$ -@end tex -@ifnottex a0 + a1 * x + a2 * x^2 + @dots{} + an * x^n -@end ifnottex -@end group @end example +@end ifnottex @noindent where @tex @@ -130,9 +130,9 @@ @group p = polynomial ([1, 0, 1]); isobject (p) -@result{} 1 + @result{} 1 isa (p, "polynomial") -@result{} 1 + @result{} 1 @end group @end example @@ -157,7 +157,7 @@ @group p = polynomial ([1, 0, 1]); ismethod (p, "roots") -@result{} 1 + @result{} 1 @end group @end example @@ -319,7 +319,7 @@ @group p = polynomial([1,2,3,4]); p(end-1) -@result{} 3 + @result{} 3 @end group @end example
--- a/doc/interpreter/testfun.txi +++ b/doc/interpreter/testfun.txi @@ -312,9 +312,9 @@ @example @group -#if 0 +/* %!test disp ("this is a test") -#endif +*/ @end group @end example @@ -323,9 +323,9 @@ @example @group -/* +#if 0 %!test disp ("this is a test") -*/ +#endif @end group @end example
--- a/doc/interpreter/tips.txi +++ b/doc/interpreter/tips.txi @@ -689,15 +689,17 @@ @example -*- texinfo -*- -@@deftypefn @{Function File@} @{@} nchoosek (@@var@{n@}, @@var@{k@}) +@@deftypefn @{Function File@} @{@@var@{c@} =@} nchoosek (@@var@{n@}, @@var@{k@}) +@@deftypefnx @{Function File@} @{@@var@{c@} =@} nchoosek (@@var@{set@}, @@var@{k@}) -Compute the binomial coefficient or all combinations of -@@var@{n@}. If @@var@{n@} is a scalar then, calculate the -binomial coefficient of @@var@{n@} and @@var@{k@}, defined as +Compute the binomial coefficient or all combinations of a set of items. +If @@var@{n@} is a scalar then calculate the binomial coefficient +of @@var@{n@} and @@var@{k@} which is defined as @@tex $$ @{n \choose k@} = @{n (n-1) (n-2) \cdots (n-k+1) \over k!@} + = @{n! \over k! (n-k)!@} $$ @@end tex @@ifnottex @@ -705,86 +707,161 @@ @@example @@group / \ - | n | n (n-1) (n-2) @dots{} (n-k+1) - | | = ------------------------- - | k | k! + | n | n (n-1) (n-2) @@dots@{@} (n-k+1) n! + | | = ------------------------- = --------- + | k | k! k! (n-k)! \ / @@end group @@end example + @@end ifnottex +@@noindent +This is the number of combinations of @@var@{n@} items taken in groups of +size @@var@{k@}. + +If the first argument is a vector, @@var@{set@}, then generate all +combinations of the elements of @@var@{set@}, taken @@var@{k@} at a time, with +one row per combination. The result @@var@{c@} has @@var@{k@} columns and +@@w@{@@code@{nchoosek (length (@@var@{set@}), @@var@{k@})@}@} rows. + +For example: + +How many ways can three items be grouped into pairs? -If @@var@{n@} is a vector, this generates all combinations -of the elements of @@var@{n@}, taken @@var@{k@} at a time, -one row per combination. The resulting @@var@{c@} has size -@@code@{[nchoosek (length (@@var@{n@}),@@var@{k@}), @@var@{k@}]@}. +@@example +@@group +nchoosek (3, 2) + @@result@{@} 3 +@@end group +@@end example + +What are the possible pairs? -@@code@{nchoosek@} works only for non-negative integer arguments; use -@@code@{bincoeff@} for non-integer scalar arguments and for using vector -arguments to compute many coefficients at once. +@@example +@@group +nchoosek (1:3, 2) + @@result@{@} 1 2 + 1 3 + 2 3 +@@end group +@@end example -@@seealso@{bincoeff@} +@@code@{nchoosek@} works only for non-negative, integer arguments. Use +@@code@{bincoeff@} for non-integer and negative scalar arguments, or for +computing many binomial coefficients at once with vector inputs +for @@var@{n@} or @@var@{k@}. + +@@seealso@{bincoeff, perms@} @@end deftypefn @end example - +@noindent which demonstrates most of the concepts discussed above. @iftex This documentation string renders as -@c Note actually use the output of info below rather than try and -@c reproduce it here to prevent it looking different than how it would +@c Note: use the actual output of info below, rather than try and +@c reproduce it here to prevent it looking different from how it would @c appear with info. @example -@group -- Function File: C = nchoosek (N, K) - Compute the binomial coefficient or all combinations - of N. If N is a scalar then, calculate the binomial - coefficient of N and K, defined as + -- Function File: C = nchoosek (SET, K) + Compute the binomial coefficient or all combinations of a set of + items. + + If N is a scalar then calculate the binomial coefficient of N and + K which is defined as / \ - | n | n (n-1) (n-2) @dots{} (n-k+1) n! + | n | n (n-1) (n-2) ... (n-k+1) n! | | = ------------------------- = --------- | k | k! k! (n-k)! \ / - If N is a vector generate all combinations of the - elements of N, taken K at a time, one row per - combination. The resulting C has size `[nchoosek - (length (N), K), K]'. + This is the number of combinations of N items taken in groups of + size K. + + If the first argument is a vector, SET, then generate all + combinations of the elements of SET, taken K at a time, with one + row per combination. The result C has K columns and + `nchoosek (length (SET), K)' rows. - `nchoosek' works only for non-negative integer - arguments; use `bincoeff' for non-integer scalar - arguments and for using vector arguments to compute - many coefficients at once. + For example: + + How many ways can three items be grouped into pairs? + + nchoosek (3, 2) + => 3 + + What are the possible pairs? - See also: bincoeff. -@end group -@end example + nchoosek (1:3, 2) + => 1 2 + 1 3 + 2 3 + + `nchoosek' works only for non-negative, integer arguments. Use + `bincoeff' for non-integer and negative scalar arguments, or for + computing many binomial coefficients at once with vector inputs + for N or K. -using info, whereas in a printed documentation using @TeX{} it will appear -as + See also: bincoeff, perms +@end example +@noindent +using info, whereas in a printed documentation using @TeX{} it will +appear as -@deftypefn {Function File} {@var{c} =} nchoosek (@var{n}, @var{k}) +@deftypefn {Function File} {@var{c} =} nchoosek (@var{n}, @var{k}) +@deftypefnx {Function File} {@var{c} =} nchoosek (@var{set}, @var{k}) -Compute the binomial coefficient or all combinations of @var{n}. -If @var{n} is a scalar then, calculate the binomial coefficient -of @var{n} and @var{k}, defined as +Compute the binomial coefficient or all combinations of a set of items. + +If @var{n} is a scalar then calculate the binomial coefficient +of @var{n} and @var{k} which is defined as @tex $$ {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!} + = {n! \over k! (n-k)!} $$ @end tex -If @var{n} is a vector generate all combinations of the elements -of @var{n}, taken @var{k} at a time, one row per combination. The -resulting @var{c} has size @code{[nchoosek (length (@var{n}), -@var{k}), @var{k}]}. +@noindent +This is the number of combinations of @var{n} items taken in groups of +size @var{k}. + +If the first argument is a vector, @var{set}, then generate all +combinations of the elements of @var{set}, taken @var{k} at a time, with +one row per combination. The result @var{c} has @var{k} columns and +@w{@code{nchoosek (length (@var{set}), @var{k})}} rows. + +For example: + +How many ways can three items be grouped into pairs? -@code{nchoosek} works only for non-negative integer arguments; use -@code{bincoeff} for non-integer scalar arguments and for using vector -arguments to compute many coefficients at once. +@example +@group +nchoosek (3, 2) + @result{} 3 +@end group +@end example + +What are the possible pairs? -@seealso{bincoeff} +@example +@group +nchoosek (1:3, 2) + @result{} 1 2 + 1 3 + 2 3 +@end group +@end example + +@code{nchoosek} works only for non-negative, integer arguments. Use +@code{bincoeff} for non-integer and negative scalar arguments, or for +computing many binomial coefficients at once with vector inputs for @var{n} +or @var{k}. + +@seealso{bincoeff, perms} @end deftypefn @end iftex
--- a/examples/@FIRfilter/FIRfilter.m +++ b/examples/@FIRfilter/FIRfilter.m @@ -1,9 +1,7 @@ ## -*- texinfo -*- -## @deftypefn {Function File} {} FIRfilter () +## @deftypefn {Function File} {} FIRfilter () ## @deftypefnx {Function File} {} FIRfilter (@var{p}) -## Creates an FIR filter with polynomial @var{p} as -## coefficient vector. -## +## Create a FIR filter with polynomial @var{p} as coefficient vector. ## @end deftypefn function f = FIRfilter (p)
--- a/examples/@FIRfilter/FIRfilter_aggregation.m +++ b/examples/@FIRfilter/FIRfilter_aggregation.m @@ -1,9 +1,7 @@ ## -*- texinfo -*- -## @deftypefn {Function File} {} FIRfilter () +## @deftypefn {Function File} {} FIRfilter () ## @deftypefnx {Function File} {} FIRfilter (@var{p}) -## Creates an FIR filter with polynomial @var{p} as -## coefficient vector. -## +## Create a FIR filter with polynomial @var{p} as coefficient vector. ## @end deftypefn function f = FIRfilter (p)
--- a/examples/@polynomial/polynomial.m +++ b/examples/@polynomial/polynomial.m @@ -1,13 +1,14 @@ ## -*- texinfo -*- -## @deftypefn {Function File} {} polynomial () +## @deftypefn {Function File} {} polynomial () ## @deftypefnx {Function File} {} polynomial (@var{a}) -## Creates a polynomial object representing the polynomial +## Create a polynomial object representing the polynomial ## ## @example ## a0 + a1 * x + a2 * x^2 + @dots{} + an * x^n ## @end example ## -## from a vector of coefficients [a0 a1 a2 ... an]. +## @noindent +## from a vector of coefficients [a0 a1 a2 @dots{} an]. ## @end deftypefn function p = polynomial (a)
--- a/examples/@polynomial/polynomial_superiorto.m +++ b/examples/@polynomial/polynomial_superiorto.m @@ -1,13 +1,14 @@ ## -*- texinfo -*- -## @deftypefn {Function File} {} polynomial () +## @deftypefn {Function File} {} polynomial () ## @deftypefnx {Function File} {} polynomial (@var{a}) -## Creates a polynomial object representing the polynomial +## Create a polynomial object representing the polynomial ## ## @example ## a0 + a1 * x + a2 * x^2 + @dots{} + an * x^n ## @end example ## -## from a vector of coefficients [a0 a1 a2 ... an]. +## @noindent +## from a vector of coefficients [a0 a1 a2 @dots{} an]. ## @end deftypefn function p = polynomial (a)
--- a/scripts/miscellaneous/usejava.m +++ b/scripts/miscellaneous/usejava.m @@ -36,7 +36,7 @@ ## Swing components for lightweight GUIs. ## @end table ## -## This function is provided for compatability with @sc{matlab} scripts which +## This function is provided for compatibility with @sc{matlab} scripts which ## may alter their behavior based on the availability of Java. Octave does ## not implement an interface to Java and this function always returns ## @code{false}.
--- a/scripts/sparse/pcg.m +++ b/scripts/sparse/pcg.m @@ -20,7 +20,7 @@ ## @deftypefn {Function File} {@var{x} =} pcg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{m1}, @var{m2}, @var{x0}, @dots{}) ## @deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}, @var{eigest}] =} pcg (@dots{}) ## -## Solves the linear system of equations @code{@var{A} * @var{x} = @var{b}} +## Solve the linear system of equations @code{@var{A} * @var{x} = @var{b}} ## by means of the Preconditioned Conjugate Gradient iterative ## method. The input arguments are ##
--- a/scripts/sparse/pcr.m +++ b/scripts/sparse/pcr.m @@ -20,7 +20,7 @@ ## @deftypefn {Function File} {@var{x} =} pcr (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{m}, @var{x0}, @dots{}) ## @deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} pcr (@dots{}) ## -## Solves the linear system of equations @code{@var{A} * @var{x} = @var{b}} +## Solve the linear system of equations @code{@var{A} * @var{x} = @var{b}} ## by means of the Preconditioned Conjugate Residuals iterative ## method. The input arguments are ##
--- a/scripts/specfun/nchoosek.m +++ b/scripts/specfun/nchoosek.m @@ -48,9 +48,9 @@ ## This is the number of combinations of @var{n} items taken in groups of ## size @var{k}. ## -## If the first argument is a vector, @var{set}, then generate all combinations -## of the elements of @var{set}, taken @var{k} at a time, with one row per -## combination. The result @var{c} has @var{k} columns and +## If the first argument is a vector, @var{set}, then generate all +## combinations of the elements of @var{set}, taken @var{k} at a time, with +## one row per combination. The result @var{c} has @var{k} columns and ## @w{@code{nchoosek (length (@var{set}), @var{k})}} rows. ## ## For example: @@ -77,8 +77,8 @@ ## ## @code{nchoosek} works only for non-negative, integer arguments. Use ## @code{bincoeff} for non-integer and negative scalar arguments, or for -## computing many binomial coefficients at once with vector inputs for @var{n} -## or @var{k}. +## computing many binomial coefficients at once with vector inputs +## for @var{n} or @var{k}. ## ## @seealso{bincoeff, perms} ## @end deftypefn
--- a/scripts/strings/validatestring.m +++ b/scripts/strings/validatestring.m @@ -39,18 +39,18 @@ ## specific. ## ## Examples: +## @c Set example in small font to prevent overfull line ## -## @example +## @smallexample ## @group ## validatestring ("r", @{"red", "green", "blue"@}) -## @result{} "red" +## @result{} "red" ## ## validatestring ("b", @{"red", "green", "blue", "black"@}) -## @result{} error: validatestring: multiple unique matches were found for 'b': -## blue, black +## @result{} error: validatestring: multiple unique matches were found for 'b': +## blue, black ## @end group -## @end example -## +## @end smallexample ## ## @seealso{strcmp, strcmpi} ## @end deftypefn
--- a/scripts/testfun/assert.m +++ b/scripts/testfun/assert.m @@ -27,7 +27,7 @@ ## be called in three different ways. ## ## @table @code -## @item assert (@var{cond}) +## @item assert (@var{cond}) ## @itemx assert (@var{cond}, @var{errmsg}, @dots{}) ## @itemx assert (@var{cond}, @var{msg_id}, @var{errmsg}, @dots{}) ## Called with a single argument @var{cond}, @code{assert} produces an
--- a/scripts/time/weekday.m +++ b/scripts/time/weekday.m @@ -30,7 +30,7 @@ ## ## Table of return values based on @var{format}: ## -## @multitable @columnfractions .06 .13 .13 +## @multitable @columnfractions .06 .13 .16 ## @headitem @var{n} @tab "short" @tab "long" ## @item 1 @tab Sun @tab Sunday ## @item 2 @tab Mon @tab Monday
--- a/src/DLD-FUNCTIONS/cellfun.cc +++ b/src/DLD-FUNCTIONS/cellfun.cc @@ -1042,11 +1042,11 @@ @group\n\ arrayfun (@@(x,y) x:y, \"abc\", \"def\", \"UniformOutput\", false)\n\ @result{} ans =\n\ -@{\n\ - [1,1] = abcd\n\ - [1,2] = bcde\n\ - [1,3] = cdef\n\ -@}\n\ + @{\n\ + [1,1] = abcd\n\ + [1,2] = bcde\n\ + [1,3] = cdef\n\ + @}\n\ @end group\n\ @end example\n\ \n\ @@ -1099,12 +1099,12 @@ @example\n\ @group\n\ function y = ferr (s, x), y = \"MyString\"; endfunction\n\ -arrayfun (@@str2num, [1234], \\n\ - \"UniformOutput\", false, \"ErrorHandler\", @@ferr)\n\ +arrayfun (@@str2num, [1234],\n\ + \"UniformOutput\", false, \"ErrorHandler\", @@ferr)\n\ @result{} ans =\n\ -@{\n\ - [1,1] = MyString\n\ -@}\n\ + @{\n\ + [1,1] = MyString\n\ + @}\n\ @end group\n\ @end example\n\ \n\
--- a/src/error.cc +++ b/src/error.cc @@ -1113,11 +1113,11 @@ be used to set the state of all warnings.\n\ \n\ If the first argument is @samp{\"on\"} or @samp{\"off\"}, set the state\n\ -of a particular warning using the identifier @var{id}. If the first\n\ +of a particular warning using the identifier @var{id}. If the first\n\ argument is @samp{\"query\"}, query the state of this warning instead.\n\ -If the identifier is omitted, a value of @samp{\"all\"} is assumed. If\n\ +If the identifier is omitted, a value of @samp{\"all\"} is assumed. If\n\ you set the state of a warning to @samp{\"error\"}, the warning named by\n\ -@var{id} is handled as if it were an error instead. So, for example, the\n\ +@var{id} is handled as if it were an error instead. So, for example, the\n\ following handles all warnings as errors:\n\ \n\ @example\n\ @@ -1488,8 +1488,8 @@ @deftypefn {Built-in Function} {@var{lasterr} =} lasterror ()\n\ @deftypefnx {Built-in Function} {} lasterror (@var{err})\n\ @deftypefnx {Built-in Function} {} lasterror ('reset')\n\ -Query or set the last error message structure. When called without arguments\n\ -, return a structure containing the last error message and other\n\ +Query or set the last error message structure. When called without\n\ +arguments, return a structure containing the last error message and other\n\ information related to this error. The elements of the structure are:\n\ \n\ @table @asis\n\
--- a/src/strfns.cc +++ b/src/strfns.cc @@ -862,8 +862,9 @@ If @var{width} is not specified, the width of the terminal screen is used.\n\ Newline characters are used to break the lines in the output string.\n\ For example:\n\ +@c Set example in small font to prevent overfull line\n\ \n\ -@example\n\ +@smallexample\n\ @group\n\ list_in_columns (@{\"abc\", \"def\", \"ghijkl\", \"mnop\", \"qrs\", \"tuv\"@}, 20)\n\ @result{} ans = abc mnop\n\ @@ -880,7 +881,7 @@ \n\ Total is 37 elements using 37 bytes\n\ @end group\n\ -@end example\n\ +@end smallexample\n\ \n\ @seealso{terminal_size}\n\ @end deftypefn")