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

[Daniel Vetter]

On Thu, Oct 20, 2016 at 11:56:07AM +0300, Ander Conselvan De Oliveira wrote:
> 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.

Assuming we're talking just about structs here: +1. For functions we
already have the signature in the heading, and that also already
hyperlinks.

There's also the difference that the detailed list has the full type+name,
whereas structs only have the name. I like the style used in functions
much more (and then we could just nuke the definition I think), and then
hyperlink them properly.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch