Mercurial > octave

comparison libinterp/corefcn/sysdep.cc @ 30888:32d2b6604a9f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Ensure documentation lists output argument when it exists for functions in libinterp/ 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. * __ftp__.cc, __magick_read__.cc, __pchip_deriv__.cc, bitfcns.cc, bsxfun.cc, call-stack.cc, cellfun.cc, chol.cc, conv2.cc, data.cc, debug.cc, defaults.cc, det.cc, dirfns.cc, display.cc, dot.cc, error.cc, event-manager.cc, fft.cc, fft2.cc, fftn.cc, file-io.cc, getgrent.cc, getpwent.cc, getrusage.cc, graphics.cc, hash.cc, help.cc, input.cc, interpreter.cc, kron.cc, load-path.cc, mappers.cc, max.cc, nproc.cc, oct-hist.cc, pager.cc, pinv.cc, psi.cc, rand.cc, settings.cc, sighandlers.cc, stream-euler.cc, strfns.cc, symtab.cc, syscalls.cc, sysdep.cc, time.cc, toplev.cc, utils.cc, variables.cc, __fltk_uigetfile__.cc, audiodevinfo.cc, audioread.cc, fftw.cc, ov-bool-mat.cc, ov-cell.cc, ov-class.cc, ov-classdef.cc, ov-fcn-handle.cc, ov-java.cc, ov-struct.cc, ov-typeinfo.cc, ov-usr-fcn.cc, ov.cc, octave.cc, profiler.cc: Add return arguments to @deftypefn macros where they were missing. Attempt to use standard naming convention for return variables. Occasionally improved the docstring itself by re-wording or adding code examples.
author Rik <rik@octave.org>
date Mon, 04 Apr 2022 10:31:48 -0700
parents f1cec1134dd1
children 670a0d878af1
comparison
equal deleted inserted replaced
30887:4bab8d3fce79 30888:32d2b6604a9f
189 #endif 189 #endif
190 } 190 }
191 191
192 DEFUN (__open_with_system_app__, args, , 192 DEFUN (__open_with_system_app__, args, ,
193 doc: /* -*- texinfo -*- 193 doc: /* -*- texinfo -*-
194 @deftypefn {} {} __open_with_system_app__ (@var{file}) 194 @deftypefn {} {@var{status} =} __open_with_system_app__ (@var{file})
195 Internal function. Returns 1 on successful system call and 0 otherwise. 195 Return 1 on successful system call and 0 otherwise.
196 @end deftypefn */) 196 @end deftypefn */)
197 { 197 {
198 if (args.length () != 1) 198 if (args.length () != 1)
199 print_usage (); 199 print_usage ();
200 200
817 817
818 DEFALIAS (home, clc); 818 DEFALIAS (home, clc);
819 819
820 DEFUN (getenv, args, , 820 DEFUN (getenv, args, ,
821 doc: /* -*- texinfo -*- 821 doc: /* -*- texinfo -*-
822 @deftypefn {} {} getenv (@var{var}) 822 @deftypefn {} {@var{val} =} getenv ("@var{var}")
823 Return the value of the environment variable @var{var}. 823 Return the value of the environment variable @var{var}.
824 824
825 For example, 825 For example,
826 826
827 @example 827 @example
845 %!assert (ischar (getenv ("OCTAVE_HOME"))) 845 %!assert (ischar (getenv ("OCTAVE_HOME")))
846 */ 846 */
847 847
848 DEFUN (setenv, args, , 848 DEFUN (setenv, args, ,
849 doc: /* -*- texinfo -*- 849 doc: /* -*- texinfo -*-
850 @deftypefn {} {} setenv (@var{var}, @var{value}) 850 @deftypefn {} {} setenv ("@var{var}", @var{value})
851 @deftypefnx {} {} setenv (@var{var}) 851 @deftypefnx {} {} setenv (@var{var})
852 @deftypefnx {} {} putenv (@dots{}) 852 @deftypefnx {} {} putenv (@dots{})
853 Set the value of the environment variable @var{var} to @var{value}. 853 Set the value of the environment variable @var{var} to @var{value}.
854 854
855 If no @var{value} is specified then the variable will be assigned the null 855 If no @var{value} is specified then the variable will be assigned the null
856 string. 856 string.
857
858 Programming Note: @code{putenv} is an alias for @code{setenv} and can be used
859 interchangeably.
857 @seealso{unsetenv, getenv} 860 @seealso{unsetenv, getenv}
858 @end deftypefn */) 861 @end deftypefn */)
859 { 862 {
860 int nargin = args.length (); 863 int nargin = args.length ();
861 864
1207 1210
1208 // FIXME: perhaps kbhit should also be able to print a prompt? 1211 // FIXME: perhaps kbhit should also be able to print a prompt?
1209 1212
1210 DEFMETHOD (kbhit, interp, args, , 1213 DEFMETHOD (kbhit, interp, args, ,
1211 doc: /* -*- texinfo -*- 1214 doc: /* -*- texinfo -*-
1212 @deftypefn {} {} kbhit () 1215 @deftypefn {} {@var{c} =} kbhit ()
1213 @deftypefnx {} {} kbhit (1) 1216 @deftypefnx {} {@var{c} =} kbhit (1)
1214 Read a single keystroke from the keyboard. 1217 Read a single keystroke from the keyboard.
1215 1218
1216 If called with an argument, don't wait for a keypress. 1219 If called with an argument (typically 1), don't wait for a keypress and
1220 immediately return the next keystroke in the keyboard input buffer or an empty
1221 string ("") if no keystroke is available.
1217 1222
1218 For example, 1223 For example,
1219 1224
1220 @example 1225 @example
1221 x = kbhit (); 1226 c = kbhit ();
1222 @end example 1227 @end example
1223 1228
1224 @noindent 1229 @noindent
1225 will set @var{x} to the next character typed at the keyboard as soon as 1230 will set @var{c} to the next character typed at the keyboard as soon as it is
1226 it is typed. 1231 typed.
1227 1232
1228 @example 1233 @example
1229 x = kbhit (1); 1234 c = kbhit (1);
1230 @end example 1235 @end example
1231 1236
1232 @noindent 1237 @noindent
1233 is identical to the above example, but doesn't wait for a keypress, 1238 is identical to the above example, but doesn't wait for a keypress, returning
1234 returning the empty string if no key is available. 1239 the empty string if no key is available.
1235 @seealso{input, pause} 1240 @seealso{input, pause}
1236 @end deftypefn */) 1241 @end deftypefn */)
1237 { 1242 {
1238 // FIXME: add timeout and default value args? 1243 // FIXME: add timeout and default value args?
1239 1244
1270 tic; pause (0.05); toc 1275 tic; pause (0.05); toc
1271 @print{} Elapsed time is 0.05039 seconds. 1276 @print{} Elapsed time is 0.05039 seconds.
1272 @end group 1277 @end group
1273 @end example 1278 @end example
1274 1279
1275 The following example prints a message and then waits 5 seconds before 1280 The following example prints a message and then waits 5 seconds before clearing
1276 clearing the screen. 1281 the screen.
1277 1282
1278 @example 1283 @example
1279 @group 1284 @group
1280 disp ("wait please..."); 1285 disp ("wait please...");
1281 pause (5); 1286 pause (5);
1379 %!assert (islogical (isieee ())) 1384 %!assert (islogical (isieee ()))
1380 */ 1385 */
1381 1386
1382 DEFUN (native_float_format, , , 1387 DEFUN (native_float_format, , ,
1383 doc: /* -*- texinfo -*- 1388 doc: /* -*- texinfo -*-
1384 @deftypefn {} {} native_float_format () 1389 @deftypefn {} {@var{fmtstr} =} native_float_format ()
1385 Return the native floating point format as a string. 1390 Return the native floating point format as a string.
1386 @end deftypefn */) 1391 @end deftypefn */)
1387 { 1392 {
1388 mach_info::float_format flt_fmt = mach_info::native_float_format (); 1393 mach_info::float_format flt_fmt = mach_info::native_float_format ();
1389 1394
1394 %!assert (ischar (native_float_format ())) 1399 %!assert (ischar (native_float_format ()))
1395 */ 1400 */
1396 1401
1397 DEFUN (tilde_expand, args, , 1402 DEFUN (tilde_expand, args, ,
1398 doc: /* -*- texinfo -*- 1403 doc: /* -*- texinfo -*-
1399 @deftypefn {} {} tilde_expand (@var{string}) 1404 @deftypefn {} {@var{newstr} =} tilde_expand (@var{string})
1400 @deftypefnx {} {} tilde_expand (@var{cellstr}) 1405 @deftypefnx {} {@var{newcstr} =} tilde_expand (@var{cellstr})
1401 Perform tilde expansion on @var{string}. 1406 Perform tilde expansion on @var{string}.
1402 1407
1403 If @var{string} begins with a tilde character, (@samp{~}), all of the 1408 If @var{string} begins with a tilde character, (@samp{~}), all of the
1404 characters preceding the first slash (or all characters, if there is no 1409 characters preceding the first slash (or all characters, if there is no
1405 slash) are treated as a possible user name, and the tilde and the following 1410 slash) are treated as a possible user name, and the tilde and the following
1467 %! endif 1472 %! endif
1468 */ 1473 */
1469 1474
1470 DEFUN (__blas_version__, , , 1475 DEFUN (__blas_version__, , ,
1471 doc: /* -*- texinfo -*- 1476 doc: /* -*- texinfo -*-
1472 @deftypefn {} {} __blas_version__ () 1477 @deftypefn {} {@var{verstr} =} __blas_version__ ()
1473 Undocumented internal function. 1478 Undocumented internal function.
1474 @end deftypefn */) 1479 @end deftypefn */)
1475 { 1480 {
1476 return ovl (sys::blas_version ()); 1481 return ovl (sys::blas_version ());
1477 } 1482 }
1478 1483
1479 DEFUN (__lapack_version__, , , 1484 DEFUN (__lapack_version__, , ,
1480 doc: /* -*- texinfo -*- 1485 doc: /* -*- texinfo -*-
1481 @deftypefn {} {} __lapack_version__ () 1486 @deftypefn {} {@var{verstr} =} __lapack_version__ ()
1482 Undocumented internal function. 1487 Undocumented internal function.
1483 @end deftypefn */) 1488 @end deftypefn */)
1484 { 1489 {
1485 return ovl (sys::lapack_version ()); 1490 return ovl (sys::lapack_version ());
1486 } 1491 }