Mercurial > octave
view scripts/miscellaneous/nargoutchk.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 | 597f3ee61a48 |
line wrap: on
line source
######################################################################## ## ## Copyright (C) 2008-2022 The Octave Project Developers ## ## See the file COPYRIGHT.md in the top-level directory of this ## distribution or <https://octave.org/copyright/>. ## ## This file is part of Octave. ## ## Octave is free software: you can redistribute it and/or modify it ## under the terms of the GNU General Public License as published by ## the Free Software Foundation, either version 3 of the License, or ## (at your option) any later version. ## ## Octave is distributed in the hope that it will be useful, but ## WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ## GNU General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with Octave; see the file COPYING. If not, see ## <https://www.gnu.org/licenses/>. ## ######################################################################## ## -*- texinfo -*- ## @deftypefn {} {} nargoutchk (@var{minargs}, @var{maxargs}) ## @deftypefnx {} {@var{msgstr} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs}) ## @deftypefnx {} {@var{msgstr} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs}, "string") ## @deftypefnx {} {@var{msgstruct} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs}, "struct") ## Check for correct number of output arguments. ## ## In the first form, return an error if the number of arguments is not between ## @var{minargs} and @var{maxargs}. Otherwise, do nothing. Note that this ## function evaluates the value of @code{nargout} on the caller so its value ## must have not been tampered with. ## ## Both @var{minargs} and @var{maxargs} must be numeric scalars. Zero, Inf, ## and negative are all valid, and they can have the same value. ## ## For backwards compatibility, the other forms return an appropriate error ## message string (or structure) if the number of outputs requested is ## invalid. ## ## This is useful for checking to that the number of output arguments supplied ## to a function is within an acceptable range. ## @seealso{narginchk, error, nargout, nargin} ## @end deftypefn function msg = nargoutchk (minargs, maxargs, nargs, outtype) ## Before Matlab 2011b, nargoutchk would return an error message (just the ## message in a string). With 2011b, it no longer returns anything, it ## simply gives an error if the args number is incorrect. ## To try to keep compatibility with both versions, check nargout and nargin ## to guess if the caller is expecting a value (old syntax) or none ## (new syntax). if (nargout == 1 && (nargin == 3 || nargin == 4)) if (minargs > maxargs) error ("nargoutchk: MINARGS must be <= MAXARGS"); elseif (nargin == 3) outtype = "string"; elseif (! any (strcmpi (outtype, {"string" "struct"}))) error ("nargoutchk: output type must be either string or struct"); elseif (! (isscalar (minargs) && isscalar (maxargs) && isscalar (nargs))) error ("nargoutchk: MINARGS, MAXARGS, and NARGS must be scalars"); endif msg = struct ("message", "", "identifier", ""); if (nargs < minargs) msg.message = "not enough output arguments"; msg.identifier = "Octave:nargoutchk:not-enough-outputs"; elseif (nargs > maxargs) msg.message = "too many output arguments"; msg.identifier = "Octave:nargoutchk:too-many-outputs"; endif if (strcmpi (outtype, "string")) msg = msg.message; elseif (isempty (msg.message)) ## Compatibility: Matlab returns a 0x1 empty struct when nargoutchk passes msg = resize (msg, 0, 1); endif elseif (nargout == 0 && nargin == 2) if (! isnumeric (minargs) || ! isscalar (minargs)) error ("nargoutchk: MINARGS must be a numeric scalar"); elseif (! isnumeric (maxargs) || ! isscalar (maxargs)) error ("nargoutchk: MAXARGS must be a numeric scalar"); elseif (minargs > maxargs) error ("nargoutchk: MINARGS cannot be larger than MAXARGS"); endif args = evalin ("caller", "nargout;"); if (args < minargs) error ("nargoutchk: Not enough output arguments"); elseif (args > maxargs) error ("nargoutchk: Too many output arguments"); endif else print_usage (); endif endfunction %!shared stnul, stmin, stmax %! stnul = resize (struct ("message", "", "identifier", ""), 0, 1); %! stmin = struct ("message", "not enough output arguments", %! "identifier", "Octave:nargoutchk:not-enough-outputs"); %! stmax = struct ("message", "too many output arguments", %! "identifier", "Octave:nargoutchk:too-many-outputs"); %!assert (nargoutchk (0, 1, 0), "") %!assert (nargoutchk (0, 1, 1), "") %!assert (nargoutchk (1, 1, 0), "not enough output arguments") %!assert (nargoutchk (0, 1, 2), "too many output arguments") %!assert (nargoutchk (0, 1, 2, "string"), "too many output arguments") ## Struct outputs %!assert (nargoutchk (0, 1, 0, "struct"), stnul) %!assert (nargoutchk (0, 1, 1, "struct"), stnul) %!assert (nargoutchk (1, 1, 0, "struct"), stmin) %!assert (nargoutchk (0, 1, 2, "struct"), stmax)