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 10:06:08 -0700 Message-ID: <20140314100608.2e5df1ad@jbarnes-desktop> References: <20140311112132.GD30571@phenom.ffwll.local> 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 1C416FB438 for ; Fri, 14 Mar 2014 10:12:10 -0700 (PDT) In-Reply-To: <20140311112132.GD30571@phenom.ffwll.local> 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 Tue, 11 Mar 2014 12:21:32 +0100 Daniel Vetter wrote: > Hi all, > > So I guess people have seen the writing on the wall since a while ;-) > > So with my latest drm kerneldoc series we'll have fairly nice interface > docs for most of the still relevant drm core subsystems. Which means we > can finally start to look at our own driver. I've already started with a > very basic skeleton as part of my latest kerneldoc series, see > > http://people.freedesktop.org/~danvet/drm/drmI915.html > > Now we only need to flesh this out! > > I see three areas where decent documentation provides good value: > > 1) High level overviews of a feature, i.e. what I've done thus far in my > blog posts. > > 2) Detailed in-driver api documentation as kerneldoc. > > 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. -- Jesse Barnes, Intel Open Source Technology Center