From mboxrd@z Thu Jan 1 00:00:00 1970 From: Daniel Vetter Subject: Re: [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers Date: Mon, 12 May 2014 10:03:55 +0200 Message-ID: <20140512080355.GB25056@phenom.ffwll.local> 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> <1399874873.15218.32.camel@sagar-desktop> Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Return-path: Received: from mail-ee0-f43.google.com (mail-ee0-f43.google.com [74.125.83.43]) by gabe.freedesktop.org (Postfix) with ESMTP id 215116E458 for ; Mon, 12 May 2014 01:04:00 -0700 (PDT) Received: by mail-ee0-f43.google.com with SMTP id d17so4326498eek.16 for ; Mon, 12 May 2014 01:04:00 -0700 (PDT) Content-Disposition: inline In-Reply-To: <1399874873.15218.32.camel@sagar-desktop> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Sagar Arun Kamble Cc: Laurent Pinchart , linux-doc@vger.kernel.org, Daniel Vetter , intel-gfx , shashidhar.hiremath@intel.com, "dri-devel@lists.freedesktop.org" , "Purushothaman, Vijay A" , Laurent Pinchart , Rob Landley , Alex Deucher , Dave Airlie List-Id: dri-devel@lists.freedesktop.org On Mon, May 12, 2014 at 11:37:53AM +0530, Sagar Arun Kamble wrote: > I support approach using docbook to start since there are not lot of > properties. Laurent has ack'ed this one. Can we go ahead with this? > http://lists.freedesktop.org/archives/intel-gfx/2014-March/041527.html > = > Adding description of new property is not very complex (assuming table > format is understood and being comfortable with HTML row/table > manipulation). > = > Adding description of each property in their source might be time > consuming task. Yeah I'm ok with docbook for the time being. My long-term plan is to fix up kerneldoc to support markdown and then we can move such neat tables into the code. There's lots other places that would benefit from proper list formatting and tables. So Ack from my side on both the docbook patch and the no-more-props-without-doc-patch rule (which is kinda what I've been doing thus far). -Daniel > = > thanks, > Sagar > = > = > On Sat, 2014-05-10 at 06:56 -0400, Rob Clark wrote: > > On Sat, May 10, 2014 at 6:39 AM, Ville Syrj=E4l=E4 > > wrote: > > > On Wed, Mar 12, 2014 at 12:25:06PM +0100, Laurent Pinchart wrote: > > >> Hi Sagar, > > >> > > >> On Wednesday 12 March 2014 16:46:05 Sagar Arun Kamble wrote: > > >> > On Mon, 2014-03-10 at 15:36 +0100, Laurent Pinchart wrote: > > >> > > On Monday 10 March 2014 06:21:49 Daniel Vetter wrote: > > >> > > > On Wed, Mar 5, 2014 at 11:56 AM, w= rote: > > >> > > > > + > > >> > > > > + > > >> > > > > + > > >> > > > > + > > >> > > > > + > > >> > > > > + > > >> > > > > + > > >> > > > > + > > >> > > > > + > > >> > > > > + > > >> > > > > + > > >> > > > > + > > >> > > > > > >> > > > In my opinion this is a horrible way to write property documen= tations > > >> > > > - explicitly constructing html tables is error prone and reall= y hard > > >> > > > to read in the source. Imo docbook in general is rather horrib= le, > > >> > > > which is way I write almost all my docs as kerneldoc ;-) > > >> > > > > > >> > > > I think a simple asciidoc/markdown would be much simpler, with= a bit > > >> > > > of free-form structure to group properties into relevant group= s. > > >> > > > Long-term we might even need to split it up into different spe= c files > > >> > > > to keep a good overview. > > >> > > > > >> > > Docbook is indeed hard to read and write when it comes to such t= ables. > > >> > > However I like having the properties documented in the DRM core > > >> > > documentation. Maybe we could come up with a simpler text format= that > > >> > > would be transformed into docbook when compiling the documentati= on ? > > >> > > > >> > Does this mean we need to create comment block with "Doc: drm > > >> > properties" style section in each driver where drm properties are > > >> > instantiated. And then in drm.tmpl collect all these using !P esca= pe > > >> > sequence? > > >> > How do create table out of these across all drivers? > > >> > > >> I don't have a strong preference here. Documenting properties in sou= rce code > > >> comments would be fine, so would an external central documentation f= ile in a > > >> non Docbook format. For the record I'm personally fine with using Do= cbook as > > >> in this patch :-) > > >> > > >> 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 propertie= s table > > >> from kerneldoc information extracted from comments is probably not p= ossible. > > > > > > Can comeone pick up the ball here and figure out what needs to be don= e? > > > > > > The reason why I want a central place for the documentation is to for= ce > > > people to collaborate outside their own sandbox when adding propertie= s. > > > 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 m= ore > > > 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 thoug= hts > > > on the subject? > > > > > > Either way I can tell you that I'm not very enthusiastic about review= ing > > > any property patches until some kind of decision about this is reache= d, > > > be it "docbook", "text", "plan c", or "fuck it, let the world burn!". > > = > > any of the first three options would be vastly superior to what we do n= ow > > = > > tbh, I'd suggest imposing a no-new-properties-without-docs rule even > > if we haven't finished bikeshedding about the docs format. That might > > motivate someone to hurry up and just pick one. > > = > > We can change the format, figure out some way to get it into docbook, > > etc, later.. it's not such a huge volume of words we have to type here > > that we can't reformat it later. > > = > > BR, > > -R > > = > > = > > > > > > -- > > > Ville Syrj=E4l=E4 > > > Intel OTC > > > _______________________________________________ > > > dri-devel mailing list > > > dri-devel@lists.freedesktop.org > > > http://lists.freedesktop.org/mailman/listinfo/dri-devel > = > = -- = Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch
Owner Module/DriversGroupProperty ObjectProperty NameTypeProperty ValuesObject attachedDescription