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: <20120816111044.GA12029@x1.osrc.amd.com>
Date:	Thu, 16 Aug 2012 13:10:44 +0200
From:	Borislav Petkov <bp@...en8.de>
To:	Thierry Reding <thierry.reding@...onic-design.de>
Cc:	Dave Jones <davej@...hat.com>,
	Linux Kernel <linux-kernel@...r.kernel.org>
Subject: Re: awful kconfig help texts.

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.

Thanks.

-- 
Regards/Gruss,
Boris.
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/