[PATCH] drm/i915: Improve kernel-doc for i915_audio_component struct

[PATCH] drm/i915: Improve kernel-doc for i915_audio_component struct

[David Henningsson]

To make kernel-doc happy, the i915_audio_component_audio_ops struct
cannot be nested.

Signed-off-by: David Henningsson <david.henningsson@canonical.com>
---

Note that I didn't do the same un-nesting for i915_audio_component_ops.
This is to make it easier to merge the pending sync_audio_rate patch set.

It applies on top of my just sent patches so should probably be taken
through Takashi's tree.

 Documentation/DocBook/drm.tmpl |  1 +
 include/drm/i915_component.h   | 33 +++++++++++++++++++++++----------
 2 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 2fb9a54..7554679 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -4048,6 +4048,7 @@ int num_ioctls;</synopsis>
 	<title>High Definition Audio</title>
 !Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port
 !Idrivers/gpu/drm/i915/intel_audio.c
+!Iinclude/drm/i915_component.h
       </sect2>
       <sect2>
 	<title>Panel Self Refresh PSR (PSR/SRD)</title>
diff --git a/include/drm/i915_component.h b/include/drm/i915_component.h
index b2d56dd..89d6362 100644
--- a/include/drm/i915_component.h
+++ b/include/drm/i915_component.h
@@ -24,6 +24,28 @@
 #ifndef _I915_COMPONENT_H_
 #define _I915_COMPONENT_H_
 
+/**
+ * struct i915_audio_component_audio_ops - i915 directly calling hda driver
+ *
+ * @audio_ptr: Pointer to pass when calling pin_eld_notify.
+ * @pin_eld_notify: Called from i915 driver, notifying the HDA driver that
+ * pin sense and/or ELD information has changed.
+ *
+ * These functions are implemented by hda driver and called by the i915
+ * driver.
+ */
+struct i915_audio_component_audio_ops {
+	void *audio_ptr;
+	void (*pin_eld_notify)(void *audio_ptr, int port);
+};
+
+/**
+ * struct i915_audio_component - Used for direct communication between i915 and hda drivers
+ *
+ * @dev: i915 device, used as parameter for ops
+ * @ops: Ops implemented by i915 driver, called by hda driver
+ * @audio_ops: Ops implemented by hda driver, called by i915 driver
+ */
 struct i915_audio_component {
 	struct device *dev;
 
@@ -35,16 +57,7 @@ struct i915_audio_component {
 		int (*get_cdclk_freq)(struct device *);
 	} *ops;
 
-	const struct i915_audio_component_audio_ops {
-		void *audio_ptr;
-		/**
-		 * Call from i915 driver, notifying the HDA driver that
-		 * pin sense and/or ELD information has changed.
-		 * @audio_ptr:		HDA driver object
-		 * @port:		Which port has changed (PORTA / PORTB / PORTC etc)
-		 */
-		void (*pin_eld_notify)(void *audio_ptr, int port);
-	} *audio_ops;
+	const struct i915_audio_component_audio_ops *audio_ops;
 };
 
 #endif /* _I915_COMPONENT_H_ */
-- 
1.9.1

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH] drm/i915: Improve kernel-doc for i915_audio_component struct

[Daniel Vetter]

On Thu, Sep 03, 2015 at 01:24:45PM +0200, David Henningsson wrote:
> To make kernel-doc happy, the i915_audio_component_audio_ops struct
> cannot be nested.
> 
> Signed-off-by: David Henningsson <david.henningsson@canonical.com>
> ---
> 
> Note that I didn't do the same un-nesting for i915_audio_component_ops.
> This is to make it easier to merge the pending sync_audio_rate patch set.
> 
> It applies on top of my just sent patches so should probably be taken
> through Takashi's tree.
> 
>  Documentation/DocBook/drm.tmpl |  1 +
>  include/drm/i915_component.h   | 33 +++++++++++++++++++++++----------
>  2 files changed, 24 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 2fb9a54..7554679 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -4048,6 +4048,7 @@ int num_ioctls;</synopsis>
>  	<title>High Definition Audio</title>
>  !Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port
>  !Idrivers/gpu/drm/i915/intel_audio.c
> +!Iinclude/drm/i915_component.h
>        </sect2>
>        <sect2>
>  	<title>Panel Self Refresh PSR (PSR/SRD)</title>
> diff --git a/include/drm/i915_component.h b/include/drm/i915_component.h
> index b2d56dd..89d6362 100644
> --- a/include/drm/i915_component.h
> +++ b/include/drm/i915_component.h
> @@ -24,6 +24,28 @@
>  #ifndef _I915_COMPONENT_H_
>  #define _I915_COMPONENT_H_
>  
> +/**
> + * struct i915_audio_component_audio_ops - i915 directly calling hda driver
> + *
> + * @audio_ptr: Pointer to pass when calling pin_eld_notify.
> + * @pin_eld_notify: Called from i915 driver, notifying the HDA driver that
> + * pin sense and/or ELD information has changed.

I think we should have a bit more detail here where exactly this gets
called. Also please use the new inline style for struct members.

/**
 * struct foo - foo
 * 
 * High level description.
 */
struct foo {
	/**
	 * @bar:
	 *
	 * Longer text for bar.
	 */
	int bar;
};

Also does your patch build correctly with make htmldocs? Iirc for the old
style you used continuation lines for @bar: need to be indented ...
-Daniel


> + *
> + * These functions are implemented by hda driver and called by the i915
> + * driver.
> + */
> +struct i915_audio_component_audio_ops {
> +	void *audio_ptr;
> +	void (*pin_eld_notify)(void *audio_ptr, int port);
> +};
> +
> +/**
> + * struct i915_audio_component - Used for direct communication between i915 and hda drivers
> + *
> + * @dev: i915 device, used as parameter for ops
> + * @ops: Ops implemented by i915 driver, called by hda driver
> + * @audio_ops: Ops implemented by hda driver, called by i915 driver
> + */
>  struct i915_audio_component {
>  	struct device *dev;
>  
> @@ -35,16 +57,7 @@ struct i915_audio_component {
>  		int (*get_cdclk_freq)(struct device *);
>  	} *ops;
>  
> -	const struct i915_audio_component_audio_ops {
> -		void *audio_ptr;
> -		/**
> -		 * Call from i915 driver, notifying the HDA driver that
> -		 * pin sense and/or ELD information has changed.
> -		 * @audio_ptr:		HDA driver object
> -		 * @port:		Which port has changed (PORTA / PORTB / PORTC etc)
> -		 */
> -		void (*pin_eld_notify)(void *audio_ptr, int port);
> -	} *audio_ops;
> +	const struct i915_audio_component_audio_ops *audio_ops;
>  };
>  
>  #endif /* _I915_COMPONENT_H_ */
> -- 
> 1.9.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH] drm/i915: Improve kernel-doc for i915_audio_component struct

[David Henningsson]

On 2015-09-04 10:03, Daniel Vetter wrote:
> Also please use the new inline style for struct members.

I tried that, but I couldn't get it to work. This was with Takashi's 
for-next tree, do I need to apply some docbook special patches on top of 
that to get the new functionality?

-- 
David Henningsson, Canonical Ltd.
https://launchpad.net/~diwic
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH] drm/i915: Improve kernel-doc for i915_audio_component struct

[Takashi Iwai]

On Fri, 04 Sep 2015 12:33:45 +0200,
David Henningsson wrote:
> 
> 
> 
> On 2015-09-04 10:03, Daniel Vetter wrote:
> > Also please use the new inline style for struct members.
> 
> I tried that, but I couldn't get it to work. This was with Takashi's 
> for-next tree, do I need to apply some docbook special patches on top of 
> that to get the new functionality?

I think you need to pull your changes onto the latest Linus tree.
The new docbook stuff was merged for 4.3, IIRC.


Takashi
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx