Re: [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers

[Daniel Vetter <daniel@ffwll.ch>]

On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote:
> >>
> >> If we decide to go for property documentation inside the source code then I
> >> believe we'll have to create our own format, as creating a properties table
> >> from kerneldoc information extracted from comments is probably not possible.
> >
> > Can comeone pick up the ball here and figure out what needs to be done?
> >
> > The reason why I want a central place for the documentation is to force
> > people to collaborate outside their own sandbox when adding properties.
> > Whether that's docbook or some text file I don't care so much at this
> > point. The fact that it's a central place should mandate that the
> > patches changing it will go through dri-devel and so everyone should se
> > them, and when adding new properties it would make the patch author more
> > likely to look around a bit before adding another slighty incompatible
> > version of the same property. If someone has a better suggestion how to
> > encforce this I'm all ears.
> >
> > Of course this idea can still fail if our esteemed maintainer merges
> > stuff without checking for violations of this policy. Dave, any thoughts
> > on the subject?
> 
> Yeah I'm happy to block merging stuff, if we can spot new properties
> when stuff is posted on dri-devel, so much the better,
> 
> most drivers still send everything via dri-devel anyways, its only
> really Intel I have to worry about so far,

I'll enforce that all prop stuff gets cc: dri-devel and that it has
updates for the prop docs.

> But we should definitely add it to the new driver review checklist as well.
> 
> I'm also on the side of this patch is ugly and makes my eyes burn,
> please please get a plan to use something else ASAP, I'm willing to
> merge this but I'm tempted to give it a lifetime of a kernel or two
> before I burn it.

Ok, I'll try to move "make kerneldoc suck less" up the task list and maybe
find someone to do it for me internally ;-)
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch