From mboxrd@z Thu Jan 1 00:00:00 1970 From: Daniel Vetter Subject: Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body Date: Tue, 4 Aug 2015 11:04:13 +0200 Message-ID: <20150804090412.GG24689@phenom.ffwll.local> References: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: Received: from mail-wi0-f170.google.com (mail-wi0-f170.google.com [209.85.212.170]) by gabe.freedesktop.org (Postfix) with ESMTPS id 6D4ED6E74A for ; Tue, 4 Aug 2015 02:04:17 -0700 (PDT) Received: by wicmv11 with SMTP id mv11so167003281wic.0 for ; Tue, 04 Aug 2015 02:04:16 -0700 (PDT) Content-Disposition: inline In-Reply-To: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Danilo Cesar Lemes de Paula Cc: Michal Marek , Herbert Xu , Jonathan Corbet , Stephan Mueller , Daniel Vetter , intel-gfx , Randy Dunlap , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, dri-devel , Laurent Pinchart List-Id: dri-devel@lists.freedesktop.org T24gRnJpLCBKdWwgMzEsIDIwMTUgYXQgMDY6MDY6NDVQTSAtMDMwMCwgRGFuaWxvIENlc2FyIExl bWVzIGRlIFBhdWxhIHdyb3RlOgo+IERlc2NyaWJpbmcgYXJndW1lbnRzIGF0IHRvcCBvZiBhIHN0 cnVjdCBkZWZpbml0aW9uIHdvcmtzIGZpbmUKPiBmb3Igc21hbGwvbWVkaXVtIHNpemUgc3RydWN0 cywgYnV0IGl0IGRlZmluaXRlbHkgZG9lc24ndCB3b3JrIHdlbGwKPiBmb3Igc3RydWN0IHdpdGgg YSBodWdlIGxpc3Qgb2YgZWxlbWVudHMuCj4gCj4gS2VlcGluZyB0aGUgYXJndW1lbnRzIGxpc3Qg aW5zaWRlIHRoZSBzdHJ1Y3QgYm9keSBtYWtlcyBpdCBlYXNpZXIKPiB0byBtYWludGFpbiB0aGUg ZG9jdW1lbnRhdGlvbi4KPiBpZToKPiAvKioKPiAgKiBzdHJ1Y3QgbXlfc3RydWN0IC0gc2hvcnQg ZGVzY3JpcHRpb24KPiAgKiBAYTogZmlyc3QgbWVtYmVyCj4gICogQGI6IHNlY29uZCBtZW1iZXIK PiAgKgo+ICAqIExvbmdlciBkZXNjcmlwdGlvbgo+ICAqLwo+IHN0cnVjdCBteV9zdHJ1Y3Qgewo+ ICAgICBpbnQgYTsKPiAgICAgaW50IGI7Cj4gICAgIC8qKgo+ICAgICAgKiBAYzogVGhpcyBpcyBs b25nZXIgZGVzY3JpcHRpb24gb2YgQwo+ICAgICAgKgo+ICAgICAgKiBZb3UgY2FuIHVzZSBwYXJh Z3JhcGhzIHRvIGRlc2NyaWJlIGFyZ3VtZW50cwo+ICAgICAgKiB1c2luZyB0aGlzIG1ldGhvZC4K PiAgICAgICovCj4gICAgIGludCBjOwo+IH07Cj4gCj4gVGhpcyBwYXRjaCBhbGxvd3MgdGhlIHVz ZSBvZiB0aGlzIGtpbmQgb2Ygc3ludGF4LiBPbmx5IG9uZSBhcmd1bWVudAo+IHBlciBjb21tZW50 IGFuZCB1c2VyIGNhbiB1c2UgaG93IG1hbnkgcGFyYWdyYXBocyBoZSBuZWVkcy4gSXQgc2hvdWxk Cj4gc3RhcnQgd2l0aCAvKiosIHdoaWNoIGlzIGFscmVhZHkgYmVpbmcgdXNlZCBieSBrZXJuZWwt ZG9jLiBJZiB0aG9zZQo+IGNvbW1lbnQgZG9lc24ndCBmb2xsb3cgdGhvc2UgcnVsZXMsIGl0IHdp bGwgYmUgaWdub3JlZC4KPiAKPiBTaWduZWQtb2ZmLWJ5OiBEYW5pbG8gQ2VzYXIgTGVtZXMgZGUg UGF1bGEgPGRhbmlsby5jZXNhckBjb2xsYWJvcmEuY28udWs+Cj4gQ2M6IFJhbmR5IER1bmxhcCA8 cmR1bmxhcEBpbmZyYWRlYWQub3JnPgo+IENjOiBEYW5pZWwgVmV0dGVyIDxkYW5pZWwudmV0dGVy QGZmd2xsLmNoPgo+IENjOiBMYXVyZW50IFBpbmNoYXJ0IDxsYXVyZW50LnBpbmNoYXJ0QGlkZWFz b25ib2FyZC5jb20+Cj4gQ2M6IEpvbmF0aGFuIENvcmJldCA8Y29yYmV0QGx3bi5uZXQ+Cj4gQ2M6 IEhlcmJlcnQgWHUgPGhlcmJlcnRAZ29uZG9yLmFwYW5hLm9yZy5hdT4KPiBDYzogU3RlcGhhbiBN dWVsbGVyIDxzbXVlbGxlckBjaHJvbm94LmRlPgo+IENjOiBNaWNoYWwgTWFyZWsgPG1tYXJla0Bz dXNlLmN6Pgo+IENjOiBsaW51eC1rZXJuZWxAdmdlci5rZXJuZWwub3JnCj4gQ2M6IGxpbnV4LWRv Y0B2Z2VyLmtlcm5lbC5vcmcKPiBDYzogaW50ZWwtZ2Z4IDxpbnRlbC1nZnhAbGlzdHMuZnJlZWRl c2t0b3Aub3JnPgo+IENjOiBkcmktZGV2ZWwgPGRyaS1kZXZlbEBsaXN0cy5mcmVlZGVza3RvcC5v cmc+Cj4gLS0tCj4gIHNjcmlwdHMva2VybmVsLWRvYyB8IDgwICsrKysrKysrKysrKysrKysrKysr KysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKystLQo+ICAxIGZpbGUgY2hhbmdlZCwgNzgg aW5zZXJ0aW9ucygrKSwgMiBkZWxldGlvbnMoLSkKPiAKPiBkaWZmIC0tZ2l0IGEvc2NyaXB0cy9r ZXJuZWwtZG9jIGIvc2NyaXB0cy9rZXJuZWwtZG9jCj4gaW5kZXggOTkyMmU2Ni4uOWJmYThiOSAx MDA3NTUKPiAtLS0gYS9zY3JpcHRzL2tlcm5lbC1kb2MKPiArKysgYi9zY3JpcHRzL2tlcm5lbC1k b2MKPiBAQCAtMTMzLDYgKzEzMywzMCBAQCB1c2Ugc3RyaWN0Owo+ICAjCj4gICMgQWxsIGRlc2Ny aXB0aW9ucyBjYW4gYmUgbXVsdGlsaW5lLCBleGNlcHQgdGhlIHNob3J0IGZ1bmN0aW9uIGRlc2Ny aXB0aW9uLgo+ICAjCj4gKyMgRm9yIHJlYWxseSBsb25ncyBzdHJ1Y3RzLCB5b3UgY2FuIGFsc28g ZGVzY3JpYmUgYXJndW1lbnRzIGluc2lkZSB0aGUKPiArIyBib2R5IG9mIHRoZSBzdHJ1Y3QuCj4g KyMgZWcuCj4gKyMgLyoqCj4gKyMgICogc3RydWN0IG15X3N0cnVjdCAtIHNob3J0IGRlc2NyaXB0 aW9uCj4gKyMgICogQGE6IGZpcnN0IG1lbWJlcgo+ICsjICAqIEBiOiBzZWNvbmQgbWVtYmVyCj4g KyMgICoKPiArIyAgKiBMb25nZXIgZGVzY3JpcHRpb24KPiArIyAgKi8KPiArIyBzdHJ1Y3QgbXlf c3RydWN0IHsKPiArIyAgICAgaW50IGE7Cj4gKyMgICAgIGludCBiOwo+ICsjICAgICAvKioKPiAr IyAgICAgICogQGM6IFRoaXMgaXMgbG9uZ2VyIGRlc2NyaXB0aW9uIG9mIEMKPiArIyAgICAgICoK PiArIyAgICAgICogWW91IGNhbiB1c2UgcGFyYWdyYXBocyB0byBkZXNjcmliZSBhcmd1bWVudHMK PiArIyAgICAgICogdXNpbmcgdGhpcyBtZXRob2QuCj4gKyMgICAgICAqLwo+ICsjICAgICBpbnQg YzsKPiArIyB9Owo+ICsjCj4gKyMgVGhpcyBzaG91bGQgYmUgdXNlIGZvciBhcmd1bWVudHMgb25s eS4KPiArIwo+ICAjIFlvdSBjYW4gYWxzbyBhZGQgYWRkaXRpb25hbCBzZWN0aW9ucy4gV2hlbiBk b2N1bWVudGluZyBrZXJuZWwgZnVuY3Rpb25zIHlvdQo+ICAjIHNob3VsZCBkb2N1bWVudCB0aGUg IkNvbnRleHQ6IiBvZiB0aGUgZnVuY3Rpb24sIGUuZy4gd2hldGhlciB0aGUgZnVuY3Rpb25zCj4g ICMgY2FuIGJlIGNhbGxlZCBmb3JtIGludGVycnVwdHMuIFVubGlrZSBvdGhlciBzZWN0aW9ucyB5 b3UgY2FuIGVuZCBpdCB3aXRoIGFuCj4gQEAgLTI4Nyw5ICszMTEsMTkgQEAgbXkgJGxpbmVwcmVm aXg9IiI7Cj4gICMgMiAtIHNjYW5uaW5nIGZpZWxkIHN0YXJ0Lgo+ICAjIDMgLSBzY2FubmluZyBw cm90b3R5cGUuCj4gICMgNCAtIGRvY3VtZW50YXRpb24gYmxvY2sKPiArIyA1IC0gZ2F0aGVyaW5n IGRvY3VtZW50YXRpb24gb3V0c2lkZSBtYWluIGJsb2NrCj4gIG15ICRzdGF0ZTsKPiAgbXkgJGlu X2RvY19zZWN0Owo+ICAKPiArIyBTcGxpdCBEb2MgU3RhdGUKPiArIyAwIC0gSW52YWxpZCAoQmVm b3JlIHN0YXJ0IG9yIGFmdGVyIGZpbmlzaCkKPiArIyAxIC0gSXMgc3RhcnRlZCAodGhlIC8qKiB3 YXMgZm91bmQgaW5zaWRlIGEgc3RydWN0KQo+ICsjIDIgLSBUaGUgQHBhcmFtZXRlciBoZWFkZXIg d2FzIGZvdW5kLCBzdGFydCBhY2NlcHRpbmcgbXVsdGkgcGFyYWdyYXBoIHRleHQuCj4gKyMgMyAt IEZpbmlzaGVkICh0aGUgKi8gd2FzIGZvdW5kKQo+ICsjIDQgLSBFcnJvciAtIENvbW1lbnQgd2l0 aG91dCBoZWFkZXIgd2FzIGZvdW5kLiBTcGl0IGEgd2FybmluZyBhcyBpdCdzIG5vdAo+ICsjICAg ICBwcm9wZXIga2VybmVsLWRvYyBhbmQgaWdub3JlIHRoZSByZXN0Lgo+ICtteSAkc3BsaXRfZG9j X3N0YXRlOwo+ICsKPiAgI2RlY2xhcmF0aW9uIHR5cGVzOiBjYW4gYmUKPiAgIyAnZnVuY3Rpb24n LCAnc3RydWN0JywgJ3VuaW9uJywgJ2VudW0nLCAndHlwZWRlZicKPiAgbXkgJGRlY2xfdHlwZTsK PiBAQCAtMzA0LDYgKzMzOCw5IEBAIG15ICRkb2NfZGVjbCA9ICRkb2NfY29tIC4gJyhcdyspJzsK PiAgbXkgJGRvY19zZWN0ID0gJGRvY19jb20gLiAnKFsnIC4gJGRvY19zcGVjaWFsIC4gJ10/W1x3 XHNdKyk6KC4qKSc7Cj4gIG15ICRkb2NfY29udGVudCA9ICRkb2NfY29tX2JvZHkgLiAnKC4qKSc7 Cj4gIG15ICRkb2NfYmxvY2sgPSAkZG9jX2NvbSAuICdET0M6XHMqKC4qKT8nOwo+ICtteSAkZG9j X3NwbGl0X3N0YXJ0ID0gJ15ccyovXCpcKlxzKiQnOwo+ICtteSAkZG9jX3NwbGl0X3NlY3QgPSAn XHMqXCpccyooQFtcd1xzXSspOiguKiknOwo+ICtteSAkZG9jX3NwbGl0X2VuZCA9ICdeXHMqXCov XHMqJCc7Cj4gIAo+ICBteSAlY29uc3RhbnRzOwo+ICBteSAlcGFyYW1ldGVyZGVzY3M7Cj4gQEAg LTIxODEsNiArMjIxOCw3IEBAIHN1YiByZXNldF9zdGF0ZSB7Cj4gICAgICAkcHJvdG90eXBlID0g IiI7Cj4gIAo+ICAgICAgJHN0YXRlID0gMDsKPiArICAgICRzcGxpdF9kb2Nfc3RhdGUgPSAwOwo+ ICB9Cj4gIAo+ICBzdWIgdHJhY2Vwb2ludF9tdW5nZSgkKSB7Cj4gQEAgLTI0NTMsNyArMjQ5MSw2 IEBAIHN1YiBwcm9jZXNzX2ZpbGUoJCkgewo+ICAJCX0KPiAgCQkkc2VjdGlvbiA9ICRuZXdzZWN0 aW9uOwo+ICAJICAgIH0gZWxzaWYgKC8kZG9jX2VuZC8pIHsKPiAtCj4gIAkJaWYgKCgkY29udGVu dHMgbmUgIiIpICYmICgkY29udGVudHMgbmUgIlxuIikpIHsKPiAgCQkgICAgZHVtcF9zZWN0aW9u KCRmaWxlLCAkc2VjdGlvbiwgeG1sX2VzY2FwZSgkY29udGVudHMpKTsKPiAgCQkgICAgJHNlY3Rp b24gPSAkc2VjdGlvbl9kZWZhdWx0Owo+IEBAIC0yNDk0LDggKzI1MzEsNDcgQEAgc3ViIHByb2Nl c3NfZmlsZSgkKSB7Cj4gIAkJcHJpbnQgU1RERVJSICJXYXJuaW5nKCR7ZmlsZX06JC4pOiBiYWQg bGluZTogJF8iOwo+ICAJCSsrJHdhcm5pbmdzOwo+ICAJICAgIH0KPiArCX0gZWxzaWYgKCRzdGF0 ZSA9PSA1KSB7ICMgc2Nhbm5pbmcgZm9yIHNwbGl0IHBhcmFtZXRlcnMKPiArCj4gKwkgICAgIyBG aXJzdCBsaW5lIChzdGF0ZSAxKSBuZWVkcyB0byBiZSBhIEBwYXJhbWV0ZXIKPiArCSAgICBpZiAo JHNwbGl0X2RvY19zdGF0ZSA9PSAxICYmIC8kZG9jX3NwbGl0X3NlY3Qvbykgewo+ICsJICAgICAg ICAkc2VjdGlvbiA9ICQxOwo+ICsJICAgICAgICAkY29udGVudHMgPSAkMjsKCllvdSdyZSB1c2lu ZyBhIG1peCBvZiB0YWJzIGFuZCBzcGFjZXMgaGVyZSB0byBpbmRlbnQuIE9mYyB3ZSBuZWVkIDQg c3BhY2VzCmZvciBvZGQgaW5kZW50IGxldmVscywgYnV0IGZvciBvdGhlcnMgaXQgc2hvdWxkbid0 IGJlIHJlcXVpcmVkLgotRGFuaWVsCgo+ICsJICAgICAgICBpZiAoJGNvbnRlbnRzIG5lICIiKSB7 Cj4gKwkgICAgCSAgICB3aGlsZSAoKHN1YnN0cigkY29udGVudHMsIDAsIDEpIGVxICIgIikgfHwK PiArCSAgICAgICAgICAgICAgICAgICAgc3Vic3RyKCRjb250ZW50cywgMCwgMSkgZXEgIlx0Iikg ewo+ICsJICAgIAkgICAgICAgICRjb250ZW50cyA9IHN1YnN0cigkY29udGVudHMsIDEpOwo+ICsJ ICAgICAgICAgICAgfQo+ICsJICAgICAgICAgICAgJGNvbnRlbnRzIC49ICJcbiI7Cj4gKwkgICAg ICAgIH0KPiArCSAgICAgICAgJHNwbGl0X2RvY19zdGF0ZSA9IDI7Cj4gKwo+ICsJICAgICMgRW5k IGNvbW1lbmQgKi8KPiArCSAgICB9IGVsc2lmICgvJGRvY19zcGxpdF9lbmQvKSB7Cj4gKwkgICAg ICAgIGlmICgoJGNvbnRlbnRzIG5lICIiKSAmJiAoJGNvbnRlbnRzIG5lICJcbiIpKSB7Cj4gKwkg ICAgICAgICAgICBkdW1wX3NlY3Rpb24oJGZpbGUsICRzZWN0aW9uLCB4bWxfZXNjYXBlKCRjb250 ZW50cykpOwo+ICsJICAgICAgICAgICAgJHNlY3Rpb24gPSAkc2VjdGlvbl9kZWZhdWx0Owo+ICsJ ICAgICAgICAgICAgJGNvbnRlbnRzID0gIiI7Cj4gKwkgICAgICAgIH0KPiArCSAgICAgICAgJHN0 YXRlID0gMzsKPiArCSAgICAgICAgJHNwbGl0X2RvY19zdGF0ZSA9IDA7Cj4gKwo+ICsJICAgICMg UmVndWxhciB0ZXh0Cj4gKwkgICAgfSBlbHNpZiAoLyRkb2NfY29udGVudC8pIHsKPiArCSAgICAJ aWYgKCRzcGxpdF9kb2Nfc3RhdGUgPT0gMikgewo+ICsJICAgIAkgICAgJGNvbnRlbnRzIC49ICQx IC4gIlxuIjsKPiArCSAgICAJfSBlbHNpZiAoJHNwbGl0X2RvY19zdGF0ZSA9PSAxKSB7Cj4gKwkg ICAgCSAgICAkc3BsaXRfZG9jX3N0YXRlID0gNDsKPiArCSAgICAJICAgIHByaW50IFNUREVSUiAi V2FybmluZygke2ZpbGV9OiQuKTogIjsKPiArCSAgICAJICAgIHByaW50IFNUREVSUiAiSW5jb3Jy ZWN0IHVzZSBvZiBrZXJuZWwtZG9jIGZvcm1hdDogJF8iOwo+ICsJICAgIAkgICAgKyskd2Fybmlu Z3M7Cj4gKwkgICAgCX0KPiArCSAgICB9Cj4gIAl9IGVsc2lmICgkc3RhdGUgPT0gMykgewkjIHNj YW5uaW5nIGZvciBmdW5jdGlvbiAneycgKGVuZCBvZiBwcm90b3R5cGUpCj4gLQkgICAgaWYgKCRk ZWNsX3R5cGUgZXEgJ2Z1bmN0aW9uJykgewo+ICsJICAgIGlmICgvJGRvY19zcGxpdF9zdGFydC8p IHsKPiArCSAgICAJICAgICRzdGF0ZSA9IDU7Cj4gKwkgICAgCSAgICAkc3BsaXRfZG9jX3N0YXRl ID0gMTsKPiArCSAgICB9IGVsc2lmICgkZGVjbF90eXBlIGVxICdmdW5jdGlvbicpIHsKPiAgCQlw cm9jZXNzX3N0YXRlM19mdW5jdGlvbigkXywgJGZpbGUpOwo+ICAJICAgIH0gZWxzZSB7Cj4gIAkJ cHJvY2Vzc19zdGF0ZTNfdHlwZSgkXywgJGZpbGUpOwo+IC0tIAo+IDIuNC42Cj4gCgotLSAKRGFu aWVsIFZldHRlcgpTb2Z0d2FyZSBFbmdpbmVlciwgSW50ZWwgQ29ycG9yYXRpb24KaHR0cDovL2Js b2cuZmZ3bGwuY2gKX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19f X18KZHJpLWRldmVsIG1haWxpbmcgbGlzdApkcmktZGV2ZWxAbGlzdHMuZnJlZWRlc2t0b3Aub3Jn Cmh0dHA6Ly9saXN0cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9kcmktZGV2ZWwK From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755641AbbHDJEW (ORCPT ); Tue, 4 Aug 2015 05:04:22 -0400 Received: from mail-wi0-f179.google.com ([209.85.212.179]:35681 "EHLO mail-wi0-f179.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755551AbbHDJER (ORCPT ); Tue, 4 Aug 2015 05:04:17 -0400 Date: Tue, 4 Aug 2015 11:04:13 +0200 From: Daniel Vetter To: Danilo Cesar Lemes de Paula Cc: linux-doc@vger.kernel.org, Randy Dunlap , Daniel Vetter , Laurent Pinchart , Jonathan Corbet , 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: <20150804090412.GG24689@phenom.ffwll.local> Mail-Followup-To: Danilo Cesar Lemes de Paula , linux-doc@vger.kernel.org, Randy Dunlap , Laurent Pinchart , Jonathan Corbet , Herbert Xu , Stephan Mueller , Michal Marek , linux-kernel@vger.kernel.org, intel-gfx , dri-devel References: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> X-Operating-System: Linux phenom 4.2.0-rc1+ User-Agent: Mutt/1.5.23 (2014-03-12) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Fri, Jul 31, 2015 at 06:06:45PM -0300, Danilo Cesar Lemes de Paula wrote: > Describing arguments at top of a struct definition works fine > for small/medium size structs, but it definitely doesn't work well > for struct with a huge list of elements. > > Keeping the arguments list inside the struct body makes it easier > to maintain the documentation. > ie: > /** > * struct my_struct - short description > * @a: first member > * @b: second member > * > * Longer description > */ > struct my_struct { > int a; > int b; > /** > * @c: This is longer description of C > * > * You can use paragraphs to describe arguments > * using this method. > */ > int c; > }; > > This patch allows the use of this kind of syntax. Only one argument > per comment and user can use how many paragraphs he needs. It should > start with /**, which is already being used by kernel-doc. If those > comment doesn't follow those rules, it will be ignored. > > Signed-off-by: Danilo Cesar Lemes de Paula > Cc: Randy Dunlap > Cc: Daniel Vetter > Cc: Laurent Pinchart > Cc: Jonathan Corbet > Cc: Herbert Xu > Cc: Stephan Mueller > Cc: Michal Marek > Cc: linux-kernel@vger.kernel.org > Cc: linux-doc@vger.kernel.org > Cc: intel-gfx > Cc: dri-devel > --- > scripts/kernel-doc | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- > 1 file changed, 78 insertions(+), 2 deletions(-) > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index 9922e66..9bfa8b9 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -133,6 +133,30 @@ use strict; > # > # All descriptions can be multiline, except the short function description. > # > +# For really longs structs, you can also describe arguments inside the > +# body of the struct. > +# eg. > +# /** > +# * struct my_struct - short description > +# * @a: first member > +# * @b: second member > +# * > +# * Longer description > +# */ > +# struct my_struct { > +# int a; > +# int b; > +# /** > +# * @c: This is longer description of C > +# * > +# * You can use paragraphs to describe arguments > +# * using this method. > +# */ > +# int c; > +# }; > +# > +# This should be use for arguments only. > +# > # You can also add additional sections. When documenting kernel functions you > # should document the "Context:" of the function, e.g. whether the functions > # can be called form interrupts. Unlike other sections you can end it with an > @@ -287,9 +311,19 @@ my $lineprefix=""; > # 2 - scanning field start. > # 3 - scanning prototype. > # 4 - documentation block > +# 5 - gathering documentation outside main block > my $state; > my $in_doc_sect; > > +# Split Doc State > +# 0 - Invalid (Before start or after finish) > +# 1 - Is started (the /** was found inside a struct) > +# 2 - The @parameter header was found, start accepting multi paragraph text. > +# 3 - Finished (the */ was found) > +# 4 - Error - Comment without header was found. Spit a warning as it's not > +# proper kernel-doc and ignore the rest. > +my $split_doc_state; > + > #declaration types: can be > # 'function', 'struct', 'union', 'enum', 'typedef' > my $decl_type; > @@ -304,6 +338,9 @@ my $doc_decl = $doc_com . '(\w+)'; > my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)'; > my $doc_content = $doc_com_body . '(.*)'; > my $doc_block = $doc_com . 'DOC:\s*(.*)?'; > +my $doc_split_start = '^\s*/\*\*\s*$'; > +my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)'; > +my $doc_split_end = '^\s*\*/\s*$'; > > my %constants; > my %parameterdescs; > @@ -2181,6 +2218,7 @@ sub reset_state { > $prototype = ""; > > $state = 0; > + $split_doc_state = 0; > } > > sub tracepoint_munge($) { > @@ -2453,7 +2491,6 @@ sub process_file($) { > } > $section = $newsection; > } elsif (/$doc_end/) { > - > if (($contents ne "") && ($contents ne "\n")) { > dump_section($file, $section, xml_escape($contents)); > $section = $section_default; > @@ -2494,8 +2531,47 @@ sub process_file($) { > print STDERR "Warning(${file}:$.): bad line: $_"; > ++$warnings; > } > + } elsif ($state == 5) { # scanning for split parameters > + > + # First line (state 1) needs to be a @parameter > + if ($split_doc_state == 1 && /$doc_split_sect/o) { > + $section = $1; > + $contents = $2; You're using a mix of tabs and spaces here to indent. Ofc we need 4 spaces for odd indent levels, but for others it shouldn't be required. -Daniel > + if ($contents ne "") { > + while ((substr($contents, 0, 1) eq " ") || > + substr($contents, 0, 1) eq "\t") { > + $contents = substr($contents, 1); > + } > + $contents .= "\n"; > + } > + $split_doc_state = 2; > + > + # End commend */ > + } elsif (/$doc_split_end/) { > + if (($contents ne "") && ($contents ne "\n")) { > + dump_section($file, $section, xml_escape($contents)); > + $section = $section_default; > + $contents = ""; > + } > + $state = 3; > + $split_doc_state = 0; > + > + # Regular text > + } elsif (/$doc_content/) { > + if ($split_doc_state == 2) { > + $contents .= $1 . "\n"; > + } elsif ($split_doc_state == 1) { > + $split_doc_state = 4; > + print STDERR "Warning(${file}:$.): "; > + print STDERR "Incorrect use of kernel-doc format: $_"; > + ++$warnings; > + } > + } > } elsif ($state == 3) { # scanning for function '{' (end of prototype) > - if ($decl_type eq 'function') { > + if (/$doc_split_start/) { > + $state = 5; > + $split_doc_state = 1; > + } elsif ($decl_type eq 'function') { > process_state3_function($_, $file); > } else { > process_state3_type($_, $file); > -- > 2.4.6 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch