From mboxrd@z Thu Jan 1 00:00:00 1970 From: Randy Dunlap Subject: Re: [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers Date: Mon, 12 May 2014 08:23:45 -0700 Message-ID: <5370E781.1080308@infradead.org> References: <1394016990-5218-1-git-send-email-sagar.a.kamble@intel.com> <2919182.UBDg5nOr7Z@avalon> <1394622965.18918.12.camel@sagar-desktop> <3136468.2PAlK4Gq8k@avalon> <20140510103937.GC18465@intel.com> <20140512085827.GD25056@phenom.ffwll.local> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <20140512085827.GD25056@phenom.ffwll.local> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" To: Daniel Vetter , Dave Airlie Cc: Laurent Pinchart , linux-doc@vger.kernel.org, Daniel Vetter , intel-gfx , dri-devel , Laurent Pinchart , Rob Landley , Alex Deucher , Dave Airlie , Sagar Arun Kamble List-Id: intel-gfx@lists.freedesktop.org On 05/12/2014 01:58 AM, Daniel Vetter wrote: > 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 > I certainly have no objections to making kerneldoc suck less. There was already an attempt to use asciidoc (like git uses) for kernel-doc (a few years ago, by Sam Ravnborg). I support(ed) that effort. OTOH, I would only want to add another way to do kernel-doc if it can be a full replacement for all of our docbook usage, i.e., it should provide a way that we can eliminate docbook and stop using it completely. thanks, -- ~Randy