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