[alsa-devel] [PATCH] ucm: improve jack configuration documentation

[Takashi Iwai]

At Thu,  5 Mar 2015 12:30:05 +0200,
Tanu Kaskinen wrote:
> 
> Signed-off-by: Tanu Kaskinen <tanu.kaskinen at linux.intel.com>
> ---
> 
> I worked with Han Lu on enabling jack detection in PulseAudio with UCM
> on Broadwell-rt286. Due to less-than-perfect coordination, we both
> independently wrote documentation for the new UCM values. Han sent his
> patch first, and it got applied already, but my patch has more
> detailed documentation, so it might make sense to replace the
> documentation with my version.

OK, I can commit the new one on the top.  But...

> 
> 
>  include/use-case.h | 26 ++++++++++++++++++++++----
>  1 file changed, 22 insertions(+), 4 deletions(-)
> 
> diff --git a/include/use-case.h b/include/use-case.h
> index 3728906..6c1fe70 100644
> --- a/include/use-case.h
> +++ b/include/use-case.h
> @@ -284,10 +284,28 @@ int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr,
>   *   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.
> + *   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.

IMO, this is hard to read due to the too narrow columns.  Can't it be
indented better?  The only requirement is that doxygen can parse
correctly.


Takashi