[PATCH] trivial: make comment about vs{n,cn,}printf more understandable

[PATCH] trivial: make comment about vs{n,cn,}printf more understandable

[Uwe Kleine-König]

"You probably want ... instead." sounds like a recommendation better
not to use the v... functions.

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
 lib/vsprintf.c |    9 +++------
 1 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/lib/vsprintf.c b/lib/vsprintf.c
index c150d3d..ec43171 100644
--- a/lib/vsprintf.c
+++ b/lib/vsprintf.c
@@ -1279,8 +1279,7 @@ qualifier:
  * return is greater than or equal to @size, the resulting
  * string is truncated.
  *
- * Call this function if you are already dealing with a va_list.
- * You probably want snprintf() instead.
+ * If you're not already dealing with a va_list better use snprintf().
  */
 int vsnprintf(char *buf, size_t size, const char *fmt, va_list args)
 {
@@ -1454,8 +1453,7 @@ EXPORT_SYMBOL(vsnprintf);
  * the @buf not including the trailing '\0'. If @size is <= 0 the function
  * returns 0.
  *
- * Call this function if you are already dealing with a va_list.
- * You probably want scnprintf() instead.
+ * If you're not already dealing with a va_list better use scnprintf().
  *
  * See the vsnprintf() documentation for format string extensions over C99.
  */
@@ -1534,8 +1532,7 @@ EXPORT_SYMBOL(scnprintf);
  * into @buf. Use vsnprintf() or vscnprintf() in order to avoid
  * buffer overflows.
  *
- * Call this function if you are already dealing with a va_list.
- * You probably want sprintf() instead.
+ * If you're not already dealing with a va_list better use sprintf().
  *
  * See the vsnprintf() documentation for format string extensions over C99.
  */
-- 
1.7.2.3

Re: trivial: make comment about vs{n,cn,}printf more understandable

[Milton Miller]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 842 bytes --]

On Tue, 23 Nov 2010 at about 16:12:45 -0000, Uwe Kleine-König wrote:
> 
> "You probably want ... instead." sounds like a recommendation better
> not to use the v... functions.
> 

Which is true, if you dont' have a va_list its hard to get them.
But I do get your point.

>   * the @buf not including the trailing '\0'. If @size is <= 0 the function
>   * returns 0.
>   *
> - * Call this function if you are already dealing with a va_list.
> - * You probably want scnprintf() instead.
> + * If you're not already dealing with a va_list better use scnprintf().

That doesn't flow off my (mid-western usa) tounge.

How about
 * Call this function if you are already dealing with a va_list.
 * Otherwise you probably want to use scnprintf().

Alternatively,
 * If you're not already dealing with a va_list consider scnprintf().

Thanks,
milton

Re: trivial: make comment about vs{n,cn,}printf more understandable

[Steven Rostedt]

On Tue, 2010-11-23 at 21:04 -0600, Milton Miller wrote:
> On Tue, 23 Nov 2010 at about 16:12:45 -0000, Uwe Kleine-König wrote:
> > 
> > "You probably want ... instead." sounds like a recommendation better
> > not to use the v... functions.
> > 
> 
> Which is true, if you dont' have a va_list its hard to get them.
> But I do get your point.
> 
> >   * the @buf not including the trailing '\0'. If @size is <= 0 the function
> >   * returns 0.
> >   *
> > - * Call this function if you are already dealing with a va_list.
> > - * You probably want scnprintf() instead.
> > + * If you're not already dealing with a va_list better use scnprintf().
> 
> That doesn't flow off my (mid-western usa) tounge.
> 
> How about
>  * Call this function if you are already dealing with a va_list.
>  * Otherwise you probably want to use scnprintf().

This is closer to what he asked us on IRC ;-)

But a "do X if Y" is more perl syntax than English (IMHO).


> 
> Alternatively,
>  * If you're not already dealing with a va_list consider scnprintf().

This isn't bad. My recommendation I gave him was:

 * If you are already dealing with a va_list, then call this function.
 * Otherwise you probably want to use scnprintf()

But my upstate NY tongue may not be the best judgment here.

-- Steve

"When people ask me what language my mother tongue is, I simply reply 'C'"

Re: trivial: make comment about vs{n,cn,}printf more understandable

[Will Schmidt]

On Tue, 2010-11-23 at 22:20 -0500, Steven Rostedt wrote:
> On Tue, 2010-11-23 at 21:04 -0600, Milton Miller wrote:
> > On Tue, 23 Nov 2010 at about 16:12:45 -0000, Uwe Kleine-König wrote:
> > > 
> > > "You probably want ... instead." sounds like a recommendation better
> > > not to use the v... functions.
> > > 
> > 
> > Which is true, if you dont' have a va_list its hard to get them.
> > But I do get your point.
> > 
> > >   * the @buf not including the trailing '\0'. If @size is <= 0 the function
> > >   * returns 0.
> > >   *
> > > - * Call this function if you are already dealing with a va_list.
> > > - * You probably want scnprintf() instead.
> > > + * If you're not already dealing with a va_list better use scnprintf().
> > 
> > That doesn't flow off my (mid-western usa) tounge.
> > 
> > How about
> >  * Call this function if you are already dealing with a va_list.
> >  * Otherwise you probably want to use scnprintf().

> This is closer to what he asked us on IRC ;-)
> 
> But a "do X if Y" is more perl syntax than English (IMHO).
> 
> 
> > 
> > Alternatively,
> >  * If you're not already dealing with a va_list consider scnprintf().
> 
> This isn't bad. My recommendation I gave him was:
> 
>  * If you are already dealing with a va_list, then call this function.
>  * Otherwise you probably want to use scnprintf()

Would be nice if we could lead with the "probably...", but I don't see a
clean way of doing that.    How about a blending of the two:

 * Call this function if you are dealing with a va_list, otherwise use
the scnprintf() function.


> But my upstate NY tongue may not be the best judgment here.
> 
> -- Steve
> 
> "When people ask me what language my mother tongue is, I simply reply 'C'"
> 
> 
> 

[PATCH v2] trivial: make comment about vs{n,cn,}printf more understandable

[Uwe Kleine-König]

"You probably want ... instead." sounds like a recommendation better
not to use the v... functions.

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
Hello,

this is Milton's alternative suggestion plus an added "using".

Thanks
Uwe

 lib/vsprintf.c |    9 +++------
 1 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/lib/vsprintf.c b/lib/vsprintf.c
index c150d3d..6c46e0f 100644
--- a/lib/vsprintf.c
+++ b/lib/vsprintf.c
@@ -1279,8 +1279,7 @@ qualifier:
  * return is greater than or equal to @size, the resulting
  * string is truncated.
  *
- * Call this function if you are already dealing with a va_list.
- * You probably want snprintf() instead.
+ * If you're not already dealing with a va_list consider using snprintf().
  */
 int vsnprintf(char *buf, size_t size, const char *fmt, va_list args)
 {
@@ -1454,8 +1453,7 @@ EXPORT_SYMBOL(vsnprintf);
  * the @buf not including the trailing '\0'. If @size is <= 0 the function
  * returns 0.
  *
- * Call this function if you are already dealing with a va_list.
- * You probably want scnprintf() instead.
+ * If you're not already dealing with a va_list consider using scnprintf().
  *
  * See the vsnprintf() documentation for format string extensions over C99.
  */
@@ -1534,8 +1532,7 @@ EXPORT_SYMBOL(scnprintf);
  * into @buf. Use vsnprintf() or vscnprintf() in order to avoid
  * buffer overflows.
  *
- * Call this function if you are already dealing with a va_list.
- * You probably want sprintf() instead.
+ * If you're not already dealing with a va_list consider using sprintf().
  *
  * See the vsnprintf() documentation for format string extensions over C99.
  */
-- 
1.7.2.3

Re: [PATCH v2] trivial: make comment about vs{n,cn,}printf more understandable

[Uwe Kleine-König]

Hello Jiri,

On Wed, Nov 24, 2010 at 08:10:33PM +0100, Uwe Kleine-König wrote:
> "You probably want ... instead." sounds like a recommendation better
> not to use the v... functions.
you didn't take this patch. Did you skip it on purpose?

Best regards
Uwe

> 
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> ---
> Hello,
> 
> this is Milton's alternative suggestion plus an added "using".
> 
> Thanks
> Uwe
> 
>  lib/vsprintf.c |    9 +++------
>  1 files changed, 3 insertions(+), 6 deletions(-)
> 
> diff --git a/lib/vsprintf.c b/lib/vsprintf.c
> index c150d3d..6c46e0f 100644
> --- a/lib/vsprintf.c
> +++ b/lib/vsprintf.c
> @@ -1279,8 +1279,7 @@ qualifier:
>   * return is greater than or equal to @size, the resulting
>   * string is truncated.
>   *
> - * Call this function if you are already dealing with a va_list.
> - * You probably want snprintf() instead.
> + * If you're not already dealing with a va_list consider using snprintf().
>   */
>  int vsnprintf(char *buf, size_t size, const char *fmt, va_list args)
>  {
> @@ -1454,8 +1453,7 @@ EXPORT_SYMBOL(vsnprintf);
>   * the @buf not including the trailing '\0'. If @size is <= 0 the function
>   * returns 0.
>   *
> - * Call this function if you are already dealing with a va_list.
> - * You probably want scnprintf() instead.
> + * If you're not already dealing with a va_list consider using scnprintf().
>   *
>   * See the vsnprintf() documentation for format string extensions over C99.
>   */
> @@ -1534,8 +1532,7 @@ EXPORT_SYMBOL(scnprintf);
>   * into @buf. Use vsnprintf() or vscnprintf() in order to avoid
>   * buffer overflows.
>   *
> - * Call this function if you are already dealing with a va_list.
> - * You probably want sprintf() instead.
> + * If you're not already dealing with a va_list consider using sprintf().
>   *
>   * See the vsnprintf() documentation for format string extensions over C99.
>   */
> -- 
> 1.7.2.3
> 
> 

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |

Re: [PATCH v2] trivial: make comment about vs{n,cn,}printf more understandable

[Jiri Kosina]

On Wed, 6 Apr 2011, Uwe Kleine-König wrote:

> Hello Jiri,
> 
> On Wed, Nov 24, 2010 at 08:10:33PM +0100, Uwe Kleine-König wrote:
> > "You probably want ... instead." sounds like a recommendation better
> > not to use the v... functions.
> you didn't take this patch. Did you skip it on purpose?

Hi,

I don't see it in the trivial 'todo' queue. Either I though someone else 
is taking it, or I just missed it. Could you please re-bounce it to 
trivial@kernel.org, and I will apply it?

Thanks.

> 
> Best regards
> Uwe
> 
> > 
> > Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> > ---
> > Hello,
> > 
> > this is Milton's alternative suggestion plus an added "using".
> > 
> > Thanks
> > Uwe
> > 
> >  lib/vsprintf.c |    9 +++------
> >  1 files changed, 3 insertions(+), 6 deletions(-)
> > 
> > diff --git a/lib/vsprintf.c b/lib/vsprintf.c
> > index c150d3d..6c46e0f 100644
> > --- a/lib/vsprintf.c
> > +++ b/lib/vsprintf.c
> > @@ -1279,8 +1279,7 @@ qualifier:
> >   * return is greater than or equal to @size, the resulting
> >   * string is truncated.
> >   *
> > - * Call this function if you are already dealing with a va_list.
> > - * You probably want snprintf() instead.
> > + * If you're not already dealing with a va_list consider using snprintf().
> >   */
> >  int vsnprintf(char *buf, size_t size, const char *fmt, va_list args)
> >  {
> > @@ -1454,8 +1453,7 @@ EXPORT_SYMBOL(vsnprintf);
> >   * the @buf not including the trailing '\0'. If @size is <= 0 the function
> >   * returns 0.
> >   *
> > - * Call this function if you are already dealing with a va_list.
> > - * You probably want scnprintf() instead.
> > + * If you're not already dealing with a va_list consider using scnprintf().
> >   *
> >   * See the vsnprintf() documentation for format string extensions over C99.
> >   */
> > @@ -1534,8 +1532,7 @@ EXPORT_SYMBOL(scnprintf);
> >   * into @buf. Use vsnprintf() or vscnprintf() in order to avoid
> >   * buffer overflows.
> >   *
> > - * Call this function if you are already dealing with a va_list.
> > - * You probably want sprintf() instead.
> > + * If you're not already dealing with a va_list consider using sprintf().
> >   *
> >   * See the vsnprintf() documentation for format string extensions over C99.
> >   */
> > -- 
> > 1.7.2.3
> > 
> > 
> 
> -- 
> Pengutronix e.K.                           | Uwe Kleine-König            |
> Industrial Linux Solutions                 | http://www.pengutronix.de/  |
> 

-- 
Jiri Kosina
SUSE Labs, Novell Inc.