From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jonathan Corbet Subject: Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body Date: Mon, 3 Aug 2015 08:37:41 -0600 Message-ID: <20150803083741.04bfb6ed@lwn.net> References: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> <20150801132210.2c0b84f1@lwn.net> <20150803082319.GB24689@phenom.ffwll.local> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: In-Reply-To: <20150803082319.GB24689@phenom.ffwll.local> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Daniel Vetter Cc: Michal Marek , Herbert Xu , Danilo Cesar Lemes de Paula , linux-doc@vger.kernel.org, Stephan Mueller , Daniel Vetter , intel-gfx , Randy Dunlap , linux-kernel@vger.kernel.org, dri-devel , Laurent Pinchart List-Id: dri-devel@lists.freedesktop.org T24gTW9uLCAzIEF1ZyAyMDE1IDEwOjIzOjE5ICswMjAwCkRhbmllbCBWZXR0ZXIgPGRhbmllbEBm ZndsbC5jaD4gd3JvdGU6Cgo+ID4gSSdtIHdvbmRlcmluZyBpZiB3ZSBuZWVkIGEga2VybmVsIHN1 bW1pdCBzZXNzaW9uIG9uIGNvbW1lbnRpbmcKPiA+IGNvbnZlbnRpb25zLCBtYXJrZG93bi1pbi1r ZXJuZWxkb2MsIGV0Yz8gIE1heWJlIEknbGwgc3RpY2sgYSBwcm9wb3NhbCBvdXQKPiA+IHRoZXJl LiAgCj4gCj4gTWlnaHQgYmUgdXNlZnVsLCBidXQgSSdtIG5vdCBzdXJlIGhvdyBtYW55IHBlb3Bs ZSByZWFsbHkgd291bGQgYWN0aXZlbHkKPiB3b3JrIG9uIGltcHJvdmluZyB0aGUgdG9vbGluZy4g VGhlIG9ubHkgY29tbWVudCBJJ3ZlIHNlZW4gaXMgdG8gbWF5YmUgdXNlCj4gZ3RrZG9jLCBidXQg dGhhdCB3b3VsZCBiZSBhIHBhaW4gc2luY2UgaXQncyBzbGlnaHRseSBpbmNvbXBhdGlibGUgd2l0 aAo+IGtlcm5lbGRvYy4KClRoZSBpZGVhIHdhcyB0byBnZXQgYSBzZW5zZSBmb3Igd2hhdCBzb3J0 IG9mIGltcHJvdmVtZW50cyB3b3VsZCBiZQp1c2VmdWwsIHRvIGJlZ2luIHdpdGguICBCdXQgbXkg YXR0ZW1wdCB0byBzdGFydCBhIGRpc2N1c3Npb24gb24gdGhlCmtlcm5lbCBzdW1taXQgbGlzdCBh cHBlYXJzIHRvIGhhdmUgaGl0IHRoZSBncm91bmQgcHJldHR5IGhhcmQ7IEkgZ3Vlc3MKdGhhdCBt ZWFucyBJIGhhdmUgZnJlZSByZWluIDopCgpJIGV4cGVjdCBJJ2xsIGFwcGx5IHRoZSBzdHJ1Y3Qt YXJncyBkb2MgcGF0Y2ggaW4gdGhlIGZhaXJseSBuZWFyIGZ1dHVyZS4KVGhlbiB3ZSdsbCBzZWUg aWYgb3RoZXJzIGNvbXBsYWluIHdoZW4gcGF0Y2hlcyB1c2luZyBpdCBzdGFydCB0byBzaG93IHVw LApidXQgdGhlIGZlYXR1cmUgaXRzZWxmIHNob3VsZG4ndCBicmVhayBhbnl0aGluZy4gIEknbSAq cmVhbGx5KiBob3BpbmcgdG8KdGFrZSBhIGhhcmQgbG9vayBhdCBEYW5pbG8ncyBzdHVmZiBmb3Ig YSA0LjMgbWVyZ2UgYXMgd2VsbC4gIEl0IHNob3VsZCBiZQpwb3NzaWJsZSwgYnV0IHRoZXJlJ3Mg cmVhbC13b3JsZCBvYm5veGlvdXNuZXNzIHRoYXQgaXMgZG9pbmcgaXRzIGJlc3QgdG8KZ2V0IGlu IHRoZSB3YXkuCgpqb24KX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19f X19fX18KZHJpLWRldmVsIG1haWxpbmcgbGlzdApkcmktZGV2ZWxAbGlzdHMuZnJlZWRlc2t0b3Au b3JnCmh0dHA6Ly9saXN0cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9kcmktZGV2 ZWwK From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753852AbbHCOhs (ORCPT ); Mon, 3 Aug 2015 10:37:48 -0400 Received: from tex.lwn.net ([70.33.254.29]:46848 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753808AbbHCOho (ORCPT ); Mon, 3 Aug 2015 10:37:44 -0400 Date: Mon, 3 Aug 2015 08:37:41 -0600 From: Jonathan Corbet To: Daniel Vetter Cc: Danilo Cesar Lemes de Paula , linux-doc@vger.kernel.org, Randy Dunlap , Daniel Vetter , Laurent Pinchart , Herbert Xu , Stephan Mueller , Michal Marek , linux-kernel@vger.kernel.org, intel-gfx , dri-devel Subject: Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body Message-ID: <20150803083741.04bfb6ed@lwn.net> In-Reply-To: <20150803082319.GB24689@phenom.ffwll.local> References: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> <20150801132210.2c0b84f1@lwn.net> <20150803082319.GB24689@phenom.ffwll.local> Organization: LWN.net X-Mailer: Claws Mail 3.11.1 (GTK+ 2.24.28; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Mon, 3 Aug 2015 10:23:19 +0200 Daniel Vetter wrote: > > I'm wondering if we need a kernel summit session on commenting > > conventions, markdown-in-kerneldoc, etc? Maybe I'll stick a proposal out > > there. > > Might be useful, but I'm not sure how many people really would actively > work on improving the tooling. The only comment I've seen is to maybe use > gtkdoc, but that would be a pain since it's slightly incompatible with > kerneldoc. The idea was to get a sense for what sort of improvements would be useful, to begin with. But my attempt to start a discussion on the kernel summit list appears to have hit the ground pretty hard; I guess that means I have free rein :) I expect I'll apply the struct-args doc patch in the fairly near future. Then we'll see if others complain when patches using it start to show up, but the feature itself shouldn't break anything. I'm *really* hoping to take a hard look at Danilo's stuff for a 4.3 merge as well. It should be possible, but there's real-world obnoxiousness that is doing its best to get in the way. jon