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

[Daniel Vetter]

On Fri, Mar 14, 2014 at 6:06 PM, Jesse Barnes <jbarnes at 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.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch