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

[Jesse Barnes]

On Tue, 11 Mar 2014 12:21:32 +0100
Daniel Vetter <daniel at ffwll.ch> 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