Mercurial > octave-antonio
annotate scripts/testfun/demo.m @ 20162:2645f9ef8c88 stable
doc: Update more docstrings to have one sentence summary as first line.
Reviewed specfun, special-matrix, testfun, and time script directories.
* scripts/specfun/expint.m, scripts/specfun/isprime.m,
scripts/specfun/legendre.m, scripts/specfun/primes.m,
scripts/specfun/reallog.m, scripts/specfun/realsqrt.m,
scripts/special-matrix/gallery.m, scripts/special-matrix/hadamard.m,
scripts/special-matrix/hankel.m, scripts/special-matrix/hilb.m,
scripts/special-matrix/invhilb.m, scripts/special-matrix/magic.m,
scripts/special-matrix/pascal.m, scripts/special-matrix/rosser.m,
scripts/special-matrix/toeplitz.m, scripts/special-matrix/vander.m,
scripts/special-matrix/wilkinson.m, scripts/testfun/assert.m,
scripts/testfun/demo.m, scripts/testfun/example.m, scripts/testfun/fail.m,
scripts/testfun/rundemos.m, scripts/testfun/runtests.m,
scripts/testfun/speed.m, scripts/time/asctime.m, scripts/time/calendar.m,
scripts/time/clock.m, scripts/time/ctime.m, scripts/time/datenum.m,
scripts/time/datestr.m, scripts/time/datevec.m, scripts/time/etime.m,
scripts/time/is_leap_year.m, scripts/time/now.m, scripts/time/weekday.m:
Update more docstrings to have one sentence summary as first line.
| author | Rik <rik@octave.org> |
|---|---|
| date | Sun, 03 May 2015 17:00:11 -0700 |
| parents | 4197fc428c7d |
| children |
| rev | line source |
|---|---|
|
19697
4197fc428c7d
maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents:
19023
diff
changeset
|
1 ## Copyright (C) 2000-2015 Paul Kienzle |
| 5589 | 2 ## |
| 7016 | 3 ## This file is part of Octave. |
| 5589 | 4 ## |
| 7016 | 5 ## Octave is free software; you can redistribute it and/or modify it |
| 6 ## under the terms of the GNU General Public License as published by | |
| 7 ## the Free Software Foundation; either version 3 of the License, or (at | |
| 8 ## your option) any later version. | |
| 9 ## | |
| 10 ## Octave is distributed in the hope that it will be useful, but | |
| 11 ## WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
| 13 ## General Public License for more details. | |
| 5589 | 14 ## |
| 15 ## You should have received a copy of the GNU General Public License | |
| 7016 | 16 ## along with Octave; see the file COPYING. If not, see |
| 17 ## <http://www.gnu.org/licenses/>. | |
| 5589 | 18 |
| 19 ## -*- texinfo -*- | |
|
12643
55430618bd5f
Properly warn when demo or example called on a function without demos
Rik <octave@nomad.inbox5.com>
parents:
12505
diff
changeset
|
20 ## @deftypefn {Command} {} demo @var{name} |
|
55430618bd5f
Properly warn when demo or example called on a function without demos
Rik <octave@nomad.inbox5.com>
parents:
12505
diff
changeset
|
21 ## @deftypefnx {Command} {} demo @var{name} @var{n} |
|
14359
7277fe922e99
doc: Use Octave preference for double quote in docstrings in scripts/
Rik <octave@nomad.inbox5.com>
parents:
14335
diff
changeset
|
22 ## @deftypefnx {Function File} {} demo ("@var{name}") |
|
7277fe922e99
doc: Use Octave preference for double quote in docstrings in scripts/
Rik <octave@nomad.inbox5.com>
parents:
14335
diff
changeset
|
23 ## @deftypefnx {Function File} {} demo ("@var{name}", @var{n}) |
| 5589 | 24 ## |
|
12643
55430618bd5f
Properly warn when demo or example called on a function without demos
Rik <octave@nomad.inbox5.com>
parents:
12505
diff
changeset
|
25 ## Run example code block @var{n} associated with the function @var{name}. |
|
20162
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
26 ## |
|
12643
55430618bd5f
Properly warn when demo or example called on a function without demos
Rik <octave@nomad.inbox5.com>
parents:
12505
diff
changeset
|
27 ## If @var{n} is not specified, all examples are run. |
|
55430618bd5f
Properly warn when demo or example called on a function without demos
Rik <octave@nomad.inbox5.com>
parents:
12505
diff
changeset
|
28 ## |
| 19023 | 29 ## The preferred location for example code blocks is embedded within the script |
| 30 ## m-file immediately following the code that it exercises. Alternatively, | |
| 31 ## the examples may be stored in a file with the same name but no extension | |
| 32 ## located on Octave's load path. To separate examples from regular script | |
| 33 ## code all lines are prefixed by @code{%!}. Each example must also be | |
| 34 ## introduced by the keyword @qcode{"demo"} flush left to the prefix with no | |
| 35 ## intervening spaces. The remainder of the example can contain arbitrary | |
| 36 ## Octave code. For example: | |
| 5589 | 37 ## |
| 38 ## @example | |
|
9051
1bf0ce0930be
Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
39 ## @group |
|
14327
4d917a6a858b
doc: Use Octave coding conventions in @example blocks of docstrings.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
40 ## %!demo |
|
14335
ce2b59a6d0e5
maint: periodic merge of stable to default.
Rik <octave@nomad.inbox5.com>
diff
changeset
|
41 ## %! t = 0:0.01:2*pi; |
|
ce2b59a6d0e5
maint: periodic merge of stable to default.
Rik <octave@nomad.inbox5.com>
diff
changeset
|
42 ## %! x = sin (t); |
|
ce2b59a6d0e5
maint: periodic merge of stable to default.
Rik <octave@nomad.inbox5.com>
diff
changeset
|
43 ## %! plot (t, x); |
| 19023 | 44 ## %! title ("one cycle of a sine wave"); |
| 45 ## %! #------------------------------------------------- | |
| 46 ## %! # the figure window shows one cycle of a sine wave | |
|
9051
1bf0ce0930be
Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
47 ## @end group |
| 5589 | 48 ## @end example |
| 49 ## | |
| 19023 | 50 ## Note that the code is displayed before it is executed so that a simple |
| 51 ## comment at the end suffices for labeling what is being shown. For plots, | |
| 52 ## labeling can also be done with @code{title} or @code{text}. It is generally | |
| 53 ## @strong{not} necessary to use @code{disp} or @code{printf} within the demo. | |
| 5589 | 54 ## |
| 19023 | 55 ## Demos are run in a stand-alone function environment with no access to |
| 56 ## external variables. This means that every demo must have separate | |
| 57 ## initialization code. Alternatively, all demos can be combined into a single | |
| 58 ## large demo with the code | |
| 5589 | 59 ## |
| 60 ## @example | |
| 19023 | 61 ## %! input ("Press <enter> to continue: ", "s"); |
| 5589 | 62 ## @end example |
| 63 ## | |
|
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
64 ## @noindent |
|
20162
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
65 ## between the sections, but this usage is discouraged. Other techniques to |
|
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
66 ## avoid multiple initialization blocks include using multiple plots with a new |
|
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
67 ## @code{figure} command between each plot, or using @code{subplot} to put |
|
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
68 ## multiple plots in the same window. |
| 5589 | 69 ## |
|
20162
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
70 ## Finally, because @code{demo} evaluates within a function context it is not |
|
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
71 ## possible to define new functions within the code. Anonymous functions make |
|
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
72 ## a good substitute in most instances. If function blocks @strong{must} be |
|
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
73 ## used then the code @code{eval (example ("function", n))} will allow Octave |
|
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
74 ## to see them. This has its own problems, however, as @code{eval} only |
|
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
75 ## evaluates one line or statement at a time. In this case the function |
|
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
76 ## declaration must be wrapped with @qcode{"if 1 <demo stuff> endif"} where |
|
2645f9ef8c88
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
77 ## @qcode{"if"} is on the same line as @qcode{"demo"}. For example: |
| 5589 | 78 ## |
| 79 ## @example | |
|
9051
1bf0ce0930be
Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
80 ## @group |
|
14327
4d917a6a858b
doc: Use Octave coding conventions in @example blocks of docstrings.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
81 ## %!demo if 1 |
| 19023 | 82 ## %! function y = f(x) |
| 83 ## %! y = x; | |
|
14327
4d917a6a858b
doc: Use Octave coding conventions in @example blocks of docstrings.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
84 ## %! endfunction |
|
4d917a6a858b
doc: Use Octave coding conventions in @example blocks of docstrings.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
85 ## %! f(3) |
|
4d917a6a858b
doc: Use Octave coding conventions in @example blocks of docstrings.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
86 ## %! endif |
|
9051
1bf0ce0930be
Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
87 ## @end group |
| 5589 | 88 ## @end example |
|
12643
55430618bd5f
Properly warn when demo or example called on a function without demos
Rik <octave@nomad.inbox5.com>
parents:
12505
diff
changeset
|
89 ## |
| 19023 | 90 ## @seealso{rundemos, example, test} |
| 5589 | 91 ## @end deftypefn |
| 92 | |
|
8202
cf59d542f33e
replace all TODOs and XXXs with FIXMEs
Jaroslav Hajek <highegg@gmail.com>
parents:
7540
diff
changeset
|
93 ## FIXME: modify subplot so that gnuplot_has_multiplot == 0 causes it to |
|
cf59d542f33e
replace all TODOs and XXXs with FIXMEs
Jaroslav Hajek <highegg@gmail.com>
parents:
7540
diff
changeset
|
94 ## use the current figure window but pause if not plotting in the |
|
cf59d542f33e
replace all TODOs and XXXs with FIXMEs
Jaroslav Hajek <highegg@gmail.com>
parents:
7540
diff
changeset
|
95 ## first subplot. |
| 5589 | 96 |
| 19023 | 97 function demo (name, n = 0) |
| 5589 | 98 |
| 99 if (nargin < 1 || nargin > 2) | |
| 6046 | 100 print_usage (); |
| 5589 | 101 endif |
| 102 | |
| 19023 | 103 if (ischar (n)) |
|
12505
6a1fe83fe129
Allow command forms of example and demo.
Ben Abbott <bpabbott@mac.com>
parents:
11587
diff
changeset
|
104 n = str2double (n); |
|
13141
e81ddf9cacd5
maint: untabify and remove trailing whitespace from source files
John W. Eaton <jwe@octave.org>
parents:
13065
diff
changeset
|
105 endif |
| 5589 | 106 |
| 19023 | 107 if (! (isreal (n) && isscalar (n) && n == fix (n))) |
| 108 error ("demo: N must be a scalar integer"); | |
| 109 endif | |
| 110 | |
| 6494 | 111 [code, idx] = test (name, "grabdemo"); |
|
15520
bcace51598ed
Improve demo() to warn when an input function does not exist.
Rik <rik@octave.org>
parents:
15079
diff
changeset
|
112 |
|
bcace51598ed
Improve demo() to warn when an input function does not exist.
Rik <rik@octave.org>
parents:
15079
diff
changeset
|
113 if (idx == -1) |
| 19023 | 114 warning ("demo: no function %s found", name); |
|
15520
bcace51598ed
Improve demo() to warn when an input function does not exist.
Rik <rik@octave.org>
parents:
15079
diff
changeset
|
115 return; |
|
bcace51598ed
Improve demo() to warn when an input function does not exist.
Rik <rik@octave.org>
parents:
15079
diff
changeset
|
116 elseif (isempty (idx)) |
| 19023 | 117 warning ("demo: no demo available for %s", name); |
| 5589 | 118 return; |
| 6494 | 119 elseif (n >= length (idx)) |
| 19023 | 120 warning ("demo: only %d demos available for %s", length (idx) - 1, name); |
| 5589 | 121 return; |
| 122 endif | |
| 123 | |
| 124 if (n > 0) | |
| 125 doidx = n; | |
| 126 else | |
|
14868
5d3a684236b0
maint: Use Octave coding conventions for cuddling parentheses in scripts directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
127 doidx = 1:(length (idx) - 1); |
| 5589 | 128 endif |
| 6494 | 129 for i = 1:length (doidx) |
| 5589 | 130 ## Pause between demos |
| 131 if (i > 1) | |
| 6494 | 132 input ("Press <enter> to continue: ", "s"); |
| 5589 | 133 endif |
| 134 | |
| 135 ## Process each demo without failing | |
| 136 try | |
| 6494 | 137 block = code(idx(doidx(i)):idx(doidx(i)+1)-1); |
|
15079
dda73cb60ac5
demo.m: Allow functions in demo blocks (bug #33981).
Rik <rik@octave.org>
parents:
14868
diff
changeset
|
138 ## Use an environment without variables |
| 19023 | 139 eval (["function __demo__ ()\n" block "\nendfunction"]); |
|
15079
dda73cb60ac5
demo.m: Allow functions in demo blocks (bug #33981).
Rik <rik@octave.org>
parents:
14868
diff
changeset
|
140 ## Display the code that will be executed before executing it |
|
dda73cb60ac5
demo.m: Allow functions in demo blocks (bug #33981).
Rik <rik@octave.org>
parents:
14868
diff
changeset
|
141 printf ("%s example %d:%s\n\n", name, doidx(i), block); |
|
dda73cb60ac5
demo.m: Allow functions in demo blocks (bug #33981).
Rik <rik@octave.org>
parents:
14868
diff
changeset
|
142 __demo__; |
| 5589 | 143 catch |
| 144 ## Let the programmer know which demo failed. | |
|
12687
6d4c18565de1
Deprecate error_text(), __error_text__()
Rik <octave@nomad.inbox5.com>
parents:
12643
diff
changeset
|
145 printf ("%s example %d: failed\n%s\n", name, doidx(i), lasterr ()); |
| 5589 | 146 end_try_catch |
| 147 clear __demo__; | |
| 148 endfor | |
| 149 | |
| 150 endfunction | |
| 151 | |
|
14237
11949c9795a0
Revamp %!demos in m-files to use Octave coding conventions on spacing, etc.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
152 |
| 5589 | 153 %!demo |
|
14237
11949c9795a0
Revamp %!demos in m-files to use Octave coding conventions on spacing, etc.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
154 %! t = 0:0.01:2*pi; |
|
11949c9795a0
Revamp %!demos in m-files to use Octave coding conventions on spacing, etc.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
155 %! x = sin (t); |
|
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14359
diff
changeset
|
156 %! plot (t, x); |
| 19023 | 157 %! title ("one cycle of a sine wave"); |
| 158 %! #------------------------------------------------- | |
| 159 %! # the figure window shows one cycle of a sine wave | |
|
13065
1ca3cde15b18
codepsprint: tests for testfun functions
John W. Eaton <jwe@octave.org>
parents:
12687
diff
changeset
|
160 |
|
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14359
diff
changeset
|
161 %!error demo () |
|
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14359
diff
changeset
|
162 %!error demo (1, 2, 3) |
| 19023 | 163 %!error <N must be a scalar integer> demo ("demo", {1}) |
| 164 %!error <N must be a scalar integer> demo ("demo", ones (2,2)) | |
| 165 %!error <N must be a scalar integer> demo ("demo", 1.5) | |
| 166 %!warning <no function .* found> demo ("_%NOT_A_FUNCTION%_"); | |
| 167 %!warning <only 1 demos available for demo> demo ("demo", 10); | |
|
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14359
diff
changeset
|
168 |