Re: [RFC] Documentation requirements for drm/i915 feature work

[Jesse Barnes <jbarnes@virtuousgeek.org>]

On Fri, 14 Mar 2014 19:00:46 +0100
Daniel Vetter <daniel@ffwll.ch> wrote:

> On Fri, Mar 14, 2014 at 6:06 PM, Jesse Barnes <jbarnes@virtuousgeek.org> 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