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:03:25 -0700 Message-ID: <20140314110325.5b100f80@jbarnes-desktop> References: <20140311112132.GD30571@phenom.ffwll.local> <20140314100608.2e5df1ad@jbarnes-desktop> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: Received: from gproxy1-pub.mail.unifiedlayer.com (gproxy1-pub.mail.unifiedlayer.com [69.89.25.95]) by gabe.freedesktop.org (Postfix) with SMTP id 2069BFB467 for ; Fri, 14 Mar 2014 11:09:27 -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:00:46 +0100 Daniel Vetter wrote: > On Fri, Mar 14, 2014 at 6:06 PM, Jesse Barnes wrote: > >> 3) Documentating userspace ABIs like ioctls structures&flags, properties > >> and so on. > >> > >> I have no idea how to do 3) well, see e.g. the discussion on documenting > >> drm properties. And the drm core is completely undocumented in that area > >> anyway afaik. So I think we can postpone this for now. > > > > IMO (3) very much belongs in libdrm as man page updates. We need to be > > good about catching this on review for new stuff. > > > > For older stuff I think there was a bit of momentum awhile back, but it > > seems to have dissipated. > > > > We could try to extract it from kernel source somehow, but for user API > > stuff, I think we really want man pages in libdrm, in addition to > > whatever web based documentation we make available. > > Yeah, I think manpages are a nice form for documenting ioctls - they > more easily allow grouping of related things and the layout lends it > self well for specs imo. But for now I'm ok with just the > documentation we have in the form of code as igt testcases. And I also > think that internal driver docs (and igt test helper library docs > fwiw) are the more immediately useful areas, so I won't pour effort > into ioctls docs for now. > > But if someone else wants to go wild I'll happily support such an effort. Yeah just saying a man page should be required as part of any new ioctl. -- Jesse Barnes, Intel Open Source Technology Center