[alsa-devel] [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 at 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