annotate scripts/polynomial/polyder.m @ 30875:5d3faba0342e

doc: Ensure documentation lists output argument when it exists for all m-files. For new users of Octave it is best to show explicit calling forms in the documentation and to show a return argument when it exists. * bp-table.cc, shift.m, accumarray.m, accumdim.m, bincoeff.m, bitcmp.m, bitget.m, bitset.m, blkdiag.m, celldisp.m, cplxpair.m, dblquad.m, flip.m, fliplr.m, flipud.m, idivide.m, int2str.m, interpft.m, logspace.m, num2str.m, polyarea.m, postpad.m, prepad.m, randi.m, repmat.m, rng.m, rot90.m, rotdim.m, structfun.m, triplequad.m, uibuttongroup.m, uicontrol.m, uipanel.m, uipushtool.m, uitoggletool.m, uitoolbar.m, waitforbuttonpress.m, help.m, __additional_help_message__.m, hsv.m, im2double.m, im2frame.m, javachk.m, usejava.m, argnames.m, char.m, formula.m, inline.m, __vectorize__.m, findstr.m, flipdim.m, strmatch.m, vectorize.m, commutation_matrix.m, cond.m, cross.m, duplication_matrix.m, expm.m, orth.m, rank.m, rref.m, trace.m, vech.m, cast.m, compare_versions.m, delete.m, dir.m, fileattrib.m, grabcode.m, gunzip.m, inputname.m, license.m, list_primes.m, ls.m, mexext.m, movefile.m, namelengthmax.m, nargoutchk.m, nthargout.m, substruct.m, swapbytes.m, ver.m, verLessThan.m, what.m, fminunc.m, fsolve.m, fzero.m, optimget.m, __fdjac__.m, matlabroot.m, savepath.m, campos.m, camroll.m, camtarget.m, camup.m, camva.m, camzoom.m, clabel.m, diffuse.m, legend.m, orient.m, rticks.m, specular.m, thetaticks.m, xlim.m, xtickangle.m, xticklabels.m, xticks.m, ylim.m, ytickangle.m, yticklabels.m, yticks.m, zlim.m, ztickangle.m, zticklabels.m, zticks.m, ellipsoid.m, isocolors.m, isonormals.m, stairs.m, surfnorm.m, __actual_axis_position__.m, __pltopt__.m, close.m, graphics_toolkit.m, pan.m, print.m, printd.m, __ghostscript__.m, __gnuplot_print__.m, __opengl_print__.m, rotate3d.m, subplot.m, zoom.m, compan.m, conv.m, poly.m, polyaffine.m, polyder.m, polyint.m, polyout.m, polyreduce.m, polyvalm.m, roots.m, prefdir.m, prefsfile.m, profexplore.m, profexport.m, profshow.m, powerset.m, unique.m, arch_rnd.m, arma_rnd.m, autoreg_matrix.m, bartlett.m, blackman.m, detrend.m, durbinlevinson.m, fftconv.m, fftfilt.m, fftshift.m, fractdiff.m, hamming.m, hanning.m, hurst.m, ifftshift.m, rectangle_lw.m, rectangle_sw.m, triangle_lw.m, sinc.m, sinetone.m, sinewave.m, spectral_adf.m, spectral_xdf.m, spencer.m, ilu.m, __sprand__.m, sprand.m, sprandn.m, sprandsym.m, treelayout.m, beta.m, betainc.m, betaincinv.m, betaln.m, cosint.m, expint.m, factorial.m, gammainc.m, gammaincinv.m, lcm.m, nthroot.m, perms.m, reallog.m, realpow.m, realsqrt.m, sinint.m, hadamard.m, hankel.m, hilb.m, invhilb.m, magic.m, pascal.m, rosser.m, toeplitz.m, vander.m, wilkinson.m, center.m, corr.m, cov.m, discrete_cdf.m, discrete_inv.m, discrete_pdf.m, discrete_rnd.m, empirical_cdf.m, empirical_inv.m, empirical_pdf.m, empirical_rnd.m, kendall.m, kurtosis.m, mad.m, mean.m, meansq.m, median.m, mode.m, moment.m, range.m, ranks.m, run_count.m, skewness.m, spearman.m, statistics.m, std.m, base2dec.m, bin2dec.m, blanks.m, cstrcat.m, deblank.m, dec2base.m, dec2bin.m, dec2hex.m, hex2dec.m, index.m, regexptranslate.m, rindex.m, strcat.m, strjust.m, strtrim.m, strtrunc.m, substr.m, untabify.m, __have_feature__.m, __prog_output_assert__.m, __run_test_suite__.m, example.m, fail.m, asctime.m, calendar.m, ctime.m, date.m, etime.m: Add return arguments to @deftypefn macros where they were missing. Rename variables in functions (particularly generic "retval") to match documentation. Rename some return variables for (hopefully) better clarity (e.g., 'ax' to 'hax' to indicate it is a graphics handle to an axes object).
author Rik <rik@octave.org>
date Wed, 30 Mar 2022 20:40:27 -0700
parents 796f54d4ddbf
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
1 ########################################################################
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
2 ##
30564
796f54d4ddbf update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 29359
diff changeset
3 ## Copyright (C) 1994-2022 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
4 ##
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
5 ## See the file COPYRIGHT.md in the top-level directory of this
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
6 ## distribution or <https://octave.org/copyright/>.
2313
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe]
jwe
parents: 2311
diff changeset
7 ##
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe]
jwe
parents: 2311
diff changeset
8 ## This file is part of Octave.
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe]
jwe
parents: 2311
diff changeset
9 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
10 ## Octave is free software: you can redistribute it and/or modify it
2313
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe]
jwe
parents: 2311
diff changeset
11 ## under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
12 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
13 ## (at your option) any later version.
2313
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe]
jwe
parents: 2311
diff changeset
14 ##
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe]
jwe
parents: 2311
diff changeset
15 ## Octave is distributed in the hope that it will be useful, but
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe]
jwe
parents: 2311
diff changeset
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
18 ## GNU General Public License for more details.
2313
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe]
jwe
parents: 2311
diff changeset
19 ##
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe]
jwe
parents: 2311
diff changeset
20 ## You should have received a copy of the GNU General Public License
7016
93c65f2a5668 [project @ 2007-10-12 06:40:56 by jwe]
jwe
parents: 6046
diff changeset
21 ## along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
22 ## <https://www.gnu.org/licenses/>.
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
23 ##
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
24 ########################################################################
1597
cf77ebb2719b [project @ 1995-11-01 00:48:17 by jwe]
jwe
parents:
diff changeset
25
3458
d25bc039237b [project @ 2000-01-19 09:36:14 by jwe]
jwe
parents: 3446
diff changeset
26 ## -*- texinfo -*-
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
27 ## @deftypefn {} {@var{k} =} polyder (@var{p})
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
28 ## @deftypefnx {} {@var{k} =} polyder (@var{a}, @var{b})
20852
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20231
diff changeset
29 ## @deftypefnx {} {[@var{q}, @var{d}] =} polyder (@var{b}, @var{a})
12803
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
30 ## Return the coefficients of the derivative of the polynomial whose
20165
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
31 ## coefficients are given by the vector @var{p}.
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
32 ##
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
33 ## If a pair of polynomials is given, return the derivative of the product
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
34 ## @math{@var{a}*@var{b}}.
20181
aa36fb998a4d maint: Remove unnecessary whitespace at end of lines.
Rik <rik@octave.org>
parents: 20165
diff changeset
35 ##
12803
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
36 ## If two inputs and two outputs are given, return the derivative of the
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
37 ## polynomial quotient @math{@var{b}/@var{a}}. The quotient numerator is
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
38 ## in @var{q} and the denominator in @var{d}.
14104
614505385171 doc: Overhaul docstrings for polynomial functions.
Rik <octave@nomad.inbox5.com>
parents: 12803
diff changeset
39 ## @seealso{polyint, polyval, polyreduce}
3458
d25bc039237b [project @ 2000-01-19 09:36:14 by jwe]
jwe
parents: 3446
diff changeset
40 ## @end deftypefn
1597
cf77ebb2719b [project @ 1995-11-01 00:48:17 by jwe]
jwe
parents:
diff changeset
41
11469
c776f063fefe Overhaul m-script files to use common variable name between code and documentation.
Rik <octave@nomad.inbox5.com>
parents: 10687
diff changeset
42 function [q, d] = polyder (p, a)
1597
cf77ebb2719b [project @ 1995-11-01 00:48:17 by jwe]
jwe
parents:
diff changeset
43
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
44 if (nargin < 1)
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
45 print_usage ();
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
46 endif
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
47
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
48 if (! isvector (p))
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
49 error ("polyder: argument must be a vector");
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
50 endif
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
51 if (nargin == 2)
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
52 if (! isvector (a))
12803
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
53 error ("polyder: argument must be a vector");
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
54 endif
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
55 if (nargout == 1)
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
56 ## derivative of p*a returns a single polynomial
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
57 q = polyder (conv (p, a));
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
58 else
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
59 ## derivative of p/a returns numerator and denominator
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
60 d = conv (a, a);
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
61 if (numel (p) == 1)
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
62 q = -p * polyder (a);
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
63 elseif (numel (a) == 1)
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
64 q = a * polyder (p);
12803
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
65 else
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
66 q = conv (polyder (p), a) - conv (p, polyder (a));
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
67 q = polyreduce (q);
12803
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
68 endif
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
69
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
70 ## remove common factors from numerator and denominator
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
71 x = polygcd (q, d);
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
72 if (length (x) != 1)
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
73 q = deconv (q, x);
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
74 d = deconv (d, x);
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
75 endif
12803
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
76
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
77 ## move all the gain into the numerator
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
78 q /= d(1);
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
79 d /= d(1);
5216
5ed60b8b1ac4 [project @ 2005-03-16 19:51:39 by jwe]
jwe
parents: 3458
diff changeset
80 endif
1597
cf77ebb2719b [project @ 1995-11-01 00:48:17 by jwe]
jwe
parents:
diff changeset
81 else
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
82 lp = numel (p);
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
83 if (lp == 1)
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
84 q = 0;
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
85 return;
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
86 elseif (lp == 0)
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
87 q = [];
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
88 return;
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
89 endif
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
90
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
91 ## Force P to be a row vector.
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
92 p = p(:).';
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
93
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
94 q = p(1:(lp-1)) .* [(lp-1):-1:1];
1597
cf77ebb2719b [project @ 1995-11-01 00:48:17 by jwe]
jwe
parents:
diff changeset
95 endif
cf77ebb2719b [project @ 1995-11-01 00:48:17 by jwe]
jwe
parents:
diff changeset
96
cf77ebb2719b [project @ 1995-11-01 00:48:17 by jwe]
jwe
parents:
diff changeset
97 endfunction
12803
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
98
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
99
14363
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
100 %!assert (polyder ([1, 2, 3], [2, 2]))
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
101 %!assert (polyder (13), 0)
12803
b7a6a3644f3b codesprint: Deprecate polyderiv.m
Rik <octave@nomad.inbox5.com>
parents: 11523
diff changeset
102
14363
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
103 %!error polyder ([])
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
104 %!error polyder (1,2,3)
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
105 %!error <argument must be a vector> polyder ([1, 2; 3, 4])