From 235aec0a757ff78e6d7f41f9bcd62357682f7e6f Mon Sep 17 00:00:00 2001 From: Andrew Eikum Date: Thu, 19 Jan 2012 12:36:09 +0100 Subject: [PATCH] Search-and-replace improve documentation language Signed-off-by: Takashi Iwai --- src/pcm/pcm.c | 146 +++++++++++++++++++++++++++------------------------------- 1 file changed, 67 insertions(+), 79 deletions(-) diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c index bc5c6e4a..dc91f79f 100644 --- a/src/pcm/pcm.c +++ b/src/pcm/pcm.c @@ -2882,15 +2882,14 @@ int snd_pcm_hw_params_dump(snd_pcm_hw_params_t *params, snd_output_t *out) } /** - * \brief Check, if hardware supports sample-resolution mmap for given configuration + * \brief Check if hardware supports sample-resolution mmap for given configuration * \param params Configuration space - * \return Boolean value * \retval 0 Hardware doesn't support sample-resolution mmap * \retval 1 Hardware supports sample-resolution mmap * - * The return value is always one when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_can_mmap_sample_resolution(const snd_pcm_hw_params_t *params) { @@ -2903,15 +2902,14 @@ int snd_pcm_hw_params_can_mmap_sample_resolution(const snd_pcm_hw_params_t *para } /** - * \brief Check, if hardware does double buffering for start/stop for given configuration + * \brief Check if hardware does double buffering for start/stop for given configuration * \param params Configuration space - * \return Boolean value * \retval 0 Hardware doesn't do double buffering for start/stop * \retval 1 Hardware does double buffering for start/stop * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_is_double(const snd_pcm_hw_params_t *params) { @@ -2924,15 +2922,14 @@ int snd_pcm_hw_params_is_double(const snd_pcm_hw_params_t *params) } /** - * \brief Check, if hardware does double buffering for data transfers for given configuration + * \brief Check if hardware does double buffering for data transfers for given configuration * \param params Configuration space - * \return Boolean value * \retval 0 Hardware doesn't do double buffering for data transfers * \retval 1 Hardware does double buffering for data transfers * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_is_batch(const snd_pcm_hw_params_t *params) { @@ -2945,15 +2942,14 @@ int snd_pcm_hw_params_is_batch(const snd_pcm_hw_params_t *params) } /** - * \brief Check, if hardware does block transfers for samples for given configuration + * \brief Check if hardware does block transfers for samples for given configuration * \param params Configuration space - * \return Boolean value * \retval 0 Hardware doesn't block transfers * \retval 1 Hardware does block transfers * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_is_block_transfer(const snd_pcm_hw_params_t *params) { @@ -2966,15 +2962,14 @@ int snd_pcm_hw_params_is_block_transfer(const snd_pcm_hw_params_t *params) } /** - * \brief Check, if timestamps are monotonic for given configuration + * \brief Check if timestamps are monotonic for given configuration * \param params Configuration space - * \return Boolean value * \retval 0 Device doesn't do monotomic timestamps * \retval 1 Device does monotonic timestamps * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_is_monotonic(const snd_pcm_hw_params_t *params) { @@ -2987,15 +2982,14 @@ int snd_pcm_hw_params_is_monotonic(const snd_pcm_hw_params_t *params) } /** - * \brief Check, if hardware supports overrange detection + * \brief Check if hardware supports overrange detection * \param params Configuration space - * \return Boolean value * \retval 0 Hardware doesn't support overrange detection * \retval 1 Hardware supports overrange detection * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_can_overrange(const snd_pcm_hw_params_t *params) { @@ -3008,15 +3002,14 @@ int snd_pcm_hw_params_can_overrange(const snd_pcm_hw_params_t *params) } /** - * \brief Check, if hardware supports pause + * \brief Check if hardware supports pause * \param params Configuration space - * \return Boolean value * \retval 0 Hardware doesn't support pause * \retval 1 Hardware supports pause * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_can_pause(const snd_pcm_hw_params_t *params) { @@ -3029,15 +3022,14 @@ int snd_pcm_hw_params_can_pause(const snd_pcm_hw_params_t *params) } /** - * \brief Check, if hardware supports resume + * \brief Check if hardware supports resume * \param params Configuration space - * \return Boolean value * \retval 0 Hardware doesn't support resume * \retval 1 Hardware supports resume * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_can_resume(const snd_pcm_hw_params_t *params) { @@ -3050,15 +3042,14 @@ int snd_pcm_hw_params_can_resume(const snd_pcm_hw_params_t *params) } /** - * \brief Check, if hardware does half-duplex only + * \brief Check if hardware does half-duplex only * \param params Configuration space - * \return Boolean value * \retval 0 Hardware doesn't do half-duplex * \retval 1 Hardware does half-duplex * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_is_half_duplex(const snd_pcm_hw_params_t *params) { @@ -3071,15 +3062,14 @@ int snd_pcm_hw_params_is_half_duplex(const snd_pcm_hw_params_t *params) } /** - * \brief Check, if hardware does joint-duplex (playback and capture are somewhat correlated) + * \brief Check if hardware does joint-duplex (playback and capture are somewhat correlated) * \param params Configuration space - * \return Boolean value * \retval 0 Hardware doesn't do joint-duplex * \retval 1 Hardware does joint-duplex * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_is_joint_duplex(const snd_pcm_hw_params_t *params) { @@ -3092,15 +3082,14 @@ int snd_pcm_hw_params_is_joint_duplex(const snd_pcm_hw_params_t *params) } /** - * \brief Check, if hardware supports synchronized start with sample resolution + * \brief Check if hardware supports synchronized start with sample resolution * \param params Configuration space - * \return Boolean value * \retval 0 Hardware doesn't support synchronized start * \retval 1 Hardware supports synchronized start * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_can_sync_start(const snd_pcm_hw_params_t *params) { @@ -3115,7 +3104,6 @@ int snd_pcm_hw_params_can_sync_start(const snd_pcm_hw_params_t *params) /** * \brief Check if hardware can disable period wakeups * \param params Configuration space - * \return Boolean value * \retval 0 Hardware cannot disable period wakeups * \retval 1 Hardware can disable period wakeups */ @@ -3136,9 +3124,9 @@ int snd_pcm_hw_params_can_disable_period_wakeup(const snd_pcm_hw_params_t *param * \param rate_den Pointer to returned rate denominator * \return 0 otherwise a negative error code if the info is not available * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_get_rate_numden(const snd_pcm_hw_params_t *params, unsigned int *rate_num, unsigned int *rate_den) @@ -3158,9 +3146,9 @@ int snd_pcm_hw_params_get_rate_numden(const snd_pcm_hw_params_t *params, * \param params Configuration space * \return signification bits in sample otherwise a negative error code if the info is not available * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_get_sbits(const snd_pcm_hw_params_t *params) { @@ -3173,13 +3161,13 @@ int snd_pcm_hw_params_get_sbits(const snd_pcm_hw_params_t *params) } /** - * \brief Get hard are FIFO size info from a configuration space + * \brief Get hardware FIFO size info from a configuration space * \param params Configuration space * \return FIFO size in frames otherwise a negative error code if the info is not available * - * It is not allowed to call this function when given configuration is not exactly one. - * Usually, #snd_pcm_hw_params() function chooses one configuration - * from the configuration space. + * This function should only be called when the configuration space + * contains a single configuration. Call #snd_pcm_hw_params to choose + * a single configuration from the configuration space. */ int snd_pcm_hw_params_get_fifo_size(const snd_pcm_hw_params_t *params) { @@ -3558,7 +3546,7 @@ void snd_pcm_hw_params_copy(snd_pcm_hw_params_t *dst, const snd_pcm_hw_params_t * \brief Extract access type from a configuration space * \param params Configuration space * \param access Returned value - * \return access type otherwise a negative error code if not exactly one is present + * \return access type otherwise a negative error code if the configuration space does not contain a single value */ #ifndef DOXYGEN int INTERNAL(snd_pcm_hw_params_get_access)(const snd_pcm_hw_params_t *params, snd_pcm_access_t *access) @@ -3659,7 +3647,7 @@ int snd_pcm_hw_params_get_access_mask(snd_pcm_hw_params_t *params, snd_pcm_acces * \brief Extract format from a configuration space * \param params Configuration space * \param format returned format - * \return format otherwise a negative error code if not exactly one is present + * \return format otherwise a negative error code if the configuration space does not contain a single value */ #ifndef DOXYGEN int INTERNAL(snd_pcm_hw_params_get_format)(const snd_pcm_hw_params_t *params, snd_pcm_format_t *format) @@ -3753,7 +3741,7 @@ void snd_pcm_hw_params_get_format_mask(snd_pcm_hw_params_t *params, snd_pcm_form * \brief Extract subformat from a configuration space * \param params Configuration space * \param subformat Returned subformat value - * \return subformat otherwise a negative error code if not exactly one is present + * \return subformat otherwise a negative error code if the configuration space does not contain a single value */ #ifndef DOXYGEN int INTERNAL(snd_pcm_hw_params_get_subformat)(const snd_pcm_hw_params_t *params, snd_pcm_subformat_t *subformat) @@ -3847,7 +3835,7 @@ void snd_pcm_hw_params_get_subformat_mask(snd_pcm_hw_params_t *params, snd_pcm_s * \brief Extract channels from a configuration space * \param params Configuration space * \param val Returned channels count - * \return 0 otherwise a negative error code if not exactly one is present + * \return 0 otherwise a negative error code if the configuration space does not contain a single value */ #ifndef DOXYGEN int INTERNAL(snd_pcm_hw_params_get_channels)(const snd_pcm_hw_params_t *params, unsigned int *val) @@ -4003,7 +3991,7 @@ int snd_pcm_hw_params_set_channels_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *par * \param params Configuration space * \param val Returned approximate rate * \param dir Sub unit direction - * \return 0 otherwise a negative error code if not exactly one is present + * \return 0 otherwise a negative error code if the configuration space does not contain a single value * * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1) */ @@ -4219,7 +4207,7 @@ int snd_pcm_hw_params_get_rate_resample(snd_pcm_t *pcm, snd_pcm_hw_params_t *par } /** - * \brief Restrict a configuration space to allow the buffer accessible from outside + * \brief Restrict a configuration space to allow the buffer to be accessible from outside * \param pcm PCM handle * \param params Configuration space * \param val 0 = disable, 1 = enable (default) exporting buffer @@ -4306,7 +4294,7 @@ int snd_pcm_hw_params_get_period_wakeup(snd_pcm_t *pcm, snd_pcm_hw_params_t *par * \param params Configuration space * \param val Returned approximate period duration in us * \param dir Sub unit direction - * \return 0 otherwise a negative error code if not exactly one is present + * \return 0 otherwise a negative error code if the configuration space does not contain a single value * * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1) */ @@ -4494,7 +4482,7 @@ int snd_pcm_hw_params_set_period_time_last(snd_pcm_t *pcm, snd_pcm_hw_params_t * * \param params Configuration space * \param val Returned approximate period size in frames * \param dir Sub unit direction - * \return 0 otherwise a negative error code if not exactly one is present + * \return 0 otherwise a negative error code if the configuration space does not contain a single value * * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1) */ @@ -4731,7 +4719,7 @@ int snd_pcm_hw_params_set_period_size_integer(snd_pcm_t *pcm, snd_pcm_hw_params_ * \param params Configuration space * \param val approximate periods per buffer * \param dir Sub unit direction - * \return 0 otherwise a negative error code if not exactly one is present + * \return 0 otherwise a negative error code if the configuration space does not contain a single value * * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1) */ @@ -4931,7 +4919,7 @@ int snd_pcm_hw_params_set_periods_integer(snd_pcm_t *pcm, snd_pcm_hw_params_t *p * \param params Configuration space * \param val Returned buffer time in us * \param dir Sub unit direction - * \return 0 otherwise a negative error code if not exactly one is present + * \return 0 otherwise a negative error code if the configuration space does not contain a single value * * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1) */ @@ -5119,7 +5107,7 @@ int snd_pcm_hw_params_set_buffer_time_last(snd_pcm_t *pcm, snd_pcm_hw_params_t * * \brief Extract buffer size from a configuration space * \param params Configuration space * \param val Returned buffer size in frames - * \return 0 otherwise a negative error code if not exactly one is present + * \return 0 otherwise a negative error code if the configuration space does not contain a single value */ #ifndef DOXYGEN int INTERNAL(snd_pcm_hw_params_get_buffer_size)(const snd_pcm_hw_params_t *params, snd_pcm_uframes_t *val) @@ -5318,7 +5306,7 @@ int snd_pcm_hw_params_set_buffer_size_last(snd_pcm_t *pcm, snd_pcm_hw_params_t * * \param params Configuration space * \param val Returned approximate tick duration in us * \param dir Sub unit direction - * \return 0 otherwise a negative error code if not exactly one is present + * \return 0 otherwise a negative error code if the configuration space does not contain a single value * * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1) */ @@ -5508,7 +5496,7 @@ int snd_pcm_hw_params_set_tick_time_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *pa * \brief Get the minimum transfer align value in samples * \param params Configuration space * \param val Returned minimum align value - * \return 0 otherwise a negative error code if not exactly one is present + * \return 0 otherwise a negative error code if the configuration space does not contain a single value */ int snd_pcm_hw_params_get_min_align(const snd_pcm_hw_params_t *params, snd_pcm_uframes_t *val) { -- 2.11.0