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

[Tanu Kaskinen]

On Thu, 2015-03-05 at 12:30 +0100, Takashi Iwai wrote:
> 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.

Sure, I can reformat the patch. One way would be to reduce the
indentation, but do you think the wrap limit should be increased from 80
chars instead or in addition to reducing the indentation?

Doxygen seems to render this documentation section rather horribly,
regardless of my patch... I'll fix that too.

-- 
Tanu