Re: [RFC] Documentation requirements for drm/i915 feature work

[Jesse Barnes <jbarnes@virtuousgeek.org>]

On Fri, 14 Mar 2014 19:16:01 +0100
Daniel Vetter <daniel@ffwll.ch> wrote:

> On Fri, Mar 14, 2014 at 7:03 PM, Jesse Barnes <jbarnes@virtuousgeek.org> wrote:
> > Yeah just saying a man page should be required as part of any new
> > ioctl.
> 
> Yeah I agree and long-term we'll get there. Otherwise I wouldn't have
> added it. But imo for a documentation requirement for merging features
> we need a few things ready first:
> a) Have a somewhat useful skeleton. For drm core Laurent made this
> happen and then the details (mostly api docs) have been slowly filled
> out over the past 1-2 years). Now we're ready to crawl into drivers.
> b) Have someone with good experience with the tooling. I've written
> and reviewed lots of kerneldoc api patches for drm, so I think we're
> covered.
> 
> Those are also the reasons why I'm writing piles of igt docs just now
> - we need a bit a baseline so that people have lots of examples to
> follow and I'm learning the tooling to figure out what works and what
> doesn't. For ioctls we have a bit of manpages, but only for the libdrm
> functions and not the ioctls themselves, and only for drm core stuff.
> 
> Hence why I think ioctl docs aren't for the masses yet. But if someone
> digs in and lays that groundwork and is willing to review patches a
> bit at the beginnning I'll happily support that by rejecting new
> ioctls without such docs.

We have the groundwork in libdrm already, along with a couple of pages,
that's where I'd expect them to land.

-- 
Jesse Barnes, Intel Open Source Technology Center