From: Daniel Vetter <daniel@ffwll.ch>
To: Chris Wilson <chris@chris-wilson.co.uk>,
Daniel Vetter <daniel.vetter@ffwll.ch>,
DRI Development <dri-devel@lists.freedesktop.org>,
Joonas Lahtinen <joonas.lahtinen@linux.intel.com>,
Daniel Vetter <daniel.vetter@intel.com>
Subject: Re: [PATCH] drm/mm: Some doc polish
Date: Thu, 29 Dec 2016 11:35:48 +0100 [thread overview]
Message-ID: <20161229103548.GA26729@dvetter-linux.ger.corp.intel.com> (raw)
In-Reply-To: <20161228173726.GL1717@nuc-i3427.alporthouse.com>
On Wed, Dec 28, 2016 at 05:37:26PM +0000, Chris Wilson wrote:
> On Wed, Dec 28, 2016 at 05:57:40PM +0100, Daniel Vetter wrote:
> > @@ -230,23 +272,23 @@ static inline u64 drm_mm_hole_node_end(const struct drm_mm_node *hole_node)
> >
> > /**
> > * drm_mm_for_each_node - iterator to walk over all allocated nodes
> > - * @entry: drm_mm_node structure to assign to in each iteration step
> > - * @mm: drm_mm allocator to walk
> > + * @entry: &drm_mm_node structure to assign to in each iteration step
>
> If we have the &struct link, do we need to say "structure"?
> We use a mix of "&struct structure" and plain "&struct". Choose a style
> and make it consistent. (Bonus points for an easy to find style guide.)
There's also "struct &struct_name" and "&struct struct_name". Anything
goes really, and I just semi-randomly pick what reads reasonably well. The
issue with macros is that they don't have the types in the declaration
(compared to functions), that's why I added the &.
And I think indicating the text that it's a structure makes some sense,
since the link could also be to an enum.
Anyway if you insist I can do some ocd for drm_mm, but for all of the drm
docs is a bit much.
Oh and the style guides we have:
https://dri.freedesktop.org/docs/drm/doc-guide/sphinx.html#writing-documentation
https://dri.freedesktop.org/docs/drm/gpu/introduction.html#style-guidelines
Reminds me, should add a link from the drm guidelines to the overall ones.
-Daniel
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
next prev parent reply other threads:[~2016-12-29 10:35 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-12-28 15:25 [PATCH 1/2] drm/docs: Small cleanup in drm-uapi.rst Daniel Vetter
2016-12-28 15:25 ` [PATCH 2/2] drm/mm: Some doc polish Daniel Vetter
2016-12-28 15:46 ` Chris Wilson
2016-12-28 16:57 ` [PATCH] " Daniel Vetter
2016-12-28 17:37 ` Chris Wilson
2016-12-29 10:35 ` Daniel Vetter [this message]
2016-12-29 10:54 ` Chris Wilson
2016-12-29 11:04 ` Jani Nikula
2016-12-29 11:08 ` Daniel Vetter
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=20161229103548.GA26729@dvetter-linux.ger.corp.intel.com \
--to=daniel@ffwll.ch \
--cc=chris@chris-wilson.co.uk \
--cc=daniel.vetter@ffwll.ch \
--cc=daniel.vetter@intel.com \
--cc=dri-devel@lists.freedesktop.org \
--cc=joonas.lahtinen@linux.intel.com \
/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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.