[Intel-gfx] [PATCH 5/7] drm/i915: Update kerneldoc for intel_dpll_mgr.c

[Ander Conselvan De Oliveira]

On Thu, 2016-10-20 at 11:19 +0300, Jani Nikula wrote:
> On Thu, 20 Oct 2016, Daniel Vetter <daniel at ffwll.ch> wrote:
> > 
> > On Wed, Oct 19, 2016 at 06:29:13PM +0300, Jani Nikula wrote:
> > > 
> > > On Wed, 19 Oct 2016, Ander Conselvan De Oliveira <conselvan2 at gmail.com>
> > > wrote:
> > > > 
> > > > On Thu, 2016-10-13 at 15:46 +0200, Daniel Vetter wrote:
> > > > > 
> > > > > > 
> > > > > > +	/**
> > > > > > +	 * @hw_state: hardware configuration for the DPLL.
> > > > > "... stored in struct &intel_dpll_hw_state." - I love my hyperlinks ;-
> > > > > )
> > > > I'll add that, but I think it's silly. The type of the field is struct
> > > > intel_dpll_hw_state, so I think it would be more natural if the
> > > > documentation
> > > > tool would add that link automatically.
> > > Agreed.
> > Someone volunteering? I'd hope it would be at most a bit of shuffling with
> > the generator, we should have the type and all that handy already. Except
> > maybe lots of corner-cases ...
> I think the problem was that I couldn't figure out how to make Sphinx do
> cross references within inline preformatted text. And I thought that was
> less important than fixing up the struct presentation that I'm not all
> too happy about currently. See [1] first. I don't think we need to have
> both the definition and members. It's just wasted vertical space.
> 
> I'd suggest we drop the definition altogether, and have the members list
> contain the member types, ideally with cross-references. If that means
> having to use normal font instead of monospace, I'd go with it anyway.
> 
> Thoughts?

I think that makes sense. There's no extra information there (and if you forget
to add a kerneldoc tag to a field, it isn't even listed). The definition is in
the code anyway.

I was actually a bit surprised to see the definition in the doc the first time.

Ander