From mboxrd@z Thu Jan  1 00:00:00 1970
From: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Subject: Re: [PATCH 1/1] Documentation: drm: describing drm
	properties exposed by various drivers
Date: Wed, 12 Mar 2014 12:25:06 +0100
Message-ID: <3136468.2PAlK4Gq8k@avalon>
References: <1394016990-5218-1-git-send-email-sagar.a.kamble@intel.com>
	<2919182.UBDg5nOr7Z@avalon>
	<1394622965.18918.12.camel@sagar-desktop>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Return-path: <intel-gfx-bounces@lists.freedesktop.org>
Received: from perceval.ideasonboard.com (perceval.ideasonboard.com
	[95.142.166.194])
	by gabe.freedesktop.org (Postfix) with ESMTP id 5230FFAF11
	for <intel-gfx@lists.freedesktop.org>;
	Wed, 12 Mar 2014 04:23:30 -0700 (PDT)
In-Reply-To: <1394622965.18918.12.camel@sagar-desktop>
List-Unsubscribe: <http://lists.freedesktop.org/mailman/options/intel-gfx>,
	<mailto:intel-gfx-request@lists.freedesktop.org?subject=unsubscribe>
List-Archive: <http://lists.freedesktop.org/archives/intel-gfx>
List-Post: <mailto:intel-gfx@lists.freedesktop.org>
List-Help: <mailto:intel-gfx-request@lists.freedesktop.org?subject=help>
List-Subscribe: <http://lists.freedesktop.org/mailman/listinfo/intel-gfx>,
	<mailto:intel-gfx-request@lists.freedesktop.org?subject=subscribe>
Sender: intel-gfx-bounces@lists.freedesktop.org
Errors-To: intel-gfx-bounces@lists.freedesktop.org
To: Sagar Arun Kamble <sagar.a.kamble@intel.com>
Cc: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>, linux-doc@vger.kernel.org, Daniel Vetter <daniel.vetter@ffwll.ch>, intel-gfx <intel-gfx@lists.freedesktop.org>, Rob Landley <rob@landley.net>, David Herrmann <dh.herrmann@gmail.com>, Alex Deucher <alexander.deucher@amd.com>, Dave Airlie <airlied@redhat.com>
List-Id: intel-gfx@lists.freedesktop.org

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,  <sagar.a.kamble@intel.com> wrote:
> > > > +<table border="1" cellpadding="0" cellspacing="0" >
> > > > +<tbody>
> > > > +<tr style="font-weight: bold;" >
> > > > +<td valign="top" >Owner Module/Drivers</td>
> > > > +<td valign="top" >Group</td>
> > > > +<td valign="top" >Property Object</td>
> > > > +<td valign="top" >Property Name</td>
> > > > +<td valign="top" >Type</td>
> > > > +<td valign="top" >Property Values</td>
> > > > +<td valign="top" >Object attached</td>
> > > > +<td valign="top" >Description</td>
> > > > +</tr>
> > > 
> > > In my opinion this is a horrible way to write property documentations
> > > - explicitly constructing html tables is error prone and really hard
> > > to read in the source. Imo docbook in general is rather horrible,
> > > 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 groups.
> > > Long-term we might even need to split it up into different spec files
> > > to keep a good overview.
> > 
> > Docbook is indeed hard to read and write when it comes to such tables.
> > 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 documentation ?
> 
> 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 escape
> sequence?
> How do create table out of these across all drivers?

I don't have a strong preference here. Documenting properties in source code 
comments would be fine, so would an external central documentation file in a 
non Docbook format. For the record I'm personally fine with using Docbook 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 properties table 
from kerneldoc information extracted from comments is probably not possible.

-- 
Regards,

Laurent Pinchart