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

[Jani Nikula]

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?

BR,
Jani.


[1] https://01.org/linuxgraphics/gfx-docs/drm/driver-api/infrastructure.html#c.device_driver

>
> And ack on the struct layout bikeshed I had.
> -Daniel

-- 
Jani Nikula, Intel Open Source Technology Center