[Intel-gfx] [RFC] Documentation requirements for drm/i915 feature work

[Daniel Vetter]

On Fri, Mar 14, 2014 at 7:03 PM, Jesse Barnes <jbarnes at 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.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch