Re: awful kconfig help texts.

[Thierry Reding <thierry.reding@avionic-design.de>]

[-- Attachment #1: Type: text/plain, Size: 3025 bytes --]

On Thu, Aug 16, 2012 at 01:10:44PM +0200, Borislav Petkov wrote:
> On Thu, Aug 16, 2012 at 11:54:39AM +0200, Thierry Reding wrote:
> > How does the attached patch look?
> > 
> > Thierry
> 
> > From cd3199b94e697cccd38766b4a60d2e91474d0539 Mon Sep 17 00:00:00 2001
> > From: Thierry Reding <thierry.reding@avionic-design.de>
> > Date: Thu, 16 Aug 2012 08:01:21 +0200
> > Subject: [PATCH] pwm: Improve Kconfig help text
> > 
> > The Kconfig help text should help the user understand what functionality
> > is provided by an option. This is especially true for new subsystems. An
> > improved help text is provided by this commit in the hopes of clarifying
> > the usefulness of the PWM framework.
> > 
> > Signed-off-by: Thierry Reding <thierry.reding@avionic-design.de>
> > ---
> >  drivers/pwm/Kconfig | 24 ++++++++++++++++++------
> >  1 file changed, 18 insertions(+), 6 deletions(-)
> > 
> > diff --git a/drivers/pwm/Kconfig b/drivers/pwm/Kconfig
> > index 8fc3808..88ddb9e 100644
> > --- a/drivers/pwm/Kconfig
> > +++ b/drivers/pwm/Kconfig
> > @@ -1,12 +1,24 @@
> >  menuconfig PWM
> > -	bool "PWM Support"
> > +	bool "Pulse-Width Modulation (PWM) Support"
> >  	depends on !MACH_JZ4740 && !PUV3_PWM
> >  	help
> > -	  This enables PWM support through the generic PWM framework.
> > -	  You only need to enable this, if you also want to enable
> > -	  one or more of the PWM drivers below.
> > -
> > -	  If unsure, say N.
> > +	  Generic Pulse-Width Modulation (PWM) support.
> > +
> > +	  This framework provides a generic interface to PWM devices
> > +	  within the Linux kernel. On the driver side it provides an API
> > +	  to register and unregister a PWM chip, an abstraction of a PWM
> > +	  controller, that supports one or more PWM devices. Client
> > +	  drivers can request PWM devices and use the generic framework
> > +	  to configure as well as enable and disable them.
> > +
> > +	  The new generic framework replaces the legacy PWM framework
> > +	  which allows only a single driver implementing the required
> > +	  API. Not all legacy implementations have been ported to the
> > +	  new framework yet. The new framework provides an API that is
> > +	  backward compatible with the legacy framework so that existing
> > +	  client drivers continue to work as expected.
> > +
> > +	  If unsure, say no.
> 
> Yes, this is much better than what we had before. I'd suggest though,
> that instead of describing the high-level software design of the PWM
> subsystem, the text should be more addressed to the simple user like me
> who would like to know what this thing is and why do I want to enable
> it. Basically summarize what PWN devices are and what they're used for.
> I.e., https://en.wikipedia.org/wiki/Pulse-width_modulation#Applications
> but in 4-5 lines of text.
> 
> IMHO, of course.

Okay, I'll add something along those lines in addition to the above.
That way everybody should find something useful in it.

Thanks,
Thierry

[-- Attachment #2: Type: application/pgp-signature, Size: 836 bytes --]