Re: [PATCH 5/7] drm/i915: Update kerneldoc for intel_dpll_mgr.c

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Thu, 2016-10-20 at 11:19 +0300, Jani Nikula wrote:
> On Thu, 20 Oct 2016, Daniel Vetter <daniel@xxxxxxxx> wrote:
> > 
> > On Wed, Oct 19, 2016 at 06:29:13PM +0300, Jani Nikula wrote:
> > > 
> > > On Wed, 19 Oct 2016, Ander Conselvan De Oliveira <conselvan2@xxxxxxxxx>
> > > 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
_______________________________________________
Intel-gfx mailing list
Intel-gfx@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/intel-gfx




[Index of Archives]     [Linux USB Devel]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]
  Powered by Linux