[alsa-devel] [PATCH v2 0/2] snd_use_case_get() documentation improvements
Tanu Kaskinen (2): ucm: reformat snd_use_case_get() doc ucm: improve jack configuration documentation
include/use-case.h | 123 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 77 insertions(+), 46 deletions(-)
Doxygen doesn't preserve formatting that relies only on indentation. This fixes it by using lists more liberally.
There are probably more places to fix than just snd_use_case_get_list(), but I only have motivation for fixing this function's documentation formatting (the next patch will add some more content to the function's documentation).
Signed-off-by: Tanu Kaskinen tanu.kaskinen@linux.intel.com --- include/use-case.h | 111 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 65 insertions(+), 46 deletions(-)
diff --git a/include/use-case.h b/include/use-case.h index 3728906..d309522 100644 --- a/include/use-case.h +++ b/include/use-case.h @@ -229,10 +229,10 @@ int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr, * "const", but it's too late to fix it, sorry about that.) * * Known identifiers: - * NULL - return current card - * _verb - return current verb + * - NULL - return current card + * - _verb - return current verb * - * [=]{NAME}[/[{modifier}|{/device}][/{verb}]] + * - [=]{NAME}[/[{modifier}|{/device}][/{verb}]] * - value identifier {NAME} * - Search starts at given modifier or device if any, * else at a verb @@ -243,51 +243,70 @@ int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr, * device/modifier/verb specified, and not search * through each object in turn. * - Examples: - * "PlaybackPCM/Play Music" - * "CapturePCM/SPDIF" - * From ValueDefaults only: - * "=Variable" - * From current active verb: - * "=Variable//" - * From verb "Verb": - * "=Variable//Verb" - * From "Modifier" in current active verb: - * "=Variable/Modifier/" - * From "Modifier" in "Verb": - * "=Variable/Modifier/Verb" + * - "PlaybackPCM/Play Music" + * - "CapturePCM/SPDIF" + * - From ValueDefaults only: + * "=Variable" + * - From current active verb: + * "=Variable//" + * - From verb "Verb": + * "=Variable//Verb" + * - From "Modifier" in current active verb: + * "=Variable/Modifier/" + * - From "Modifier" in "Verb": + * "=Variable/Modifier/Verb" * * Recommended names for values: - * TQ - Tone Quality - * PlaybackPCM - full PCM playback device name - * PlaybackPCMIsDummy - Valid values: "yes" and "no". If set to "yes", the - * PCM named by the PlaybackPCM value is a dummy device, - * meaning that opening it enables an audio path in the - * hardware, but writing to the PCM device has no - * effect. - * CapturePCM - full PCM capture device name - * CapturePCMIsDummy - Valid values: "yes" and "no". If set to "yes", the - * PCM named by the CapturePCM value is a dummy device, - * meaning that opening it enables an audio path in the - * hardware, but reading from the PCM device has no - * effect. - * PlaybackRate - playback device sample rate - * PlaybackChannels - playback device channel count - * PlaybackCTL - playback control device name - * PlaybackVolume - playback control volume ID string - * PlaybackSwitch - playback control switch ID string - * CaptureRate - capture device sample rate - * CaptureChannels - capture device channel count - * CaptureCTL - capture control device name - * CaptureVolume - capture control volume ID string - * CaptureSwitch - capture control switch ID string - * PlaybackMixer - name of playback mixer - * PlaybackMixerID - mixer playback ID - * CaptureMixer - name of capture mixer - * CaptureMixerID - mixer capture ID - * JackDev - jack device name - * JackControl - jack control name - * JackHWMute - indicate if the HW mutes a device on jack insertion - * or not. + * - TQ + * - Tone Quality + * - PlaybackPCM + * - full PCM playback device name + * - PlaybackPCMIsDummy + * - Valid values: "yes" and "no". If set to "yes", the PCM named by the + * PlaybackPCM value is a dummy device, meaning that opening it enables + * an audio path in the hardware, but writing to the PCM device has no + * effect. + * - CapturePCM + * - full PCM capture device name + * - CapturePCMIsDummy + * - Valid values: "yes" and "no". If set to "yes", the PCM named by the + * CapturePCM value is a dummy device, meaning that opening it enables + * an audio path in the hardware, but reading from the PCM device has no + * effect. + * - PlaybackRate + * - playback device sample rate + * - PlaybackChannels + * - playback device channel count + * - PlaybackCTL + * - playback control device name + * - PlaybackVolume + * - playback control volume ID string + * - PlaybackSwitch + * - playback control switch ID string + * - CaptureRate + * - capture device sample rate + * - CaptureChannels + * - capture device channel count + * - CaptureCTL + * - capture control device name + * - CaptureVolume + * - capture control volume ID string + * - CaptureSwitch + * - capture control switch ID string + * - PlaybackMixer + * - name of playback mixer + * - PlaybackMixerID + * - mixer playback ID + * - CaptureMixer + * - name of capture mixer + * - CaptureMixerID + * - mixer capture ID + * - JackDev + * - jack device name + * - JackControl + * - jack control name + * - JackHWMute + * - indicate if the HW mutes a device on jack insertion or not. */ int snd_use_case_get(snd_use_case_mgr_t *uc_mgr, const char *identifier,
Signed-off-by: Tanu Kaskinen tanu.kaskinen@linux.intel.com --- include/use-case.h | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-)
diff --git a/include/use-case.h b/include/use-case.h index d309522..e3308b1 100644 --- a/include/use-case.h +++ b/include/use-case.h @@ -301,12 +301,24 @@ int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr, * - name of capture mixer * - CaptureMixerID * - mixer capture ID - * - JackDev - * - jack device name - * - JackControl - * - jack control name - * - JackHWMute - * - indicate if the HW mutes a device on jack insertion or not. + * - JackControl, JackDev, JackHWMute + * - Jack information for a device. The jack status can be reported via + * a kcontrol and/or via an input device. **JackControl** is the + * kcontrol name of the jack, and **JackDev** is the input device id of + * the jack (if the full input device path is /dev/input/by-id/foo, the + * JackDev value should be "foo"). UCM configuration files should + * contain both JackControl and JackDev when possible, because + * applications are likely to support only one or the other. + * + * If **JackHWMute** is set, it indicates that when the jack is plugged + * in, the hardware automatically mutes some other device. The + * JackHWMute value is the name of the muted device. Note that + * JackHWMute should be used only when the hardware enforces the + * automatic muting. If the hardware doesn't enforce any muting, it may + * still be tempting to set JackHWMute to trick upper software layers to + * e.g. automatically mute speakers when headphones are plugged in, but + * that's application policy configuration that doesn't belong to UCM + * configuration files. */ int snd_use_case_get(snd_use_case_mgr_t *uc_mgr, const char *identifier,
At Thu, 5 Mar 2015 14:51:56 +0200, Tanu Kaskinen wrote:
Tanu Kaskinen (2): ucm: reformat snd_use_case_get() doc ucm: improve jack configuration documentation
Thanks, applied both patches.
Takashi
include/use-case.h | 123 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 77 insertions(+), 46 deletions(-)
-- 1.9.3
participants (2)
-
Takashi Iwai -
Tanu Kaskinen