[PATCH v3 0/2] fix kernel-docs for struct iio_trigger

[PATCH v3 0/2] fix kernel-docs for struct iio_trigger

[Tobin C. Harding]

This series was inspired by a warning emitted by sphinx when running
kernel make target 'htmldocs'.

	warning: No description found for parameter 'owner'

Patch 1 adds a kernel-doc description for field @owner.

Patch 2 adds field identifier to kernel-doc string (for @use_count).

v3:
 - Fix up patch title to include correct version number.

v2:
 - Change field identifier from DRIVER to INTERN.
 - Add second patch, change subject line.

v1:
 - [PATCH] iio: add kernel-doc '@owner'

Tobin C. Harding (2):
  iio: add kernel-doc for field @owner
  iio: add field identifier for @use_count kernel-doc

 include/linux/iio/trigger.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

-- 
2.7.4

[PATCH v3 1/2] iio: add kernel-doc for field @owner

[Tobin C. Harding]

When building kernel documentation sphinx emits the following warning

	warning: No description found for parameter 'owner'

Add description for struct member 'owner'.

Signed-off-by: Tobin C. Harding <me@tobin.cc>
---
 include/linux/iio/trigger.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/linux/iio/trigger.h b/include/linux/iio/trigger.h
index 7d5e44518379..390789d43369 100644
--- a/include/linux/iio/trigger.h
+++ b/include/linux/iio/trigger.h
@@ -43,6 +43,7 @@ struct iio_trigger_ops {
 /**
  * struct iio_trigger - industrial I/O trigger device
  * @ops:		[DRIVER] operations structure
+ * @owner:		[INTERN] owner of this driver module
  * @id:			[INTERN] unique id number
  * @name:		[DRIVER] unique name
  * @dev:		[DRIVER] associated device (if relevant)
-- 
2.7.4

[PATCH v3 2/2] iio: add field identifier for @use_count kernel-doc

[Tobin C. Harding]

Kernel-doc for @use_count does not currently have a field identifier.
All the rest of the fields do. @use_count is used internally and should
not be accessed directly by the driver so it should be marked as so.

Add [INTERN] identifier to @use_count field.

Signed-off-by: Tobin C. Harding <me@tobin.cc>
---
 include/linux/iio/trigger.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/iio/trigger.h b/include/linux/iio/trigger.h
index 390789d43369..b19b7204ef84 100644
--- a/include/linux/iio/trigger.h
+++ b/include/linux/iio/trigger.h
@@ -49,7 +49,7 @@ struct iio_trigger_ops {
  * @dev:		[DRIVER] associated device (if relevant)
  * @list:		[INTERN] used in maintenance of global trigger list
  * @alloc_list:		[DRIVER] used for driver specific trigger list
- * @use_count:		use count for the trigger
+ * @use_count:		[INTERN] use count for the trigger.
  * @subirq_chip:	[INTERN] associate 'virtual' irq chip.
  * @subirq_base:	[INTERN] base number for irqs provided by trigger.
  * @subirqs:		[INTERN] information about the 'child' irqs.
-- 
2.7.4

Re: [PATCH v3 1/2] iio: add kernel-doc for field @owner

[Jonathan Cameron]

On Sun,  7 Jan 2018 08:56:05 +1100
"Tobin C. Harding" <me@tobin.cc> wrote:

> When building kernel documentation sphinx emits the following warning
> 
> 	warning: No description found for parameter 'owner'
> 
> Add description for struct member 'owner'.
> 
> Signed-off-by: Tobin C. Harding <me@tobin.cc>
Applied to the togreg branch of iio.git and pushed out as testing for
the autobuilders to play with it.

Thanks,

Jonathan

> ---
>  include/linux/iio/trigger.h | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/include/linux/iio/trigger.h b/include/linux/iio/trigger.h
> index 7d5e44518379..390789d43369 100644
> --- a/include/linux/iio/trigger.h
> +++ b/include/linux/iio/trigger.h
> @@ -43,6 +43,7 @@ struct iio_trigger_ops {
>  /**
>   * struct iio_trigger - industrial I/O trigger device
>   * @ops:		[DRIVER] operations structure
> + * @owner:		[INTERN] owner of this driver module
>   * @id:			[INTERN] unique id number
>   * @name:		[DRIVER] unique name
>   * @dev:		[DRIVER] associated device (if relevant)

Re: [PATCH v3 2/2] iio: add field identifier for @use_count kernel-doc

[Jonathan Cameron]

On Sun,  7 Jan 2018 08:56:06 +1100
"Tobin C. Harding" <me@tobin.cc> wrote:

> Kernel-doc for @use_count does not currently have a field identifier.
> All the rest of the fields do. @use_count is used internally and should
> not be accessed directly by the driver so it should be marked as so.
> 
> Add [INTERN] identifier to @use_count field.
> 
> Signed-off-by: Tobin C. Harding <me@tobin.cc>
Applied to the togreg branch of iio.git and pushed out as testing
for the autobuilder to play with it.

Thanks,

Jonathan

> ---
>  include/linux/iio/trigger.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/linux/iio/trigger.h b/include/linux/iio/trigger.h
> index 390789d43369..b19b7204ef84 100644
> --- a/include/linux/iio/trigger.h
> +++ b/include/linux/iio/trigger.h
> @@ -49,7 +49,7 @@ struct iio_trigger_ops {
>   * @dev:		[DRIVER] associated device (if relevant)
>   * @list:		[INTERN] used in maintenance of global trigger list
>   * @alloc_list:		[DRIVER] used for driver specific trigger list
> - * @use_count:		use count for the trigger
> + * @use_count:		[INTERN] use count for the trigger.
>   * @subirq_chip:	[INTERN] associate 'virtual' irq chip.
>   * @subirq_base:	[INTERN] base number for irqs provided by trigger.
>   * @subirqs:		[INTERN] information about the 'child' irqs.