Mercurial > hg > octave-nkf
changeset 19713:fc85d9026bb6
doc fixes for audio functions
* audiodevinfo.cc, audioread.cc: Style fixes for docstrings.
author | John W. Eaton <jwe@octave.org> |
---|---|
date | Fri, 02 Jan 2015 11:42:04 -0500 |
parents | 0f7788e2d677 |
children | 22e2f11424b3 |
files | libinterp/dldfcn/audiodevinfo.cc libinterp/dldfcn/audioread.cc |
diffstat | 2 files changed, 37 insertions(+), 61 deletions(-) [+] |
line wrap: on
line diff
--- a/libinterp/dldfcn/audiodevinfo.cc +++ b/libinterp/dldfcn/audiodevinfo.cc @@ -64,45 +64,33 @@ "-*- texinfo -*-\n\ @deftypefn {Loadable Function} {@var{devinfo} =} audiodevinfo ()\n\ \n\ -Returns a structure with two fields called \"input\" and \"output\".\n\ -Each structure contains an array of structures with three fields called\n\ -\"Name\", \"DriverVersion\" and \"ID\". Each structure contains information\n\ -about a PortAudio device.\n\ -\n\ -@end deftypefn\n\ -\n\ -@deftypefn {Loadable Function} {@var{devs} =} audiodevinfo (@var{io})\n\ +@deftypefnx {Loadable Function} {@var{devs} =} audiodevinfo (@var{io})\n\ +@deftypefnx {Loadable Function} {@var{name} =} audiodevinfo (@var{io}, @var{id})\n\ +@deftypefnx {Loadable Function} {@var{id} =} audiodevinfo (@var{io}, @var{name})\n\ +@deftypefnx {Loadable Function} {@var{id} =} audiodevinfo (@var{io}, @var{rate}, @var{bits}, @var{chans})\n\ \n\ -Returns the number of input or output devices available. Set @var{io} to 1\n\ -for input devices and to 0 for output devices.\n\ -@end deftypefn\n\ +@deftypefnx {Loadable Function} {@var{supports} =} audiodevinfo (@var{io}, @var{id}, @var{rate}, @var{bits}, @var{chans})\n\ \n\ -@deftypefn {Loadable Function} {@var{name} =} audiodevinfo (@var{io}, @var{id})\n\ +Return a structure with fields \"input\" and \"output\".\n\ +The value of each field is a structure array with fields\n\ +\"Name\", \"DriverVersion\" and \"ID\" describing an audio device.\n\ \n\ -Returns the name of a device specified by numerical @var{id}. Set @var{io}\n\ -to 1 for input devices and to 0 for output devices.\n\ -@end deftypefn\n\ \n\ -@deftypefn {Loadable Function} {@var{id} =} audiodevinfo (@var{io}, @var{name})\n\ +If the optional argument @var{io} is 1, return information about input\n\ +devices only. If it is 0, return information about output devices only.\n\ \n\ -Returns the id of a device specified by name. Set @var{io}\n\ -to 1 for input devices and to 0 for output devices.\n\ -@end deftypefn\n\ -\n\ -@deftypefn {Loadable Function} {@var{id} =} audiodevinfo (@var{io}, @var{rate}, @var{bits}, @var{chans})\n\ +If the optional argument @var{id} is provided, return information about\n\ +corresponding device.\n\ \n\ -Returns the id of the first device that supports playback or recording\n\ -using the specified sampling rate (@var{rate}), bits per sample (@var{bits})\n\ -and number of channels (@var{chans}). Set @var{io} to 1 for input devices\n\ -and to 0 for output devices.\n\ -@end deftypefn\n\ +If the optional argument @var{name} is provided, return the id of the\n\ +named device.\n\ \n\ -@deftypefn {Loadable Function} {@var{supports} =} audiodevinfo (@var{io}, @var{id}, @var{rate}, @var{bits}, @var{chans})\n\ +Given a sampling rate, bits per sample, and number of channels for\n\ +an input or output device, return the ID of the first device that\n\ +supports playback or recording using the specified parameters.\n\ \n\ -Returns 1 if the device bearing @var{id} supports specified sampling rate\n\ -(@var{rate}), bits per sample (@var{bits}) and number of channels (@var{chans}).\n\ -Returns 0 otherwise. Set @var{io} to 1 for input devices and to 0 for output\n\ -devices.\n\ +If also given a device ID, return true if the device supports playback\n\ +or recording using those parameters.\n\ @end deftypefn") { octave_value retval;
--- a/libinterp/dldfcn/audioread.cc +++ b/libinterp/dldfcn/audioread.cc @@ -43,34 +43,24 @@ DEFUN_DLD (audioread, args, , "-*- texinfo -*-\n\ @deftypefn {Loadable Function} {[@var{y}, @var{fs}] =} audioread (@var{filename})\n\ -\n\ -Load an audio file that is specified by @var{filename}. It will be loaded\n\ -in to a column matrix with as many rows as there are audio frames and as many\n\ -columns as there are channels in the file. Sampling rate will be stored in\n\ -@var{fs}.\n\ -\n\ -@end deftypefn\n\ -@deftypefn {Loadable Function} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples})\n\ +@deftypefnx {Loadable Function} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples})\n\ \n\ -Read a specified range of samples from a file specified by @var{filename}.\n\ -Argument @var{samples} is a vector with two values specifying starting frame\n\ -and ending frame.\n\ -\n\ -@end deftypefn\n\ -@deftypefn {Loadable Function} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{datatype})\n\ +@deftypefnx {Loadable Function} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{datatype})\n\ +@deftypefnx {Loadable Function} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples}, @var{datatype})\n\ +Read the audio file @var{filename} and return the audio data and sampling\n\ +rate. The audio data is stored as matrix with rows corresponding\n\ +to audio frames and columns corresponding to channels.\n\ \n\ -Read a file and return an array of specified type. If @var{datatype} is\n\ -@qcode{\"native\"} then an array of fixed width integer type will be returned\n\ -depending on how data is stored in the audio file. If @var{datatype} is\n\ -@qcode{\"double\"} a double matrix will be returned.\n\ +The optional two-element vector argument @var{samples} specifies starting\n\ +and ending frames.\n\ \n\ -@end deftypefn\n\ -@deftypefn {Loadable Function} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples}, @var{datatype})\n\ +The optional argument @var{datatype} specifies the datatype to return.\n\ +If it is @qcode{\"native\"}, then the type of data depends on how the\n\ +data is stored in the audio file.\n\ \n\ Read a file and return a specified range of frames in an array of specified type.\n\ \n\ -@end deftypefn" -) +@end deftypefn") { octave_value_list retval; #ifdef HAVE_SNDFILE @@ -172,21 +162,19 @@ DEFUN_DLD (audiowrite, args, , "-*- texinfo -*-\n\ @deftypefn {Loadable Function} {} audiowrite (@var{filename}, @var{y}, @var{fs})\n\ -\n\ -Write audio data from the matrix @var{y} to a file specified by @var{filename},\n\ -file format will be determined by the file extension.\n\ +@deftypefnx {Loadable Function} {} audiowrite (@var{filename}, @var{y}, @var{fs}, @var{name}, @var{value}, @dots{})\n\ \n\ -@end deftypefn\n\ -@deftypefn {Loadable Function} {} audiowrite (@var{filename}, @var{y}, @var{fs}, @var{name}, @var{value})\n\ +Write audio data from the matrix @var{y} to @var{filename} with the file\n\ +format determined by the file extension.\n\ \n\ -Lets you specify additional parameters when writing the file. Those parameters\n\ -are given in the table below:\n\ +Additional name and value argument pairs may be used to specify the\n\ +following options:\n\ \n\ @table @samp\n\ @item BitsPerSample\n\ Number of bits per sample, valid values are 8, 16, 24 and 32. Default is 16.\n\ @item BitRate\n\ -Valid argument name, but ignored. Left for compatibility with MATLAB.\n\ +Valid argument name, but ignored. Left for compatibility with @sc{matlab}.\n\ @item Quality\n\ Quality setting for the Ogg Vorbis compressor. Values can range between 0 and 100 with 100 being the highest quality setting. Default is 75.\n\ @item Title\n\