[PATCH] Staging: comedi: Coding style warning fix for block comments

[PATCH] Staging: comedi: Coding style warning fix for block comments

[Punit Vara]

This patch is to comedidev.h file that fixes up following warnings
reported by checkpatch.pl :

-Block comments use a trailing */ on a separate line
-Block comments use * on subsequent lines

Signed-off-by: Punit Vara <punitvara@gmail.com>
---
 drivers/staging/comedi/comedidev.h | 62 ++++++++++++++++++++------------------
 1 file changed, 32 insertions(+), 30 deletions(-)

diff --git a/drivers/staging/comedi/comedidev.h b/drivers/staging/comedi/comedidev.h
index 28a5d3a..5b0ab03 100644
--- a/drivers/staging/comedi/comedidev.h
+++ b/drivers/staging/comedi/comedidev.h
@@ -1,20 +1,20 @@
 /*
-    include/linux/comedidev.h
-    header file for kernel-only structures, variables, and constants
-
-    COMEDI - Linux Control and Measurement Device Interface
-    Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org>
-
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-*/
+ * include/linux/comedidev.h
+ * header file for kernel-only structures, variables, and constants
+ *
+ * COMEDI - Linux Control and Measurement Device Interface
+ * Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
 
 #ifndef _COMEDIDEV_H
 #define _COMEDIDEV_H
@@ -105,7 +105,7 @@ struct comedi_buf_map {
 	struct kref refcount;
 };
 
-/**
+/*
  * struct comedi_async - control data for asynchronous comedi commands
  * @prealloc_buf:	preallocated buffer
  * @prealloc_bufsz:	buffer size (in bytes)
@@ -215,7 +215,7 @@ struct comedi_async {
 		       unsigned int x);
 };
 
-/**
+/*
  * comedi_async callback "events"
  * @COMEDI_CB_EOS:		end-of-scan
  * @COMEDI_CB_EOA:		end-of-acquisition/output
@@ -262,9 +262,11 @@ struct comedi_device {
 	struct device *class_dev;
 	int minor;
 	unsigned int detach_count;
-	/* hw_dev is passed to dma_alloc_coherent when allocating async buffers
+	/*
+	 * hw_dev is passed to dma_alloc_coherent when allocating async buffers
 	 * for subdevices that have async_dma_dir set to something other than
-	 * DMA_NONE */
+	 * DMA_NONE
+	 */
 	struct device *hw_dev;
 
 	const char *board_name;
@@ -391,7 +393,7 @@ static inline unsigned int comedi_offset_munge(struct comedi_subdevice *s,
 	return val ^ s->maxdata ^ (s->maxdata >> 1);
 }
 
-/**
+/*
  * comedi_bytes_per_sample - determine subdevice sample size
  * @s:		comedi_subdevice struct
  *
@@ -405,7 +407,7 @@ static inline unsigned int comedi_bytes_per_sample(struct comedi_subdevice *s)
 	return s->subdev_flags & SDF_LSAMPL ? sizeof(int) : sizeof(short);
 }
 
-/**
+/*
  * comedi_sample_shift - determine log2 of subdevice sample size
  * @s:		comedi_subdevice struct
  *
@@ -421,7 +423,7 @@ static inline unsigned int comedi_sample_shift(struct comedi_subdevice *s)
 	return s->subdev_flags & SDF_LSAMPL ? 2 : 1;
 }
 
-/**
+/*
  * comedi_bytes_to_samples - converts a number of bytes to a number of samples
  * @s:		comedi_subdevice struct
  * @nbytes:	number of bytes
@@ -434,7 +436,7 @@ static inline unsigned int comedi_bytes_to_samples(struct comedi_subdevice *s,
 	return nbytes >> comedi_sample_shift(s);
 }
 
-/**
+/*
  * comedi_samples_to_bytes - converts a number of samples to a number of bytes
  * @s:		comedi_subdevice struct
  * @nsamples:	number of samples
@@ -448,7 +450,7 @@ static inline unsigned int comedi_samples_to_bytes(struct comedi_subdevice *s,
 	return nsamples << comedi_sample_shift(s);
 }
 
-/**
+/*
  * comedi_check_trigger_src() - trivially validate a comedi_cmd trigger source
  * @src: pointer to the trigger source to validate
  * @flags: bitmask of valid TRIG_* for the trigger
@@ -469,7 +471,7 @@ static inline int comedi_check_trigger_src(unsigned int *src,
 	return 0;
 }
 
-/**
+/*
  * comedi_check_trigger_is_unique() - make sure a trigger source is unique
  * @src: the trigger source to check
  */
@@ -481,7 +483,7 @@ static inline int comedi_check_trigger_is_unique(unsigned int src)
 	return 0;
 }
 
-/**
+/*
  * comedi_check_trigger_arg_is() - trivially validate a trigger argument
  * @arg: pointer to the trigger arg to validate
  * @val: the value the argument should be
@@ -496,7 +498,7 @@ static inline int comedi_check_trigger_arg_is(unsigned int *arg,
 	return 0;
 }
 
-/**
+/*
  * comedi_check_trigger_arg_min() - trivially validate a trigger argument
  * @arg: pointer to the trigger arg to validate
  * @val: the minimum value the argument should be
@@ -511,7 +513,7 @@ static inline int comedi_check_trigger_arg_min(unsigned int *arg,
 	return 0;
 }
 
-/**
+/*
  * comedi_check_trigger_arg_max() - trivially validate a trigger argument
  * @arg: pointer to the trigger arg to validate
  * @val: the maximum value the argument should be
@@ -604,7 +606,7 @@ void comedi_auto_unconfig(struct device *);
 int comedi_driver_register(struct comedi_driver *);
 void comedi_driver_unregister(struct comedi_driver *);
 
-/**
+/*
  * module_comedi_driver() - Helper macro for registering a comedi driver
  * @__comedi_driver: comedi_driver struct
  *
-- 
2.5.2

Re: [PATCH] Staging: comedi: Coding style warning fix for block comments

[Ian Abbott]

On 20/09/15 09:50, Punit Vara wrote:
> This patch is to comedidev.h file that fixes up following warnings
> reported by checkpatch.pl :
>
> -Block comments use a trailing */ on a separate line
> -Block comments use * on subsequent lines
>
> Signed-off-by: Punit Vara <punitvara@gmail.com>
> ---
>   drivers/staging/comedi/comedidev.h | 62 ++++++++++++++++++++------------------
>   1 file changed, 32 insertions(+), 30 deletions(-)
>
> diff --git a/drivers/staging/comedi/comedidev.h b/drivers/staging/comedi/comedidev.h
> index 28a5d3a..5b0ab03 100644
> --- a/drivers/staging/comedi/comedidev.h
> +++ b/drivers/staging/comedi/comedidev.h
> @@ -1,20 +1,20 @@
>   /*
> -    include/linux/comedidev.h
> -    header file for kernel-only structures, variables, and constants
> -
> -    COMEDI - Linux Control and Measurement Device Interface
> -    Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org>
> -
> -    This program is free software; you can redistribute it and/or modify
> -    it under the terms of the GNU General Public License as published by
> -    the Free Software Foundation; either version 2 of the License, or
> -    (at your option) any later version.
> -
> -    This program is distributed in the hope that it will be useful,
> -    but WITHOUT ANY WARRANTY; without even the implied warranty of
> -    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> -    GNU General Public License for more details.
> -*/
> + * include/linux/comedidev.h
> + * header file for kernel-only structures, variables, and constants
> + *
> + * COMEDI - Linux Control and Measurement Device Interface
> + * Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org>
> + *
> + * This program is free software; you can redistribute it and/or modify
> + * it under the terms of the GNU General Public License as published by
> + * the Free Software Foundation; either version 2 of the License, or
> + * (at your option) any later version.
> + *
> + * This program is distributed in the hope that it will be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> + * GNU General Public License for more details.
> + */
>
>   #ifndef _COMEDIDEV_H
>   #define _COMEDIDEV_H
> @@ -105,7 +105,7 @@ struct comedi_buf_map {
>   	struct kref refcount;
>   };
>
> -/**
> +/*

The '/**' here and on most of the other comments is deliberate.  It is 
used to mark things up with "kernel-doc" - see 
"Documentation/kernel-doc-nano-HOWTO.txt".

>    * struct comedi_async - control data for asynchronous comedi commands
>    * @prealloc_buf:	preallocated buffer
>    * @prealloc_bufsz:	buffer size (in bytes)
> @@ -215,7 +215,7 @@ struct comedi_async {
>   		       unsigned int x);
>   };
>
> -/**
> +/*
>    * comedi_async callback "events"
>    * @COMEDI_CB_EOS:		end-of-scan
>    * @COMEDI_CB_EOA:		end-of-acquisition/output

Admittedly, this wasn't a valid kernel-doc comment, but I'm planning to 
fix that shortly.

Please don't bother fixing this patch as I'm about to send a larger 
series of patches to comedidev.h to add more documentation and I will 
fix the incorrect block comments in that series.

-- 
-=( Ian Abbott @ MEV Ltd.    E-mail: <abbotti@mev.co.uk> )=-
-=(                          Web: http://www.mev.co.uk/  )=-

Re: [PATCH] Staging: comedi: Coding style warning fix for block comments

[punit vara]

On Mon, Sep 21, 2015 at 11:15 PM, Ian Abbott <abbotti@mev.co.uk> wrote:
> On 20/09/15 09:50, Punit Vara wrote:
>>
>> This patch is to comedidev.h file that fixes up following warnings
>> reported by checkpatch.pl :
>>
>> -Block comments use a trailing */ on a separate line
>> -Block comments use * on subsequent lines
>>
>> Signed-off-by: Punit Vara <punitvara@gmail.com>
>> ---
>>   drivers/staging/comedi/comedidev.h | 62
>> ++++++++++++++++++++------------------
>>   1 file changed, 32 insertions(+), 30 deletions(-)
>>
>> diff --git a/drivers/staging/comedi/comedidev.h
>> b/drivers/staging/comedi/comedidev.h
>> index 28a5d3a..5b0ab03 100644
>> --- a/drivers/staging/comedi/comedidev.h
>> +++ b/drivers/staging/comedi/comedidev.h
>> @@ -1,20 +1,20 @@
>>   /*
>> -    include/linux/comedidev.h
>> -    header file for kernel-only structures, variables, and constants
>> -
>> -    COMEDI - Linux Control and Measurement Device Interface
>> -    Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org>
>> -
>> -    This program is free software; you can redistribute it and/or modify
>> -    it under the terms of the GNU General Public License as published by
>> -    the Free Software Foundation; either version 2 of the License, or
>> -    (at your option) any later version.
>> -
>> -    This program is distributed in the hope that it will be useful,
>> -    but WITHOUT ANY WARRANTY; without even the implied warranty of
>> -    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>> -    GNU General Public License for more details.
>> -*/
>> + * include/linux/comedidev.h
>> + * header file for kernel-only structures, variables, and constants
>> + *
>> + * COMEDI - Linux Control and Measurement Device Interface
>> + * Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org>
>> + *
>> + * This program is free software; you can redistribute it and/or modify
>> + * it under the terms of the GNU General Public License as published by
>> + * the Free Software Foundation; either version 2 of the License, or
>> + * (at your option) any later version.
>> + *
>> + * This program is distributed in the hope that it will be useful,
>> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
>> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>> + * GNU General Public License for more details.
>> + */
>>
>>   #ifndef _COMEDIDEV_H
>>   #define _COMEDIDEV_H
>> @@ -105,7 +105,7 @@ struct comedi_buf_map {
>>         struct kref refcount;
>>   };
>>
>> -/**
>> +/*
>
>
> The '/**' here and on most of the other comments is deliberate.  It is used
> to mark things up with "kernel-doc" - see
> "Documentation/kernel-doc-nano-HOWTO.txt".
>
>>    * struct comedi_async - control data for asynchronous comedi commands
>>    * @prealloc_buf:     preallocated buffer
>>    * @prealloc_bufsz:   buffer size (in bytes)
>> @@ -215,7 +215,7 @@ struct comedi_async {
>>                        unsigned int x);
>>   };
>>
>> -/**
>> +/*
>>    * comedi_async callback "events"
>>    * @COMEDI_CB_EOS:            end-of-scan
>>    * @COMEDI_CB_EOA:            end-of-acquisition/output
>
>
> Admittedly, this wasn't a valid kernel-doc comment, but I'm planning to fix
> that shortly.
>
> Please don't bother fixing this patch as I'm about to send a larger series
> of patches to comedidev.h to add more documentation and I will fix the
> incorrect block comments in that series.
>
> --
> -=( Ian Abbott @ MEV Ltd.    E-mail: <abbotti@mev.co.uk> )=-
> -=(                          Web: http://www.mev.co.uk/  )=-


Yes sir. It was my previous patch .After Greg sir told me about that I
got that mistake afterwards I didnt repeat that mistake in following
patches. and yes you can fix that comments in your patches .

Have a nice day sir ;-)

[PATCH] staging: comedi: Coding style warning fix for block comments

[Jitendra Kumar Khasdev]

This patch is to comedilib.h file that fixes up following warnings
reported by checkpatch.pl :
I) Block comments use * on subsequent lines

Signed-off-by: Jitendra Kumar Khasdev <jkhasdev@gmail.com>
---
 drivers/staging/comedi/comedilib.h | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/drivers/staging/comedi/comedilib.h b/drivers/staging/comedi/comedilib.h
index 56baf85..ccbe17b 100644
--- a/drivers/staging/comedi/comedilib.h
+++ b/drivers/staging/comedi/comedilib.h
@@ -1,20 +1,20 @@
 /*
-    linux/include/comedilib.h
-    header file for kcomedilib
-
-    COMEDI - Linux Control and Measurement Device Interface
-    Copyright (C) 1998-2001 David A. Schleef <ds@schleef.org>
-
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-*/
+ * linux/include/comedilib.h
+ * header file for kcomedilib
+ *
+ * COMEDI - Linux Control and Measurement Device Interface
+ * Copyright (C) 1998-2001 David A. Schleef <ds@schleef.org>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
 
 #ifndef _LINUX_COMEDILIB_H
 #define _LINUX_COMEDILIB_H
-- 
1.9.1

Re: [PATCH] staging: comedi: Coding style warning fix for block comments

[Andy Shevchenko]

On Sun, Nov 22, 2015 at 9:19 PM, Jitendra Kumar Khasdev
<jkhasdev@gmail.com> wrote:
> This patch is to comedilib.h file that fixes up following warnings
> reported by checkpatch.pl :
> I) Block comments use * on subsequent lines
>
> Signed-off-by: Jitendra Kumar Khasdev <jkhasdev@gmail.com>
> ---
>  drivers/staging/comedi/comedilib.h | 32 ++++++++++++++++----------------
>  1 file changed, 16 insertions(+), 16 deletions(-)
>
> diff --git a/drivers/staging/comedi/comedilib.h b/drivers/staging/comedi/comedilib.h
> index 56baf85..ccbe17b 100644
> --- a/drivers/staging/comedi/comedilib.h
> +++ b/drivers/staging/comedi/comedilib.h
> @@ -1,20 +1,20 @@
>  /*
> -    linux/include/comedilib.h

I don't think the file name is somehow useful here.


> -    header file for kcomedilib

Perhaps

* Header file for kcomedilib.

> -
> -    COMEDI - Linux Control and Measurement Device Interface
> -    Copyright (C) 1998-2001 David A. Schleef <ds@schleef.org>
> -
> -    This program is free software; you can redistribute it and/or modify
> -    it under the terms of the GNU General Public License as published by
> -    the Free Software Foundation; either version 2 of the License, or
> -    (at your option) any later version.
> -
> -    This program is distributed in the hope that it will be useful,
> -    but WITHOUT ANY WARRANTY; without even the implied warranty of
> -    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> -    GNU General Public License for more details.
> -*/
> + * linux/include/comedilib.h
> + * header file for kcomedilib
> + *
> + * COMEDI - Linux Control and Measurement Device Interface
> + * Copyright (C) 1998-2001 David A. Schleef <ds@schleef.org>
> + *
> + * This program is free software; you can redistribute it and/or modify
> + * it under the terms of the GNU General Public License as published by
> + * the Free Software Foundation; either version 2 of the License, or
> + * (at your option) any later version.
> + *
> + * This program is distributed in the hope that it will be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> + * GNU General Public License for more details.
> + */
>
>  #ifndef _LINUX_COMEDILIB_H
>  #define _LINUX_COMEDILIB_H
> --
> 1.9.1
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/



-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH] staging: comedi: Coding style warning fix for block comments

[Ian Abbott]

On 22/11/15 19:24, Andy Shevchenko wrote:
> On Sun, Nov 22, 2015 at 9:19 PM, Jitendra Kumar Khasdev
> <jkhasdev@gmail.com> wrote:
>> This patch is to comedilib.h file that fixes up following warnings
>> reported by checkpatch.pl :
>> I) Block comments use * on subsequent lines
>>
>> Signed-off-by: Jitendra Kumar Khasdev <jkhasdev@gmail.com>
>> ---
>>   drivers/staging/comedi/comedilib.h | 32 ++++++++++++++++----------------
>>   1 file changed, 16 insertions(+), 16 deletions(-)
>>
>> diff --git a/drivers/staging/comedi/comedilib.h b/drivers/staging/comedi/comedilib.h
>> index 56baf85..ccbe17b 100644
>> --- a/drivers/staging/comedi/comedilib.h
>> +++ b/drivers/staging/comedi/comedilib.h
>> @@ -1,20 +1,20 @@
>>   /*
>> -    linux/include/comedilib.h
>
> I don't think the file name is somehow useful here.

To be fair, this patch is merely fixing the comment style, rather than 
changing the contents.  Although I wouldn't mind if this line were 
changed, especially as the existing pathname is wrong.

It could be changed to be just the basename of the header file like this:

  * comedilib.h

which is similar to the header comment in comedidev.h.

>
>
>> -    header file for kcomedilib
>
> Perhaps
>
> * Header file for kcomedilib.

No objections there.

-- 
-=( Ian Abbott @ MEV Ltd.    E-mail: <abbotti@mev.co.uk> )=-
-=(                          Web: http://www.mev.co.uk/  )=-

Re: [PATCH] staging: comedi: Coding style warning fix for block comments

[Ian Abbott]

On 22/11/15 19:19, Jitendra Kumar Khasdev wrote:
> This patch is to comedilib.h file that fixes up following warnings
> reported by checkpatch.pl :
> I) Block comments use * on subsequent lines
>
> Signed-off-by: Jitendra Kumar Khasdev <jkhasdev@gmail.com>
> ---
>   drivers/staging/comedi/comedilib.h | 32 ++++++++++++++++----------------
>   1 file changed, 16 insertions(+), 16 deletions(-)

Please could you mention comedilib.h in the Subject line? E.g.:

staging: comedi: comedilib.h: Fix block comments

It helps to localize the affected area more.

-- 
-=( Ian Abbott @ MEV Ltd.    E-mail: <abbotti@mev.co.uk> )=-
-=(                          Web: http://www.mev.co.uk/  )=-