linux-kernel - Re: awful kconfig help texts.

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20120817061102.GA6003@avionic-0098.adnet.avionic-design.de>
Date:	Fri, 17 Aug 2012 08:11:02 +0200
From:	Thierry Reding <thierry.reding@...onic-design.de>
To:	Borislav Petkov <bp@...en8.de>, Dave Jones <davej@...hat.com>,
	Linux Kernel <linux-kernel@...r.kernel.org>
Subject: Re: awful kconfig help texts.

On Thu, Aug 16, 2012 at 02:05:41PM +0200, Thierry Reding wrote:
> 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@...onic-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@...onic-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.

How about the patch below?

Thierry

View attachment "0001-pwm-Improve-Kconfig-help-text.patch" of type "text/plain" (2334 bytes)

Content of type "application/pgp-signature" skipped