Mercurial > octave
changeset 29512:4f555ba551e5 stable
doc: Update keyword docstrings (bug #60275).
* op-kw-docs: Revamp the documentation for keywords.
author | Rik <rik@octave.org> |
---|---|
date | Thu, 08 Apr 2021 15:34:33 -0700 |
parents | 7e987b69ebde |
children | 1591e7470f1a ec768b0f7dcd |
files | libinterp/op-kw-docs |
diffstat | 1 files changed, 98 insertions(+), 60 deletions(-) [+] |
line wrap: on
line diff
--- a/libinterp/op-kw-docs Thu Apr 08 09:48:17 2021 -0700 +++ b/libinterp/op-kw-docs Thu Apr 08 15:34:33 2021 -0700 @@ -23,17 +23,6 @@ ## ######################################################################## -## FIXME: Can't have duplicate DOCSTRING entries. The function properties -## already has a docstring which overrides this keyword definition. -## If this is ever fixed this entry can be re-inserted after the -## keyword "persistent". -## properties -## libinterp/parse-tree/oct-parse.yy -## -*- texinfo -*- -## @deftypefn {} {} properties -## Begin a properties block in a classdef definition. -## @end deftypefn - ! @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @@ -100,8 +89,9 @@ @deftypefn {} {} #@{ Begin block comment. -There must be no other characters, other than whitespace, on the line before -and after @code{#@{}. It is possible to nest block comments. +The sequence @code{#@{} must appear alone on a line with no other characters, +other than whitespace, before or after it. It is possible to nest block +comments. @seealso{%@\{, #@\}, #} @end deftypefn %{ @@ -110,8 +100,9 @@ @deftypefn {} {} %@{ Begin block comment. -There must be no other characters, other than whitespace, on the line before -and after @code{%@{}. It is possible to nest block comments. +The sequence @code{%@{} must appear alone on a line with no other characters, +other than whitespace, before or after it. It is possible to nest block +comments. @seealso{#@\{, %@\}, %} @end deftypefn #} @@ -120,8 +111,9 @@ @deftypefn {} {} #@} Close block comment. -There must be no other characters, other than whitespace, on the line before -and after @code{#@}}. It is possible to nest block comments. +The sequence @code{#@}} must appear alone on a line with no other characters, +other than whitespace, before or after it. It is possible to nest block +comments. @seealso{%@\}, #@\{, #} @end deftypefn %} @@ -130,8 +122,9 @@ @deftypefn {} {} %@} Close block comment. -There must be no other characters, other than whitespace, on the line before -and after @code{%@}}. It is possible to nest block comments. +The sequence @code{%@}} must appear alone on a line with no other characters, +other than whitespace, before or after it. It is possible to nest block +comments. @seealso{#@\}, %@\{, %} @end deftypefn ... @@ -140,21 +133,22 @@ @deftypefn {} {} ... Continuation marker. -Joins current line with following line before parsing. +Joins current line with following line before parsing. This can be used to +improve the human-readability of Octave code, without affecting interpretation. @end deftypefn & @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} & -Element by element logical 'and' operator. -@seealso{&&, and} +Element-by-element logical 'and' operator. +@seealso{and, &&} @end deftypefn && @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} && Logical 'and' operator (with short-circuit evaluation). -@seealso{&, and} +@seealso{&} @end deftypefn ' @c libinterp/parse-tree/oct-parse.yy @@ -168,7 +162,7 @@ sequences within single-quoted strings are not expanded. I.e., '\n' is a 2-character string '\' and 'n' rather than "\n" which is a single character representing a newline. -@seealso{.', transpose, "} +@seealso{ctranspose, .', "} @end deftypefn ( @c libinterp/parse-tree/oct-parse.yy @@ -187,7 +181,7 @@ -*- texinfo -*- @deftypefn {} {} * Multiplication operator. -@seealso{.*, times} +@seealso{mtimes, .*} @end deftypefn ** @c libinterp/parse-tree/oct-parse.yy @@ -224,7 +218,8 @@ @deftypefn {} {} ++ Increment operator. -As in C, may be applied as a prefix or postfix operator. +Add 1 to existing value of variable. As in C, may be applied as a prefix +(@code{++x}) or postfix (@code{x++}) operator. @seealso{--} @end deftypefn , @@ -246,7 +241,8 @@ @deftypefn {} {} -- Decrement operator. -As in C, may be applied as a prefix or postfix operator. +Subtract 1 from existing value of variable. As in C, may be applied as a +prefix (@code{--x}) or postfix (@code{x--}) operator. @seealso{++} @end deftypefn .' @@ -257,57 +253,57 @@ For complex matrices, computes the transpose, @emph{not} the complex conjugate (Hermitian) transpose. -@seealso{', transpose} +@seealso{transpose, '} @end deftypefn .* @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} .* -Element by element multiplication operator. -@seealso{*, times} +Element-by-element multiplication operator. +@seealso{times, *} @end deftypefn .** @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} .** -Element by element power operator. +Element-by-element power operator. If several complex results are possible, returns the one with smallest non-negative argument (angle). Use @code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a real result is preferred. -@seealso{**, ^, .^, power, realpow, realsqrt, cbrt, nthroot} +@seealso{power, .^, **, ^, realpow, realsqrt, cbrt, nthroot} @end deftypefn .^ @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} .^ -Element by element power operator. +Element-by-element power operator. If several complex results are possible, returns the one with smallest non-negative argument (angle). Use @code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a real result is preferred. -@seealso{.**, ^, **, power, realpow, realsqrt, cbrt, nthroot} +@seealso{power, .**, ^, **, realpow, realsqrt, cbrt, nthroot} @end deftypefn ./ @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} ./ -Element by element right division operator. -@seealso{/, .\\, rdivide, mrdivide} +Element-by-element right division operator. +@seealso{rdivide, /, mrdivide, .\\} @end deftypefn / @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} / Right division operator. -@seealso{./, \\, rdivide, mrdivide} +@seealso{mrdivide, ./, rdivide, \\} @end deftypefn .\ @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} .\ -Element by element left division operator. -@seealso{\\, ./, rdivide, mrdivide} +Element-by-element left division operator. +@seealso{ldivide, \\, mldivide, ./} @end deftypefn \ @c libinterp/parse-tree/oct-parse.yy @@ -317,13 +313,17 @@ Within double-quoted strings, @samp{\} is the line continuation marker used to join the current line with the following line. -@seealso{.\\, /, ldivide, mldivide} +@seealso{mldivide, .\\, ldivide, /} @end deftypefn : @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} : -Select entire rows or columns of matrices. +Select all elements in the specified dimension when indexing. + +@example +x(2, :) # selects 2nd row, all columns +@end example @end deftypefn ; @c libinterp/parse-tree/oct-parse.yy @@ -391,15 +391,15 @@ @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} | -Element by element logical 'or' operator. -@seealso{||, or} +Element-by-element logical 'or' operator. +@seealso{or, ||} @end deftypefn || @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} || Logical 'or' (with short-circuit evaluation) operator. -@seealso{|, or} +@seealso{|} @end deftypefn @ @c libinterp/parse-tree/oct-parse.yy @@ -417,8 +417,8 @@ @end group @end example -(Note: @@ also finds use in creating classes. See manual chapter titled -Object Oriented Programming for detailed description.) +(Note: @@ also finds use in creating classes. See the manual chapter titled +Object Oriented Programming for a detailed description.) @seealso{function, functions, func2str, str2func} @end deftypefn break @@ -485,14 +485,21 @@ @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} else -Alternate action for an if block. See @code{if} for an example. +Alternate action for an if block. + +See @code{if} for an example. @seealso{if} @end deftypefn elseif @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- -@deftypefn {} {} elseif (@var{condition}) -Alternate conditional test for an if block. See @code{if} for an example. +@deftypefn {} {} elseif (@var{cond}) +Alternate conditional test for an if block. + +The conditional @var{cond} is true if it is not empty and if @emph{all} values +are nonzero. + +See @code{if} for an example. @seealso{if} @end deftypefn end_try_catch @@ -534,7 +541,9 @@ @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} endfor -Mark the end of a for loop. See @code{for} for an example. +Mark the end of a for loop. + +See @code{for} for an example. @seealso{for} @end deftypefn endfunction @@ -548,7 +557,9 @@ @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} endif -Mark the end of an if block. See @code{if} for an example. +Mark the end of an if block. + +See @code{if} for an example. @seealso{if} @end deftypefn endmethods @@ -562,7 +573,9 @@ @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} endparfor -Mark the end of a parfor loop. See @code{parfor} for an example. +Mark the end of a parfor loop. + +See @code{parfor} for an example. @seealso{parfor} @end deftypefn endproperties @@ -576,14 +589,18 @@ @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} endswitch -Mark the end of a switch block. See @code{switch} for an example. +Mark the end of a switch block. + +See @code{switch} for an example. @seealso{switch} @end deftypefn endwhile @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} endwhile -Mark the end of a while loop. See @code{while} for an example. +Mark the end of a while loop. + +See @code{while} for an example. @seealso{do, while} @end deftypefn enumeration @@ -620,8 +637,9 @@ @deftypefnx {} {} function {} function_name (@var{input}, @dots{}) @deftypefnx {} {} function @var{outputs} = function_name Begin a function body with name @code{function_name}, with @var{outputs} as -results, and with @var{inputs} as parameters. The function can later be -invoked in Octave using the syntax +results, and with @var{inputs} as parameters. + +The function can later be invoked in Octave using the syntax @example [@var{output1}, @var{output2}, @dots{}] = function_name (@var{input1}, @var{input2}, @dots{}) @@ -654,6 +672,9 @@ @deftypefnx {} {} if (@var{cond}) @dots{} elseif (@var{cond}) @dots{} else @dots{} endif Begin an if block. +The conditional @var{cond} is true if it is not empty and if @emph{all} values +are nonzero. + @example @group x = 1; @@ -668,7 +689,7 @@ @end example @seealso{switch} @end deftypefn -@c ## FIXME: Can't have duplicate DOCSTRING entries. The function methods +@c ## FIXME: Can't have duplicate DOCSTRING entries. The function methods() @c ## already has a docstring which overrides this keyword definition. @c #methods @c #@c libinterp/parse-tree/oct-parse.yy @@ -725,6 +746,14 @@ elsewhere. @seealso{global} @end deftypefn +@c ## FIXME: Can't have duplicate DOCSTRING entries. The function properties() +@c ## already has a docstring which overrides this keyword definition. +@c ## properties +@c ## libinterp/parse-tree/oct-parse.yy +@c ## -*- texinfo -*- +@c ## @deftypefn {} {} properties +@c ## Begin a properties block in a classdef definition. +@c ## @end deftypefn return @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @@ -762,14 +791,20 @@ If an error occurs within a try block, then the catch code will be run and execution will proceed after the catch block (though it is often recommended to -use the lasterr function to re-throw the error after cleanup is completed). +use the @code{lasterr} function to re-throw the error after cleanup is +completed). @seealso{catch, unwind_protect} @end deftypefn until @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- @deftypefn {} {} until (@var{cond}) -End a do-until loop. See @code{do} for an example. +End a do-until loop. + +The conditional @var{cond} is true if it is not empty and if @emph{all} values +are nonzero. + +See @code{do} for an example. @seealso{do} @end deftypefn unwind_protect @@ -809,9 +844,12 @@ while @c libinterp/parse-tree/oct-parse.yy -*- texinfo -*- -@deftypefn {} {} while +@deftypefn {} {} while (@var{cond}) Begin a while loop. +The conditional @var{cond} is true if it is not empty and if @emph{all} values +are nonzero. + @example @group i = 0;