Re: [PATCH] checkpatch.pl: Improve WARNING on Kconfig help

[Andy Whitcroft <apw@canonical.com>]

On Wed, Dec 19, 2018 at 02:44:36AM -0800, Joe Perches wrote:
> On Wed, 2018-12-19 at 10:35 +0200, Igor Stoppa wrote:
> > The checkpatch.pl script complains when the help section of a Kconfig
> > entry is too short, but it doesn't really explain what it is looking
> > for. Instead, it gives a generic warning that one should consider writing
> > a paragraph.
> > 
> > But what it *really* checks is that the help section is at least
> > .$min_conf_desc_length lines long.
> > 
> > Since the definition of what is a paragraph is not really carved in
> > stone (and actually the primary descriptions is "5 sentences"), make the
> > warning less ambiguous by expliciting the actual test condition, so that
> > one doesn't have to read checkpatch.pl sources, to figure out the actual
> > test.
> []
> > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> []
> > @@ -2931,7 +2931,8 @@ sub process {
> >  			}
> >  			if ($is_start && $is_end && $length < $min_conf_desc_length) {
> >  				WARN("CONFIG_DESCRIPTION",
> > -				     "please write a paragraph that describes the config symbol fully\n" . $herecurr);
> > +				     "please write a paragraph (" .$min_conf_desc_length . " lines)" .
> 
> could say "(at least $min_conf_desc_length lines)"

The original is better description in the semantic sense.  We want them
to describe it well.  We assume they haven't because it is short.  We
don't want them to make it long, we want them to confirm it is fully
described.

You arn't trying to make people make these warnings away, they should
just be checking they have met the criteria in the warning.  If they
have they can ignore the warning and be happy, they don't have to add
two more lines.

To cover both cases perhaps:

	"please ensure that this config symbols is described fully (less than
	 $min_conf_desc_length lines is quite brief)"

-apw