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).

--- a/scripts/sparse/treelayout.m	Wed Mar 30 17:30:18 2022 -0700
+++ b/scripts/sparse/treelayout.m	Wed Mar 30 20:40:27 2022 -0700
@@ -24,21 +24,21 @@
 ########################################################################
 
 ## -*- texinfo -*-
-## @deftypefn  {} {} treelayout (@var{tree})
-## @deftypefnx {} {} treelayout (@var{tree}, @var{permutation})
+## @deftypefn  {} {[@var{x}, @var{y}] =} treelayout (@var{tree})
+## @deftypefnx {} {[@var{x}, @var{y}] =} treelayout (@var{tree}, @var{permutation})
+## @deftypefnx {} {[@var{x}, @var{y}, @var{h}, @var{s}] =} treelayout (@dots{})
 ## treelayout lays out a tree or a forest.
 ##
 ## The first argument @var{tree} is a vector of predecessors.
 ##
-## The parameter @var{permutation} is an optional postorder permutation.
+## The optional parameter @var{permutation} is a postorder permutation.
 ##
 ## The complexity of the algorithm is O(n) in terms of time and memory
 ## requirements.
 ## @seealso{etreeplot, gplot, treeplot}
 ## @end deftypefn
 
-function [x_coordinate, y_coordinate, height, s] = ...
-                                                 treelayout (tree, permutation)
+function [x, y, h, s] = treelayout (tree, permutation)
 
   if (nargin < 1)
     print_usage ();
@@ -162,7 +162,7 @@
     ## If there is not any descendant of "parent node":
     if (stk(end,2) != par_number)
      left_most += 1;
-     x_coordinate_r(par_number) = left_most;
+     x_r(par_number) = left_most;
      max_ht = min (max_ht, level);
      if (length (stk) > 1 && find ((circshift (stk,1) - stk) == 0) > 1
          && stk(end,2) != stk(end-1,2))
@@ -181,7 +181,7 @@
 
         ## The level have to be decreased.
 
-        x_coordinate_r(par_number_vec) = left_most;
+        x_r(par_number_vec) = left_most;
         stk(position:end,:) = [];
       endif
 
@@ -192,8 +192,8 @@
       par_number = stk(end,1);
       ## If there is another branch start to search it.
       if (par_number != -1)
-        y_coordinate(par_number) = level;
-        x_coordinate_l(par_number) = left_most + 1;
+        y(par_number) = level;
+        x_l(par_number) = left_most + 1;
       endif
     else
 
@@ -201,16 +201,16 @@
       ## them and go on through it.
       level -= 1;
       par_number = stk(end,1);
-      y_coordinate(par_number) = level;
-      x_coordinate_l(par_number) = left_most + 1;
+      y(par_number) = level;
+      x_l(par_number) = left_most + 1;
     endif
   endwhile
 
   ## Calculate the x coordinates (the known values are the position
   ## of most left and most right descendants).
-  x_coordinate = (x_coordinate_l + x_coordinate_r) / 2;
+  x = (x_l + x_r) / 2;
 
-  height = num_nodes - max_ht - 1;
+  h = num_nodes - max_ht - 1;
 
 endfunction