[Intel-gfx] [PATCH] drm/i915: add kerneldoc for i915_audio_component

[Yang, Libin]

Hi Daniel,

As Takashi has already accepted the first 3 patches for 
sync_audio_rate() and the patches are not merged
into -nightly branch. If I make a kerneldoc patch
based on currently -nightly branch, there will
be conflict when you are merging Takashi's branch.

What do you think if I make the kerneldoc patch
after the sync_audio_rate() patches are merged
into the -nightly branch?

Regards,
Libin


> -----Original Message-----
> From: Daniel Vetter [mailto:daniel.vetter at ffwll.ch] On Behalf Of
> Daniel Vetter
> Sent: Friday, September 04, 2015 3:55 PM
> To: Jani Nikula
> Cc: Yang, Libin; Daniel Vetter; intel-gfx at lists.freedesktop.org;
> daniel.vetter at ffwll.ch; ville.syrjala at linux.intel.com
> Subject: Re: [PATCH] drm/i915: add kerneldoc for
> i915_audio_component
> 
> On Fri, Sep 04, 2015 at 09:40:17AM +0300, Jani Nikula wrote:
> > On Fri, 04 Sep 2015, "Yang, Libin" <libin.yang at intel.com> wrote:
> > >> -----Original Message-----
> > >> From: Daniel Vetter [mailto:daniel.vetter at ffwll.ch] On Behalf Of
> > >> Daniel Vetter
> > >> Sent: Wednesday, September 02, 2015 8:18 PM
> > >> To: Yang, Libin
> > >> Cc: intel-gfx at lists.freedesktop.org; daniel.vetter at ffwll.ch;
> > >> jani.nikula at linux.intel.com; ville.syrjala at linux.intel.com
> > >> Subject: Re: [PATCH] drm/i915: add kerneldoc for
> > >> i915_audio_component
> > >>
> > >> On Wed, Sep 02, 2015 at 02:12:24PM +0800,
> libin.yang at intel.com
> > >> wrote:
> > >> > From: Libin Yang <libin.yang at intel.com>
> > >> >
> > >> > Add the kerneldoc for i915_audio_component in
> i915_component.h
> > >> >
> > >> > Signed-off-by: Libin Yang <libin.yang at intel.com>
> > >> > ---
> > >> >  include/drm/i915_component.h | 39
> ++++++++++++++++++++++++--
> > >> -------------
> > >> >  1 file changed, 24 insertions(+), 15 deletions(-)
> > >> >
> > >> > diff --git a/include/drm/i915_component.h
> > >> b/include/drm/i915_component.h
> > >> > index 8ad6f1b..187acc8 100644
> > >> > --- a/include/drm/i915_component.h
> > >> > +++ b/include/drm/i915_component.h
> > >> > @@ -24,23 +24,32 @@
> > >> >  #ifndef _I915_COMPONENT_H_
> > >> >  #define _I915_COMPONENT_H_
> > >> >
> > >> > +/**
> > >> > + * struct i915_audio_component_ops - callbacks defined in gfx
> > >> driver
> > >> > + * @owner: the module owner
> > >> > + * @get_power: get the POWER_DOMAIN_AUDIO power well
> > >> > + * @put_power: put the POWER_DOMAIN_AUDIO power well
> > >> > + * @codec_wake_override: Enable/Disable generating the
> codec
> > >> wake signal
> > >> > + * @get_cdclk_freq: get the Core Display Clock in KHz
> > >> > + * @sync_audio_rate: set n/cts based on the sample rate
> > >> > + */
> > >> > +struct i915_audio_component_ops {
> > >> > +	struct module *owner;
> > >>
> > >> New kerneldoc in 4.3 allows you to split structure documentation
> up
> > >> into
> > >> per-member comments. Especially with vtables I think this makes
> a lot
> > >> of
> > >> sense, since then you have enough space to document where and
> how
> > >> exactly
> > >> a given hook is called (looks, place in the overall sequence).
> > >>
> > >> Also please include your stancas in the drm.tmpl docbook
> template,
> > >> otherwise it won't be included in the html docs. And finally please
> add
> > >
> > > OK, I will add it in drm.tmpl.
> > >
> > >> a
> > >> DOC: overview section which explains at a high level how i915 and
> > >> hda-intel corporate for hdmi/dp audio.
> > >
> > > Where the DOC should be located in?
> >
> > i915/intel_audio.c already has a "DOC: High Definition Audio over
> HDMI
> > and Display Port" comment. IMO you could just amend that, as
> there's
> > already some references to the audio driver.
> 
> Yeah I think that would be a perfect place.
> -Daniel
> --
> Daniel Vetter
> Software Engineer, Intel Corporation
> http://blog.ffwll.ch