From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jesse Barnes Subject: Re: [RFC] Documentation requirements for drm/i915 feature work Date: Fri, 14 Mar 2014 11:24:19 -0700 Message-ID: <20140314112419.090c5a50@jbarnes-desktop> References: <20140311112132.GD30571@phenom.ffwll.local> <20140314100608.2e5df1ad@jbarnes-desktop> <20140314110325.5b100f80@jbarnes-desktop> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: Received: from gproxy5-pub.mail.unifiedlayer.com (gproxy5-pub.mail.unifiedlayer.com [67.222.38.55]) by gabe.freedesktop.org (Postfix) with SMTP id 69292FB4D5 for ; Fri, 14 Mar 2014 11:23:38 -0700 (PDT) In-Reply-To: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: intel-gfx-bounces@lists.freedesktop.org Errors-To: intel-gfx-bounces@lists.freedesktop.org To: Daniel Vetter Cc: Intel Graphics Development List-Id: intel-gfx@lists.freedesktop.org On Fri, 14 Mar 2014 19:16:01 +0100 Daniel Vetter wrote: > On Fri, Mar 14, 2014 at 7:03 PM, Jesse Barnes 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