[beast] BSE: docu cleanups
- From: Tim Janik <timj src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [beast] BSE: docu cleanups
- Date: Sun, 8 May 2011 12:54:51 +0000 (UTC)
commit a80d944b81200071da842f4c3b4cb018164deebf
Author: Tim Janik <timj gtk org>
Date: Sun May 8 14:38:56 2011 +0200
BSE: docu cleanups
bse/bsedatahandle-fir.cc | 28 +++---
bse/bseengine.c | 56 ++++++------
bse/bsejanitor.c | 8 +-
bse/bseserver.c | 12 ++--
bse/gslcommon.c | 13 +--
bse/gsldatahandle.c | 26 +++---
bse/gsldatautils.c | 37 ++++-----
bse/gslfft.h | 32 ++++----
bse/gslfilehash.c | 90 +++++++++-----------
bse/gslfilter.c | 212 ++++++++++++++++++++++-----------------------
10 files changed, 246 insertions(+), 268 deletions(-)
---
diff --git a/bse/bsedatahandle-fir.cc b/bse/bsedatahandle-fir.cc
index c772260..adff131 100644
--- a/bse/bsedatahandle-fir.cc
+++ b/bse/bsedatahandle-fir.cc
@@ -370,16 +370,17 @@ public:
using namespace Bse;
/**
+ * <pre>
* __________
* /
* /
- * /
- * _____/
+ * /|
+ * _____/ |
* |
* cutoff_freq
- *
- * @cutoff_freq: cutoff frequency in Hz in intervall [0..SR/2]
- * @order: number of filter coefficients
+ * </pre>
+ * @param cutoff_freq cutoff frequency in Hz in intervall [0..SR/2]
+ * @param order number of filter coefficients
*/
extern "C" GslDataHandle*
bse_data_handle_new_fir_highpass (GslDataHandle *src_handle,
@@ -391,16 +392,17 @@ bse_data_handle_new_fir_highpass (GslDataHandle *src_handle,
}
/**
- * ______
- * \
- * \
- * \
- * \__________
+ * <pre>
+ * ______
+ * \
+ * \
+ * |\
+ * | \ __________
* |
* cutoff_freq
- *
- * @cutoff_freq: cutoff frequency in Hz in intervall [0..SR/2]
- * @order: number of filter coefficients
+ * </pre>
+ * @param cutoff_freq cutoff frequency in Hz in intervall [0..SR/2]
+ * @param order number of filter coefficients
*/
extern "C" GslDataHandle*
bse_data_handle_new_fir_lowpass (GslDataHandle *src_handle,
diff --git a/bse/bseengine.c b/bse/bseengine.c
index 5fd68ac..97a710f 100644
--- a/bse/bseengine.c
+++ b/bse/bseengine.c
@@ -154,7 +154,7 @@ bse_module_is_scheduled (BseModule *module)
/**
* @param module The module to integrate
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job to integrate @a module into the engine.
* This function is MT-safe and may be called from any thread.
@@ -176,7 +176,7 @@ bse_job_integrate (BseModule *module)
/**
* @param module The module to discard
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which removes @a module from the
* engine and destroys it.
@@ -198,7 +198,7 @@ bse_job_discard (BseModule *module)
/**
* @param module Module with input streams
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which causes all connected input streams
* of @a module to be disconnected, like it's done upon discarding the module.
@@ -220,7 +220,7 @@ bse_job_kill_inputs (BseModule *module)
/**
* @param module Module with output streams
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which causes all connected output streams
* of @a module to be disconnected, like it's done upon discarding the module.
@@ -245,7 +245,7 @@ bse_job_kill_outputs (BseModule *module)
* @param src_ostream Index of output stream of @a src_module
* @param dest_module Module with unconnected input stream
* @param dest_istream Index of input stream of @a dest_module
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which connects the ouput stream @a src_ostream
* of module @a src_module to the input stream @a dest_istream of module @a dest_module
@@ -281,7 +281,7 @@ bse_job_connect (BseModule *src_module,
* @param src_ostream Index of output stream of @a src_module
* @param dest_module Module with unconnected joint input stream
* @param dest_jstream Index of joint input stream of @a dest_module
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which connects the ouput stream @a src_ostream
* of module @a src_module to the joint input stream @a dest_istream of module
@@ -314,7 +314,7 @@ bse_job_jconnect (BseModule *src_module,
/**
* @param dest_module Module with connected input stream
* @param dest_istream Index of input stream of @a dest_module
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which causes the input stream @a dest_istream
* of @a dest_module to be disconnected (it is an error if the input stream isn't
@@ -345,7 +345,7 @@ bse_job_disconnect (BseModule *dest_module,
* @param dest_jstream Index of input stream of @a dest_module
* @param src_module Module with output stream
* @param src_ostream Index of output stream of @a src_module
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which causes the joint input
* stream @a dest_jstream of @a dest_module to be disconnected from
@@ -396,7 +396,7 @@ bse_job_set_consumer (BseModule *module,
/**
* @param module The module to be reset
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Forces a reset of @a module before its next call to
* process(), if its class provides a reset()
@@ -422,7 +422,7 @@ bse_job_force_reset (BseModule *module)
}
/**
- * BseEngineAccessFunc
+ * \fn BseEngineAccessFunc
* @param module Module to operate on
* @param data Accessor data
*
@@ -437,7 +437,7 @@ bse_job_force_reset (BseModule *module)
* @param access_func The accessor function (executed in master thread)
* @param data Data passed in to the accessor
* @param free_func Function to free @a data (executed in user thread)
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which will invoke @a access_func
* on @a module with @a data when the transaction queue is processed
@@ -493,7 +493,7 @@ bse_engine_add_user_callback (gpointer data,
}
/**
- * BseEngineProbeFunc
+ * \fn BseEngineProbeFunc
* @param data user data passed in to bse_job_probe_request()
* @param n_values number of values probed
* @param tick_stamp engine time in microseconds of the probe
@@ -515,7 +515,7 @@ bse_engine_add_user_callback (gpointer data,
* @param module The module to access
* @param probe_func Function invoked with @a data in the user thread
* @param data Data passed in to the accessor
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which inserts @a probe_func with @a data
* into the job queue of @a module.
@@ -562,7 +562,7 @@ bse_job_probe_request (BseModule *module,
* @param access_func The accessor function
* @param data Data passed in to the accessor
* @param free_func Function to free @a data
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which inserts @a access_func
* with @a data into the flow job queue of @a module.
@@ -609,7 +609,7 @@ bse_job_flow_access (BseModule *module,
* @param access_func The accessor function
* @param data Data passed in to the accessor
* @param free_func Function to free @a data
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which inserts @a access_func
* with @a data into the boundary job queue of @a module.
@@ -660,7 +660,7 @@ bse_engine_boundary_discard (BseModule *module,
/**
* @param module The module to access
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Discard @a module at block boundaries, after all ordinary jobs
* have been processed. This job type should be used instead of
@@ -692,7 +692,7 @@ bse_job_boundary_discard (BseModule *module)
/**
* @param module Module not currently suspended
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which suspends the @a module
* and all it's input modules which don't have other non-suspended
@@ -718,7 +718,7 @@ bse_job_suspend_now (BseModule *module)
/**
* @param module Module to resume
* @param tick_stamp Sample tick at which to resume @a module
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which inserts a resumption
* event into the job queue of @a module.
@@ -747,14 +747,14 @@ bse_job_resume_at (BseModule *module,
}
/**
- * BseEnginePollFunc
+ * \fn BseEnginePollFunc
* @param data Data of poll function
* @param n_values Minimum number of values the engine wants to process
* @param timeout_p Location of timeout value
* @param n_fds Number of file descriptors used for polling
* @param fds File descriptors to be used for polling
* @param revents_filled Indicates whether @a fds actually have their ->revents field filled with valid data.
- * @param Returns A boolean value indicating whether the engine should process data right now
+ * @return A boolean value indicating whether the engine should process data right now
*
* The BseEnginePollFunc is a user supplied callback function which can be hooked into the
* BSE Engine. The engine uses the poll functions to determine whether processing of
@@ -774,7 +774,7 @@ bse_job_resume_at (BseModule *module,
* @param free_func Function to free @a data
* @param n_fds Number of poll file descriptors
* @param fds File descriptors to select(2) or poll(2) on
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which adds a poll function
* to the engine. The poll function is used by the engine to
@@ -808,7 +808,7 @@ bse_job_add_poll (BseEnginePollFunc poll_func,
/**
* @param poll_func Poll function to remove
* @param data Data of poll function
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which removes a previously inserted poll
* function from the engine.
@@ -837,7 +837,7 @@ bse_job_remove_poll (BseEnginePollFunc poll_func,
* @param timer_func Timer function to add
* @param data Data of timer function
* @param free_func Function to free @a data
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which adds a timer function
* to the engine. The timer function is called after the engine
@@ -864,7 +864,7 @@ bse_job_add_timer (BseEngineTimerFunc timer_func,
/**
* @param debug Debug message
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which issues @a debug message when
* the job is executed. This function is meant for debugging purposes
@@ -883,7 +883,7 @@ bse_job_debug (const gchar *debug)
}
/**
- * @param Returns New job suitable for bse_trans_add()
+ * @return New job suitable for bse_trans_add()
*
* Create a new transaction job which does nothing.
* The job enforces a roundtrip to the engine's master
@@ -902,7 +902,7 @@ bse_job_nop (void)
}
/**
- * @param Returns Newly opened empty transaction
+ * @return Newly opened empty transaction
*
* Open up a new transaction to commit jobs to the BSE Engine.
* While the distinct functions to operate on a transaction are
@@ -951,7 +951,7 @@ bse_trans_add (BseTrans *trans,
/**
* @param trans1 open transaction
* @param trans2 open transaction
- * @param Returns open transaction @a trans1
+ * @return open transaction @a trans1
*
* Merge two open transactions by appending the jobs of @a trans2
* to the jobs of @a trans1, returning the resulting transaction.
@@ -1328,7 +1328,7 @@ bse_engine_constrain (guint latency_ms,
* @param latency_ms calculation latency in milli seconds
* @param sample_freq mixing frequency
* @param control_freq frequency at which to check control values or 0
- * @param returns whether reconfiguration was successful
+ * @return whether reconfiguration was successful
*
* Reconfigure engine parameters. This function may only be called
* after engine initialization and can only succeed if no modules
diff --git a/bse/bsejanitor.c b/bse/bsejanitor.c
index 8270605..307871d 100644
--- a/bse/bsejanitor.c
+++ b/bse/bsejanitor.c
@@ -266,11 +266,11 @@ bse_janitor_get_ident (BseJanitor *self)
return self->port ? self->port->ident : NULL;
}
-/* bse_janitor_progress
- * @self: janitor object
- * @progress: progress value
+/**
+ * @param self janitor object
+ * @param progress progress value
*
- * Signal progress, @progress is either a value between 0 and 1
+ * Signal progress, @a progress is either a value between 0 and 1
* to indicate completion status or is -1 to indicate progress
* of unknown amount.
*/
diff --git a/bse/bseserver.c b/bse/bseserver.c
index 5bf3fbb..f6e7544 100644
--- a/bse/bseserver.c
+++ b/bse/bseserver.c
@@ -731,8 +731,8 @@ bse_server_discard_pcm_input_module (BseServer *self,
bse_server_close_devices (self);
}
-/* bse_server_script_start
- * @script_control: associated script control object
+/**
+ * @param script_control associated script control object
*
* Signal script invocation start.
*/
@@ -757,10 +757,10 @@ bse_server_registration (BseServer *server,
g_signal_emit (server, signal_registration, 0, rtype, what, error);
}
-/* bse_server_script_error
- * @script_name: name of the executed script
- * @proc_name: procedure name to execute
- * @reason: error condition
+/**
+ * @param script_name name of the executed script
+ * @param proc_name procedure name to execute
+ * @param reason error condition
*
* Signal script invocation error.
*/
diff --git a/bse/gslcommon.c b/bse/gslcommon.c
index 192460b..745ae6c 100644
--- a/bse/gslcommon.c
+++ b/bse/gslcommon.c
@@ -38,8 +38,7 @@ static guint global_tick_stamp_leaps = 0;
/* --- tick stamps --- */
static BirnetMutex global_tick_stamp_mutex = { 0, };
/**
- * gsl_tick_stamp
- * @RETURNS: GSL's execution tick stamp as unsigned 64bit integer
+ * @return GSL's execution tick stamp as unsigned 64bit integer
*
* Retrieve the global GSL tick counter stamp.
* GSL increments its global tick stamp at certain intervals,
@@ -50,7 +49,7 @@ static BirnetMutex global_tick_stamp_mutex = { 0, };
* sfi_thread_awake_before(). Tick stamp updating occours at
* GSL engine block processing boundaries, so code that can
* guarantee to not run across those boundaries (for instance
- * BseProcessFunc() functions) may use the macro %GSL_TICK_STAMP
+ * BseProcessFunc() functions) may use the macro GSL_TICK_STAMP
* to retrieve the current tick in a faster manner (not involving
* mutex locking). See also bse_module_tick_stamp().
* This function is MT-safe and may be called from any thread.
@@ -76,8 +75,7 @@ _gsl_tick_stamp_set_leap (guint ticks)
}
/**
- * gsl_tick_stamp_last
- * @RETURNS: Current tick stamp and system time in micro seconds
+ * @return Current tick stamp and system time in micro seconds
*
* Get the system time of the last GSL global tick stamp update.
* This function is MT-safe and may be called from any thread.
@@ -115,11 +113,10 @@ _gsl_tick_stamp_inc (void)
}
/**
- * gsl_thread_awake_before
- * @tick_stamp: tick stamp update to trigger wakeup
+ * @param tick_stamp tick stamp update to trigger wakeup
* Wakeup the currently running thread upon the last global tick stamp
* update (see gsl_tick_stamp()) that happens prior to updating the
- * global tick stamp to @tick_stamp.
+ * global tick stamp to @a tick_stamp.
* (If the moment of wakeup has already passed by, the thread is
* woken up at the next global tick stamp update.)
*/
diff --git a/bse/gsldatahandle.c b/bse/gsldatahandle.c
index bb942d4..329f394 100644
--- a/bse/gsldatahandle.c
+++ b/bse/gsldatahandle.c
@@ -1027,14 +1027,13 @@ gsl_data_handle_new_translate (GslDataHandle *src_handle,
}
/**
- * gsl_data_handle_new_cut
- * @src_handle: source GslDataHandle
- * @cut_offset: offset of gap into @src_handle
- * @n_cut_values: length of gap in @src_handle
- * @RETURNS: a newly created data handle
+ * @param src_handle source GslDataHandle
+ * @param cut_offset offset of gap into @a src_handle
+ * @param n_cut_values length of gap in @a src_handle
+ * @return a newly created data handle
*
- * Create a new data handle containing the contents of @src_handle
- * minus @n_cut_values at offset @cut_offset.
+ * Create a new data handle containing the contents of @a src_handle
+ * minus @a n_cut_values at offset @a cut_offset.
*/
GslDataHandle*
gsl_data_handle_new_cut (GslDataHandle *src_handle,
@@ -1045,14 +1044,13 @@ gsl_data_handle_new_cut (GslDataHandle *src_handle,
}
/**
- * gsl_data_handle_new_crop
- * @src_handle: source GslDataHandle
- * @n_head_cut: number of values to cut at data handle head
- * @n_tail_cut: number of values to cut at data handle tail
- * @RETURNS: a newly created data handle
+ * @param src_handle source GslDataHandle
+ * @param n_head_cut number of values to cut at data handle head
+ * @param n_tail_cut number of values to cut at data handle tail
+ * @return a newly created data handle
*
- * Create a new data handle containing the contents of @src_handle
- * minus @n_head_cut values at the start and @n_tail_cut values at
+ * Create a new data handle containing the contents of @a src_handle
+ * minus @a n_head_cut values at the start and @a n_tail_cut values at
* the end.
*/
GslDataHandle*
diff --git a/bse/gsldatautils.c b/bse/gsldatautils.c
index 0087247..d242137 100644
--- a/bse/gsldatautils.c
+++ b/bse/gsldatautils.c
@@ -655,12 +655,11 @@ gsl_data_find_tailmatch (GslDataHandle *dhandle,
}
/**
- * gsl_data_find_block
- * @handle: an open GslDataHandle
- * @n_values: amount of values to look for
- * @values: values to find
- * @epsilon: maximum difference upon comparisions
- * @RETURNS: position of values in data handle or -1
+ * @param handle an open GslDataHandle
+ * @param n_values amount of values to look for
+ * @param values values to find
+ * @param epsilon maximum difference upon comparisions
+ * @returns position of values in data handle or -1
*
* Find the position of a block of values within a
* data handle, where all values compare to the reference
@@ -702,15 +701,14 @@ gsl_data_find_block (GslDataHandle *handle,
}
/**
- * gsl_data_make_fade_ramp
- * @dhandle: valid and opened #GslDataHandle
- * @min_pos: position within @dhandle
- * @max_pos: position within @dhandle
- * @length_p: location to store the length of the fade ramp in
- * @RETURNS: newly allocated float block with fade ramp
- * Create a float value block of abs (@max_pos - @min_pos) values,
- * which contain a fade ramp of values from @dhandle, with @min_pos
- * indicating the minimum of the fade ramp and @max_pos indicating
+ * @param dhandle valid and opened GslDataHandle
+ * @param min_pos position within @a dhandle
+ * @param max_pos position within @a dhandle
+ * @param length_p location to store the length of the fade ramp in
+ * @return newly allocated float block with fade ramp
+ * Create a float value block of abs (@a max_pos - @a min_pos) values,
+ * which contain a fade ramp of values from @a dhandle, with @a min_pos
+ * indicating the minimum of the fade ramp and @a max_pos indicating
* its maximum.
*/
gfloat*
@@ -760,11 +758,10 @@ gsl_data_make_fade_ramp (GslDataHandle *handle,
}
/**
- * gsl_data_clip_sample
- * @dhandle: valid and opened #GslDataHandle
- * @cconfig: clip configuration
- * @result: clip result
- * @RETURNS: error code as stored in @result
+ * @param dhandle valid and opened GslDataHandle
+ * @param cconfig clip configuration
+ * @param result clip result
+ * @return error code as stored in @a result
* Clip silence at head and/or tail of a data handle
* according to a given threshold and optionally produce
* a fade ramp.
diff --git a/bse/gslfft.h b/bse/gslfft.h
index 78db780..f440f63 100644
--- a/bse/gslfft.h
+++ b/bse/gslfft.h
@@ -25,10 +25,10 @@ extern "C" {
/**
- * gsl_power2_fftac
- * @n_values: Number of complex values
- * @ri_values_in: Complex sample values [0..n_values*2-1]
- * @ri_values_out: Complex frequency values [0..n_values*2-1]
+ * @param n_values Number of complex values
+ * @param ri_values_in Complex sample values [0..n_values*2-1]
+ * @param ri_values_out Complex frequency values [0..n_values*2-1]
+ *
* This function performs a decimation in time fourier transformation
* in forward direction, where the input values are equidistant sampled
* data, and the output values contain the frequency proportions of the
@@ -60,10 +60,10 @@ void gsl_power2_fftac (const unsigned int n_values,
double *ri_values_out);
/**
- * gsl_power2_fftsc
- * @n_values: Number of complex values
- * @ri_values_in: Complex frequency values [0..n_values*2-1]
- * @ri_values_out: Complex sample values [0..n_values*2-1]
+ * @param n_values Number of complex values
+ * @param ri_values_in Complex frequency values [0..n_values*2-1]
+ * @param ri_values_out Complex sample values [0..n_values*2-1]
+ *
* This function performs a decimation in time fourier transformation
* in backwards direction with normalization. As such, this function
* represents the counterpart to gsl_power2_fftac(), that is, a value
@@ -85,10 +85,10 @@ void gsl_power2_fftsc (const unsigned int n_values,
double *ri_values_out);
/**
- * gsl_power2_fftar
- * @n_values: Number of real sample values
- * @r_values_in: Real sample values [0..n_values-1]
- * @ri_values_out: Complex frequency values [0..n_values-1]
+ * @param n_values Number of real sample values
+ * @param r_values_in Real sample values [0..n_values-1]
+ * @param ri_values_out Complex frequency values [0..n_values-1]
+ *
* Real valued variant of gsl_power2_fftac(), the input array contains
* real valued equidistant sampled data [0..n_values-1], and the output
* array contains the positive frequency half of the complex valued
@@ -115,10 +115,10 @@ void gsl_power2_fftar (const unsigned int n_values,
double *ri_values_out);
/**
- * gsl_power2_fftsr
- * @n_values: Number of real sample values
- * @ri_values_in: Complex frequency values [0..n_values-1]
- * @r_values_out: Real sample values [0..n_values-1]
+ * @param n_values Number of real sample values
+ * @param ri_values_in Complex frequency values [0..n_values-1]
+ * @param r_values_out Real sample values [0..n_values-1]
+ *
* Real valued variant of gsl_power2_fftsc(), counterpart to
* gsl_power2_fftar(), using the same frequency storage format.
* A real valued data set transformed into the frequency domain
diff --git a/bse/gslfilehash.c b/bse/gslfilehash.c
index 1fdb64e..5551436 100644
--- a/bse/gslfilehash.c
+++ b/bse/gslfilehash.c
@@ -89,15 +89,14 @@ stat_file (const gchar *file_name,
}
/**
- * gsl_hfile_open
- * @file_name: name of the file to open
- * @RETURNS: a new opened #GslHFile or NULL if an error occoured (errno set)
+ * @param file_name name of the file to open
+ * @returns a new opened GslHFile or NULL if an error occoured (errno set)
*
* Open a file for reading and return the associated GSL hashed file.
- * The motivation for using a #GslHFile over normal unix file
+ * The motivation for using a GslHFile over normal unix file
* descriptors is to reduce the amount of opened unix file descriptors and
* to ensure thread safety upon reading offset relative byte blocks.
- * Multiple open #GslHFiles with equal file names will share a
+ * Multiple open GslHFiles with equal file names will share a
* single unix file descriptor as long as the file wasn't modified meanwhile.
* This function is MT-safe and may be called from any thread.
*/
@@ -152,10 +151,9 @@ gsl_hfile_open (const gchar *file_name)
}
/**
- * gsl_hfile_close
- * @hfile: valid #GslHFile
+ * @param hfile valid GslHFile
*
- * Close and destroy a #GslHFile.
+ * Close and destroy a GslHFile.
* This function is MT-safe and may be called from any thread.
*/
void
@@ -195,12 +193,11 @@ gsl_hfile_close (GslHFile *hfile)
}
/**
- * gsl_hfile_pread
- * @hfile: valid GslHFile
- * @offset: offset in bytes within 0 and file end
- * @n_bytes: number of bytes to read
- * @bytes: buffer to store read bytes
- * @RETURNS: amount of bytes read or -1 if an error occoured (errno set)
+ * @param hfile valid GslHFile
+ * @param offset offset in bytes within 0 and file end
+ * @param n_bytes number of bytes to read
+ * @param bytes buffer to store read bytes
+ * @return amount of bytes read or -1 if an error occoured (errno set)
*
* Read a block of bytes from a GslHFile.
* This function is MT-safe and may be called from any thread.
@@ -274,9 +271,8 @@ gsl_hfile_pread (GslHFile *hfile,
}
/**
- * gsl_hfile_zoffset
- * @hfile: valid GslHFile
- * @RETURNS: offset of first zero byte or -1
+ * @param hfile valid GslHFile
+ * @return offset of first zero byte or -1
*
* Find the offset of the first zero byte in a GslHFile.
* This function is MT-safe and may be called from any thread.
@@ -339,9 +335,8 @@ gsl_hfile_zoffset (GslHFile *hfile)
}
/**
- * gsl_rfile_open
- * @file_name: name of the file to open
- * @RETURNS: a new opened #GslRFile or NULL if an error occoured (errno set)
+ * @param file_name name of the file to open
+ * @return a new opened #GslRFile or NULL if an error occoured (errno set)
*
* Open a file for reading and create a GSL read only file handle for it.
* The motivation for using a #GslRFile over normal unix files
@@ -366,11 +361,10 @@ gsl_rfile_open (const gchar *file_name)
}
/**
- * gsl_rfile_name
- * @rfile: valid #GslRFile
- * @RETURNS: the file name used to open this file
+ * @param rfile valid #GslRFile
+ * @return the file name used to open this file
*
- * Retrieve the file name used to open @rfile.
+ * Retrieve the file name used to open @a rfile.
*/
gchar*
gsl_rfile_name (GslRFile *rfile)
@@ -383,12 +377,11 @@ gsl_rfile_name (GslRFile *rfile)
}
/**
- * gsl_rfile_seek_set
- * @rfile: valid #GslRFile
- * @offset: new seek position within 0 and gsl_rfile_length()+1
- * @RETURNS: resulting position within 0 and gsl_rfile_length()+1
+ * @param rfile valid GslRFile
+ * @param offset new seek position within 0 and gsl_rfile_length()+1
+ * @return resulting position within 0 and gsl_rfile_length()+1
*
- * Set the current #GslRFile seek position.
+ * Set the current GslRFile seek position.
*/
GslLong
gsl_rfile_seek_set (GslRFile *rfile,
@@ -407,11 +400,10 @@ gsl_rfile_seek_set (GslRFile *rfile,
}
/**
- * gsl_rfile_position
- * @rfile: valid #GslRFile
- * @RETURNS: current position within 0 and gsl_rfile_length()
+ * @param rfile valid GslRFile
+ * @return current position within 0 and gsl_rfile_length()
*
- * Retrieve the current #GslRFile seek position.
+ * Retrieve the current GslRFile seek position.
*/
GslLong
gsl_rfile_position (GslRFile *rfile)
@@ -424,11 +416,10 @@ gsl_rfile_position (GslRFile *rfile)
}
/**
- * gsl_rfile_length
- * @rfile: valid #GslRFile
- * @RETURNS: total length of the #GslRFile in bytes
+ * @param rfile valid GslRFile
+ * @return total length of the GslRFile in bytes
*
- * Retrieve the file length of @rfile in bytes.
+ * Retrieve the file length of @a rfile in bytes.
*/
GslLong
gsl_rfile_length (GslRFile *rfile)
@@ -445,12 +436,11 @@ gsl_rfile_length (GslRFile *rfile)
}
/**
- * gsl_rfile_pread
- * @rfile: valid GslRFile
- * @offset: offset in bytes within 0 and gsl_rfile_length()
- * @n_bytes: number of bytes to read
- * @bytes: buffer to store read bytes
- * @RETURNS: amount of bytes read or -1 if an error occoured (errno set)
+ * @param rfile valid GslRFile
+ * @param offset offset in bytes within 0 and gsl_rfile_length()
+ * @param n_bytes number of bytes to read
+ * @param bytes buffer to store read bytes
+ * @return amount of bytes read or -1 if an error occoured (errno set)
*
* Read a block of bytes from a GslRFile at a specified position.
*/
@@ -467,11 +457,10 @@ gsl_rfile_pread (GslRFile *rfile,
}
/**
- * gsl_rfile_read
- * @rfile: valid GslRFile
- * @n_bytes: number of bytes to read
- * @bytes: buffer to store read bytes
- * @RETURNS: amount of bytes read or -1 if an error occoured (errno set)
+ * @param rfile valid GslRFile
+ * @param n_bytes number of bytes to read
+ * @param bytes buffer to store read bytes
+ * @return amount of bytes read or -1 if an error occoured (errno set)
*
* Read a block of bytes from a GslRFile from the current seek position
* and advance the seek position.
@@ -493,10 +482,9 @@ gsl_rfile_read (GslRFile *rfile,
}
/**
- * gsl_rfile_close
- * @rfile: valid #GslRFile
+ * @param rfile valid GslRFile
*
- * Close and destroy a #GslRFile.
+ * Close and destroy a GslRFile.
*/
void
gsl_rfile_close (GslRFile *rfile)
diff --git a/bse/gslfilter.c b/bse/gslfilter.c
index d70d40f..d9c3016 100644
--- a/bse/gslfilter.c
+++ b/bse/gslfilter.c
@@ -301,11 +301,11 @@ gsl_filter_tscheb2_rp (unsigned int iorder,
}
/**
- * gsl_filter_tscheb2_steepness_db
- * @iorder: filter order
- * @c_freq: passband cutoff frequency (0..pi)
- * @epsilon: fall off at passband frequency (0..1)
- * @stopband_db: reduction in stopband in dB (>= 0)
+ * @param iorder filter order
+ * @param c_freq passband cutoff frequency (0..pi)
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param stopband_db reduction in stopband in dB (>= 0)
+ *
* Calculates the steepness parameter for Tschebyscheff type 2 lowpass filter,
* based on the ripple residue in the stop band.
*/
@@ -319,11 +319,11 @@ gsl_filter_tscheb2_steepness_db (unsigned int iorder,
}
/**
- * gsl_filter_tscheb2_steepness
- * @iorder: filter order
- * @c_freq: passband cutoff frequency (0..pi)
- * @epsilon: fall off at passband frequency (0..1)
- * @residue: maximum of transfer function in stopband (0..1)
+ * @param iorder filter order
+ * @param c_freq passband cutoff frequency (0..pi)
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param residue maximum of transfer function in stopband (0..1)
+ *
* Calculates the steepness parameter for Tschebyscheff type 2 lowpass filter,
* based on ripple residue in the stop band.
*/
@@ -346,12 +346,12 @@ gsl_filter_tscheb2_steepness (unsigned int iorder,
/* --- lowpass filters --- */
/**
- * gsl_filter_butter_lp
- * @iorder: filter order
- * @freq: cutoff frequency (0..pi)
- * @epsilon: fall off at cutoff frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order
+ * @param freq cutoff frequency (0..pi)
+ * @param epsilon fall off at cutoff frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Butterworth lowpass filter.
*/
void
@@ -376,12 +376,12 @@ gsl_filter_butter_lp (unsigned int iorder,
}
/**
- * gsl_filter_tscheb1_lp
- * @iorder: filter order
- * @freq: cutoff frequency (0..pi)
- * @epsilon: fall off at cutoff frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order
+ * @param freq cutoff frequency (0..pi)
+ * @param epsilon fall off at cutoff frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Tschebyscheff type 1 lowpass filter.
*/
void
@@ -411,17 +411,17 @@ gsl_filter_tscheb1_lp (unsigned int iorder,
}
/**
- * gsl_filter_tscheb2_lp
- * @iorder: filter order
- * @freq: passband cutoff frequency (0..pi)
- * @steepness: frequency steepness (c_freq * steepness < pi)
- * @epsilon: fall off at passband frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order
+ * @param freq passband cutoff frequency (0..pi)
+ * @param steepness frequency steepness (c_freq * steepness < pi)
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Tschebyscheff type 2 lowpass filter.
* To gain a transition band between freq1 and freq2, pass arguements
- * @freq=freq1 and @steepness=freq2/freq1. To specify the transition
- * band width in fractions of octaves, pass @steepness=2^octave_fraction.
+ * @a freq=freq1 and @a steepness=freq2/freq1. To specify the transition
+ * band width in fractions of octaves, pass @a steepness=2^octave_fraction.
*/
void
gsl_filter_tscheb2_lp (unsigned int iorder,
@@ -450,12 +450,12 @@ gsl_filter_tscheb2_lp (unsigned int iorder,
/* --- highpass filters --- */
/**
- * gsl_filter_butter_hp
- * @iorder: filter order
- * @freq: passband frequency (0..pi)
- * @epsilon: fall off at passband frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order
+ * @param freq passband frequency (0..pi)
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Butterworth highpass filter.
*/
void
@@ -473,12 +473,12 @@ gsl_filter_butter_hp (unsigned int iorder,
}
/**
- * gsl_filter_tscheb1_hp
- * @iorder: filter order
- * @freq: passband frequency (0..pi)
- * @epsilon: fall off at passband frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order
+ * @param freq passband frequency (0..pi)
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Tschebyscheff type 1 highpass filter.
*/
void
@@ -496,13 +496,13 @@ gsl_filter_tscheb1_hp (unsigned int iorder,
}
/**
- * gsl_filter_tscheb2_hp
- * @iorder: filter order
- * @freq: stopband frequency (0..pi)
- * @steepness: frequency steepness
- * @epsilon: fall off at passband frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order
+ * @param freq stopband frequency (0..pi)
+ * @param steepness frequency steepness
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Tschebyscheff type 2 highpass filter.
*/
void
@@ -523,13 +523,13 @@ gsl_filter_tscheb2_hp (unsigned int iorder,
/* --- bandpass filters --- */
/**
- * gsl_filter_butter_bp
- * @iorder: filter order (must be even)
- * @freq1: stopband end frequency (0..pi)
- * @freq2: passband end frequency (0..pi)
- * @epsilon: fall off at passband frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order (must be even)
+ * @param freq1 stopband end frequency (0..pi)
+ * @param freq2 passband end frequency (0..pi)
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Butterworth bandpass filter.
*/
void
@@ -557,13 +557,13 @@ gsl_filter_butter_bp (unsigned int iorder,
}
/**
- * gsl_filter_tscheb1_bp
- * @iorder: filter order (must be even)
- * @freq1: stopband end frequency (0..pi)
- * @freq2: passband end frequency (0..pi)
- * @epsilon: fall off at passband frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order (must be even)
+ * @param freq1 stopband end frequency (0..pi)
+ * @param freq2 passband end frequency (0..pi)
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Tschebyscheff type 1 bandpass filter.
*/
void
@@ -591,14 +591,14 @@ gsl_filter_tscheb1_bp (unsigned int iorder,
}
/**
- * gsl_filter_tscheb2_bp
- * @iorder: filter order (must be even)
- * @freq1: stopband end frequency (0..pi)
- * @freq2: passband end frequency (0..pi)
- * @steepness: frequency steepness factor
- * @epsilon: fall off at passband frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order (must be even)
+ * @param freq1 stopband end frequency (0..pi)
+ * @param freq2 passband end frequency (0..pi)
+ * @param steepness frequency steepness factor
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Tschebyscheff type 2 bandpass filter.
*/
void
@@ -629,13 +629,13 @@ gsl_filter_tscheb2_bp (unsigned int iorder,
/* --- bandstop filters --- */
/**
- * gsl_filter_butter_bs
- * @iorder: filter order (must be even)
- * @freq1: passband end frequency (0..pi)
- * @freq2: stopband end frequency (0..pi)
- * @epsilon: fall off at passband frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order (must be even)
+ * @param freq1 passband end frequency (0..pi)
+ * @param freq2 stopband end frequency (0..pi)
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Butterworth bandstop filter.
*/
void
@@ -663,13 +663,13 @@ gsl_filter_butter_bs (unsigned int iorder,
}
/**
- * gsl_filter_tscheb1_bs
- * @iorder: filter order (must be even)
- * @freq1: passband end frequency (0..pi)
- * @freq2: stopband end frequency (0..pi)
- * @epsilon: fall off at passband frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order (must be even)
+ * @param freq1 passband end frequency (0..pi)
+ * @param freq2 stopband end frequency (0..pi)
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Tschebyscheff type 1 bandstop filter.
*/
void
@@ -697,14 +697,14 @@ gsl_filter_tscheb1_bs (unsigned int iorder,
}
/**
- * gsl_filter_tscheb2_bs
- * @iorder: filter order (must be even)
- * @freq1: passband end frequency (0..pi)
- * @freq2: stopband end frequency (0..pi)
- * @steepness: frequency steepness factor
- * @epsilon: fall off at passband frequency (0..1)
- * @a: root polynomial coefficients a[0..iorder]
- * @b: pole polynomial coefficients b[0..iorder]
+ * @param iorder filter order (must be even)
+ * @param freq1 passband end frequency (0..pi)
+ * @param freq2 stopband end frequency (0..pi)
+ * @param steepness frequency steepness factor
+ * @param epsilon fall off at passband frequency (0..1)
+ * @param a root polynomial coefficients a[0..iorder]
+ * @param b pole polynomial coefficients b[0..iorder]
+ *
* Tschebyscheff type 2 bandstop filter.
*/
void
@@ -853,16 +853,14 @@ gsl_blackman_window (double x)
}
/**
- * gsl_filter_fir_approx
- *
- * @iorder: order of the filter (must be oven, >= 2)
- * @freq: the frequencies of the transfer function
- * @value: the desired value of the transfer function
- * @interpolate_db: whether to interpolate the transfer function "value linear" or "dB linear"
+ * @param iorder order of the filter (must be oven, >= 2)
+ * @param freq the frequencies of the transfer function
+ * @param value the desired value of the transfer function
+ * @param interpolate_db whether to interpolate the transfer function "value linear" or "dB linear"
*
* Approximates a given transfer function with an iorder-coefficient FIR filter.
* It is recommended to provide enough frequency values, so that
- * @n_points >= @iorder.
+ * @a n_points >= @a iorder.
*/
void
gsl_filter_fir_approx (unsigned int iorder,
@@ -1305,13 +1303,11 @@ gsl_biquad_lphp_reso (GslBiquadFilter *c,
/* --- filter scanning -- */
/**
- * gsl_filter_sine_scan
- *
- * @order: order of the iir filter
- * @a: root polynomial coefficients of the filter a[0..order]
- * @b: pole polynomial coefficients of the filter b[0..order]
- * @freq: frequency to test
- * @mix_freq: the mixing frequency
+ * @param order order of the iir filter
+ * @param a root polynomial coefficients of the filter a[0..order]
+ * @param b pole polynomial coefficients of the filter b[0..order]
+ * @param freq frequency to test
+ * @param mix_freq the mixing frequency
*
* This function sends a sine signal of the desired frequency through an IIR
* filter, to test the value of the transfer function at a given point. It uses
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
