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 <dan...@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 <conselv...@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 _______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
