From: Daniel Vetter <daniel@ffwll.ch>
To: Ander Conselvan De Oliveira <conselvan2@gmail.com>
Cc: intel-gfx@lists.freedesktop.org
Subject: Re: [PATCH 5/7] drm/i915: Update kerneldoc for intel_dpll_mgr.c
Date: Thu, 20 Oct 2016 11:12:24 +0200 [thread overview]
Message-ID: <20161020091223.GP20761@phenom.ffwll.local> (raw)
In-Reply-To: <1476953767.3327.5.camel@gmail.com>
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@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@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
next prev parent reply other threads:[~2016-10-20 9:12 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-10-04 12:32 [PATCH 0/7] Shared DPLL kernel doc and improvements Ander Conselvan de Oliveira
2016-10-04 12:32 ` [PATCH 1/7] drm/i915: Introduce intel_release_shared_dpll() Ander Conselvan de Oliveira
2016-10-13 13:24 ` Daniel Vetter
2016-10-04 12:32 ` [PATCH 2/7] drm/i915: Rename intel_shared_dpll_commit() to _swap_state() Ander Conselvan de Oliveira
2016-10-13 13:25 ` Daniel Vetter
2016-10-04 12:32 ` [PATCH 3/7] drm/i915: Rename intel_shared_dpll_config to intel_shared_dpll_state Ander Conselvan de Oliveira
2016-10-13 13:25 ` Daniel Vetter
2016-10-04 12:32 ` [PATCH 4/7] drm/i915: Rename intel_shared_dpll->mode_set() to prepare() Ander Conselvan de Oliveira
2016-10-13 13:26 ` Daniel Vetter
2016-10-04 12:32 ` [PATCH 5/7] drm/i915: Update kerneldoc for intel_dpll_mgr.c Ander Conselvan de Oliveira
2016-10-13 13:46 ` Daniel Vetter
2016-10-19 12:03 ` Ander Conselvan De Oliveira
2016-10-19 15:29 ` Jani Nikula
2016-10-20 6:50 ` Daniel Vetter
2016-10-20 8:19 ` Jani Nikula
2016-10-20 8:56 ` Ander Conselvan De Oliveira
2016-10-20 9:12 ` Daniel Vetter [this message]
2016-10-04 12:32 ` [PATCH 6/7] drm/i915: Add dpll entrypoint for dumping hw state Ander Conselvan de Oliveira
2016-10-13 13:47 ` Daniel Vetter
2016-10-04 12:32 ` [PATCH 7/7] drm/i915: Add entrypoints for mapping dplls to encoders and crtcs Ander Conselvan de Oliveira
2016-10-13 13:53 ` Daniel Vetter
2016-10-04 13:19 ` ✗ Fi.CI.BAT: warning for Shared DPLL kernel doc and improvements Patchwork
-- strict thread matches above, loose matches on Subject: below --
2016-12-29 15:22 [PATCH v2 0/7] " Ander Conselvan de Oliveira
2016-12-29 15:22 ` [PATCH 5/7] drm/i915: Update kerneldoc for intel_dpll_mgr.c Ander Conselvan de Oliveira
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20161020091223.GP20761@phenom.ffwll.local \
--to=daniel@ffwll.ch \
--cc=conselvan2@gmail.com \
--cc=intel-gfx@lists.freedesktop.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox