From mboxrd@z Thu Jan 1 00:00:00 1970 From: Danilo Cesar Lemes de Paula Subject: Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements Date: Mon, 14 Sep 2015 09:11:00 -0300 Message-ID: <55F6B954.30506@collabora.co.uk> References: <1441656124-8997-1-git-send-email-danilo.cesar@collabora.co.uk> <20150912152449.1cdc1710@lwn.net> <20150913103607.GA3383@phenom.ffwll.local> <20150913131356.780426e9@lwn.net> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: In-Reply-To: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Daniel Vetter , Jonathan Corbet Cc: Johannes Berg , linux-doc@vger.kernel.org, intel-gfx , Linux Kernel Mailing List , dri-devel , Andrew Morton List-Id: dri-devel@lists.freedesktop.org T24gMDkvMTMvMjAxNSAwNTo1OCBQTSwgRGFuaWVsIFZldHRlciB3cm90ZToKPiBPbiBTdW4sIFNl cCAxMywgMjAxNSBhdCA5OjEzIFBNLCBKb25hdGhhbiBDb3JiZXQgPGNvcmJldEBsd24ubmV0PiB3 cm90ZToKPj4gT24gU3VuLCAxMyBTZXAgMjAxNSAxMjozNjowNyArMDIwMAo+PiBEYW5pZWwgVmV0 dGVyIDxkYW5pZWxAZmZ3bGwuY2g+IHdyb3RlOgo+Pgo+Pj4gUGVyc29uYWxseSBJIGRvbid0IGNh cmUgd2hpY2gga2luZCBvZiB0ZXh0IG1hcmt1cCB3ZSBwaWNrIGFuZCB3aWNoCj4+PiBjb252ZXJ0 ZXIsIGFzIGxvbmcgYXMgdGhlIHByb2plY3QgbG9va3MgcmVhc29uYWJsZSBmYXIgYXdheSBmcm9t Cj4+PiBpbW1lbmluZW50IGRlYXRoICh3YXkgdG9vIG1hbnkgb25lLXBlcnNvbiBwcm9qZWN0cyBv biBnaXRodWIgaW4gdGhpcwo+Pj4gYXJlYSkuCgpJIHdvdWxkbid0IGNhcmUgZWl0aGVyLiBJIGNo b29zZSBwYW5kb2MgYXMgaXQncyBvbGQsIGtpbmQgb2Ygc3RhYmxlIGFuZApoYXMgYSBkZWNlbnQg Y29tbXVuaXR5IGFyb3VuZCBpdCwgc28gaXQgd29uJ3QgcHJvYmFibHkgZGllIGR1ZSB0aGUgbGFj awpvZiBpbnRlcmVzdGVkIGRldmVsb3BlcnMuCgpUaGF0IHNhaWQsIGNtYXJrIGlzIG5vdCBhIG9w dGlvbiAoYXQgbGVhc3QgZm9yIG5vdykuIFdpdGggdGhlIGN1cnJlbnQKYXBwcm9hY2ggd2UgbmVl ZCBhIHRvb2wgY2FwYWJsZSBvZiByZWFkaW5nIG1hcmtkb3duIHRleHQgYW5kIG91dHB1dApEb2NC b29rIHRhZ3MsIGFzIHdlJ3JlIGFjdHVhbGx5IHN0aWxsIHVzaW5nIGRvY2Jvb2sgdG8gc3BpdCBh bGwga2luZHMgb2YKRG9jdW1lbnRhdGlvbiBmb3JtYXRzIChodG1sLCBtYW4sIHBkZikuIExvb2tz IGxpa2UgY21hcmsgY2FuIG9ubHkgZG8KbWFya2Rvd24tPmh0bWwuCgpJIGRpZCBsb29rIGludG8g b3RoZXIgb3B0aW9ucyB0aG91Z2gsIGJ1dCB0aGV5IHdlcmUgYWxsIG1vc3RseSBvbmUtbWFuCmpv Yi4gQnV0IHllYWgsIGJhc2ljYWxseSBhbnkgdG9vbCBjYXBhYmxlIG9mIGNvbnZlcnRpbmcKbWFy a2Rvd24tPmRvY2Jvb2sgd2lsbCB3b3JrLiBJJ20gYWx3YXlzIGxpc3RlbmluZyB0byBzdWdnZXN0 aW9ucyA9KQoKCj4+Pgo+Pj4gQnV0IGlmIHdlIGhhdmUgdGhpcyBkaXNjdXNzaW9uIEknZCBsaWtl IHRvIGRlY291cGxlIGl0IGZyb20gdGhlIG90aGVyCj4+PiBrZXJuZWxkb2MgaW1wcm92ZW1udHMg aW4gdGhpcyBzZXJpZXMgKHBhdGNoZXMgMSwgNSBhbmQgNikuIElmIHdlIGNhbnQKPj4+IGFncmVl IG9uIHRoZSB0ZXh0IG1hcmt1cCB0aGVuIGRybSBkb2NzIHdpbGwgc2ltcGx5IGxvb2sgYSBiaXQg ZnVubnkgZm9yCj4+PiBldmVyeW9uZSBlbHNlLiBCdXQgaWYgdGhlIGlubGluZSBzdHJ1Y3Qgc3R1 ZmYgd29uJ3QgaGFwcGVuIDAtZGF5IHdpbGwKPj4+IHNjcmVhbSBhcm91bmQgKGFuZCB0aGVyZSdz IGFscmVhZHkgcGF0Y2hlcyB3aGljaCB1c2UgdGhlIG5ldyBsYXlvdXQpLgo+Pgo+PiBUaG9zZSBw YXRjaGVzIGFyZToKPj4KPj4gMSkgIHNjcmlwdHMva2VybmVsLWRvYzogUmVwbGFjaW5nIGhpZ2hs aWdodHMgaGFzaCBieSBhbiBhcnJheQo+PiA1KSAgc2NyaXB0cy9rZXJuZWwtZG9jOiBJbXByb3Zl IE1hcmtkb3duIHJlc3VsdHMKPj4gNikgIHNjcmlwdHMva2VybmVsLWRvYzogUHJvY2Vzc2luZyAt bm9mdW5jIGZvciBmdW5jdGlvbnMgb25seQo+Pgo+PiAjMSBpcyBmaW5lLCBJJ2xsIG1lcmdlIHRo YXQgdG9kYXkuICAjNiBpcyBhbHJlYWR5IG1lcmdlZC4gICM1IGlzIGEgbWFya2Rvd24KPj4gcGF0 Y2gsIHRob3VnaCwgYW5kIGRvZXNuJ3QgbWFrZSBzZW5zZSB3aXRob3V0IHRoZSBvdGhlcnM/ICBB cmUgeW91IHRoaW5raW5nCj4+IGFib3V0ICMzIChkcm0vZG9jOiBDb252ZXJ0IHRvIG1hcmtkb3du KT8gIFRoYXQgb25lIHdvdWxkIGFsbW9zdCB3b3JrIChpdAo+PiBkZXBlbmRzIG9uICMyIGN1cnJl bnRseSkgYW5kIGl0IG5pY2VseSBzaG93cyAqd2h5KiBJJ2QgbGlrZSB0byBnZXQgYXdheSBmcm9t Cj4+IFhNTC4uLgoKIzUgaXMgdGhlIERSTSBtYXJrZG93biBjb252ZXJzaW9uLCB3aGljaCBkZXBl bmRzIG9uICMyIGFuZCAjNC4gU28gaWYgYQpkZWNpc2lvbiBhYm91dCB0aGlzIGlzIGdvaW5nIGR1 cmluZyBLUywgd2UgbmVlZCB0byBob2xkIHRob3NlIHRocmVlIHBhdGNoZXMuCgo+IAo+IFNvcnJ5 IEkgbWl4ZWQgdGhpbmdzIHVwLCAjNSBpcyBvayB0byBsZWF2ZSBvdXQuIEkgdGhvdWdodCBhYm91 dAo+ICJzY3JpcHRzL2tlcm5lbC1kb2MgQWxsb3cgc3RydWN0IGFyZ3VtZW50cyBkb2N1bWVudGF0 aW9uIGluIHN0cnVjdAo+IGJvZHkiIGJ1dCB5b3UgYWxyZWFkeSBtZXJnZWQgdGhhdCBvbmUgZm9y IDQuMi4gV2hpY2ggSSBtaXNzZWQsIGJ1dAo+IHdoaWNoIGlzIGdyZWF0IHNpbmNlIHRoYXQncyB0 aGUgb25lIHRoYXQgd291bGQgY2F1c2UgdGhlIGJpZwo+IGNvbmZsaWN0cy4KPiAKPj4+PiAyIFdl J3JlIGNvbnN0cnVjdGluZyBhbiBpbmNyZWFzaW5nbHkgY29tcGxpY2F0ZWQgZG9jdW1lbnQtcHJv Y2Vzc2luZwo+Pj4+ICAgbWVjaGFuaXNtIHdpdGggYSBsb3Qgb2YgaW5kZXBlbmRlbnRseSBtb3Zp bmcgcGFydHMuICBXaGF0IGlmIHdlCj4+Pj4gICBjb252ZXJ0ZWQgdGhlIHdob2xlIGRvY3VtZW50 IHRvIG1hcmtkb3duIGFuZCBkaXNwZW5zZWQgd2l0aCB0aGUgWE1MCj4+Pj4gICBwYXJ0IGFsdG9n ZXRoZXI/ICBNYWtpbmcgdGhlIHNvdXJjZSBmaWxlcyBzaW1wbGVyIGFuZCBkaXNwZW5zaW5nIHdp dGgKPj4+PiAgIHRoZSB4bWx0byByZXF1aXJlbWVudCB3b3VsZCBiZSBhIGJpZyB3aW4sIElNTy4K Pj4+Cj4+PiBXaG8ncyBnb2luZyB0byBjb252ZXJ0IHRoZSBhbG1vc3QgMzBrbG9jIG9mIHhtbCB0 ZW1wbGF0ZSAod2hpY2ggb2Z0ZW4gaGF2ZQo+Pj4gbGFyZ2UgYW1vdW50cyBvZiB0ZXh0cykgYW5k IHRoZSBvdmVyIDYwayBrZXJuZWxkb2MgY29tbWVudHMgdGhhdCB3ZSBoYXZlCj4+PiBhbHJlYWR5 Pwo+Pgo+PiBJIHRob3VnaHQgeW91J2QgZG8gdGhhdCA6KQo+Pgo+PiBTZXJpb3VzbHksIHRob3Vn aCwgYSBjaGFuZ2Ugd291bGQgYmUgYSBiaWcgam9iLiAgVGhlcmUncyBhIHJlYXNvbiBJJ3ZlIHNh aWQKPj4gc2V2ZXJhbCB0aW1lcyB0aGF0IGl0IHdvdWxkIG1ha2Ugbm8gc2Vuc2UgdG8gZGVsYXkg dGhlIHdvcmsgYXQgaGFuZCBpbiB0aGUKPj4gaG9wZXMgb2Ygc29tZWJvZHkgZG9pbmcgdGhpcyB3 aG9sZSBqb2IgaW5zdGVhZC4gIEJ1dCB3ZSBjYW4gY2VydGFpbmx5Cj4+IHBvbmRlciB3aGF0IG1p Z2h0IGJlIGJldHRlci4KPj4KPj4gR2V0dGluZyByaWQgb2YgdGhlIFhNTCBzdHVmZiBtYXkgd2Vs bCBzaW1wbGlmeSB0aGUgd2hvbGUgcHJvY2VzcyBhbmQgbWFrZQo+PiB0aGUgZG9jdW1lbnRhdGlv biBtdWNoIG1vcmUgYWNjZXNzaWJsZSBmb3IgdGhvc2Ugd2hvIHdvdWxkIGNoYW5nZSBpdDsgdGhh dAo+PiBjb3VsZCBiZSBhIGdvYWwgd29ydGggZ29pbmcgZm9yLiAgT2gsIGFuZCBhbnl0aGluZyBy ZXF1aXJpbmcgY2hhbmdlcyB0byB0aGUKPj4ga2VybmVsZG9jIGNvbW1lbnRzIGlzIGdvaW5nIG5v d2hlcmUsIHRoYXQgd2FzIG5ldmVyIHNvbWV0aGluZyBJJ2QKPj4gY29udGVtcGxhdGVkLiAgVGhv c2UgY29tbWVudHMgYXJlIGZpbmUuCj4gCj4gV2VsbCBteSBnb2FsIGlzIHRvIGJlIGFibGUgdG8g aGF2ZSBhbGwgdGhlIHByb2dyYW1tZXIgZG9jcyBpbiB0aGUKPiBjb2RlLCBpbmNsdWRpbmcgYW55 IGhpZ2gtbGV2ZWwgb3ZlcnZpZXcgc2VjdGlvbnMgdG8gdGllIGV2ZXJ5dGhpbmcKPiB0b2dldGhl ciAoaGVuY2UgaHlwZXJsaW5rcyBhbmQgYmV0dGVyIGZvcm1hdHRpbmcpLiBCdXQgdGhlbiB5b3Ug c3RpbGwKPiBuZWVkIHNvbWUgc2tlbGV0b24gdG8gbWFrZSBhIGNvaGVyZW50IHdob2xlIG91dCBv ZiBhbGwgdGhlIHBhcnRzLCBhbmQKPiBJIHRoaW5rIHRoZSBkb2Nib29rIHhtbCB0ZW1wbGF0ZXMg d2UgaGF2ZSBzZXJ2ZSByYXRoZXIgZmluZSBmb3IgdGhhdAo+IHJvbGUuIFdyaXRpbmcgdGV4dCBp biB4bWwgaXMgaW5kZWVkIGhvcnJpZCwgYnV0IGlmIHdlIGNhbiBjcmVhdGUKPiBpbi1saW5lIERP Qzogc2VjdGlvbnMgd2l0aCBkZWNlbnQgZm9ybWF0dGluZyB0aGVyZSdzIHJlYWxseSBubyBuZWVk Cj4gZm9yIHRoYXQuIEZyb20gdGhhdCBhbmdsZSB0aGlzIHdvcmsgaGVyZSBhbHJlYWR5IGhhcyB0 aGUgZ29hbCB0byBnZXQKPiByaWQgb2YgdGhlIHhtbCAtIEkgcGxhbmUgdG8gbW92ZSBhbGwgdGhl IGV4aXN0aW5nIHRleHQgaW4gdGhlIGRybS50bXBsCj4geG1sIGludG8gaW5saW5lIERPQzoga2Vy bmVsZG9jIGNvbW1ldHMuCj4gCj4gQW5kIGF0IGxlYXN0IGd0a2RvYyAod2hpY2ggd2UgdXNlIGV4 dGVuc2l2ZWx5IGZvciB0aGUgdXNlcnBhY2UKPiB0ZXN0L3Rvb2xzIHJlcG8pIHJlbGllcyBvbiBz b21lIHhtbCB0aGluZyB0byB0aWUgZGlmZmVyZW50IHRvcGljcwo+IHRvZ2V0aGVyIHRvby4gU28g dGhhdCBzZWVtcyBwcmV0dHkgc3RhbmRhcmQuCj4gCj4+IEJ1dCBhbnkgc3VjaCBjaGFuZ2UgbmVl ZHMgYSBsb3Qgb2YgdGhvdWdodCBhbmQgYSByZWFzb25hYmxlIHByb29mIG9mCj4+IGNvbmNlcHQu ICBNZWFud2hpbGUgd2UgaGF2ZSB3b3JrIHRoYXQgY2FuIG1ha2UgdGhlIGRvY3MgYmV0dGVyIG5v dywgYW5kIEkKPj4gd2FudCB0byBtZXJnZSBpdC4gIEJ1dCB3ZSBzaG91bGQgY2hvb3NlIHRoZSB0 b29scyB3ZSB1c2UgY2FyZWZ1bGx5LCBhbmQgSQo+PiBhbnRpY2lwYXRlIGEgbG90IG9mIG9wcG9z aXRpb24gdG8gb25lIHRoYXQgaGFzIHRvIGRyYWcgaW4gNzAgSGFza2VsbAo+PiBwYWNrYWdlcyB3 aXRoIGl0Lgo+IAo+IFdlbGwgcGVyc29uYWxseSBJIGRvbid0IGNhcmUgYWJvdXQgdGhlIGV4YWN0 IHRvb2xpbmcsIGFzIGxvbmcgYXM6Cj4gLSBpdCdzIGEgcmVhc29uYWJsZSBhbGl2ZSBwcm9qZWN0 Cj4gLSBwYWNrYWdlcyBhdmFpbGFibGUgb24gZGlzdHJvcyAod29ya3MgZm9yIG1lIG9uIGJvdGgg ZGViaWFuIGFuZCBmZWRvcmEpCj4gLSB3ZSBjYW4gbXVjayBhcm91bmQgd2l0aCBob3cgdGhpbmdz IGFyZSBpbnRlZ3JhdGVkIGludG8gb3ZlcmFsbCBkb2NzCj4gKHdoaWNoIGlzIHRoZSBjYXNlIHNp bmNlIHBhbmRvYyBpcyBvbmx5IHVzZWQgYXMgYSBwYXJhZ3JhcGggZm9ybWF0dGVyCj4gaGVyZSku Cj4gCj4gVGhlIGxhc3Qgb25lIGlzIHNvbWV0aGluZyB3ZSBzdHVtYmxlZCBvdmVyIGZvciB0aGUg dXNlcnNwYWNlIHNpZGUKPiB3aGVyZSB3ZSB3YW50ZWQgdG8gaGF2ZSBiZXR0ZXIgdG9vbGluZyBm b3IgZG9jdW1lbnRpbmcgdGVzdGNhc2VzLgo+IFVwc3RyZWFtIGd0a2RvYyBpcyByZWNlcHRpdmUs IGJ1dCBnZXR0aW5nIGFueXRoaW5nIGluIHRha2VzIGZvcmV2ZXIKPiBhbmQgdGhlbiB0aGVyZSdz IHRoZSA2IG1vbnRoIHJlbGVhc2Ugc2NoZWR1bGUgdG9vLiBBbmQgdGhlcmUncyBhbHNvCj4gdGhl IHByb2JsZW0gdGhhdCB3ZSBjYW4ndCBjaGFuZ2UgdGhlIGtlcm5lbGRvYyBncmFtbWFyIChlLmcu IGd0a2RvYwo+IGhhcyB0aGUgY29kZSBjb21tZW50IHBhcnNlciBpbnRlZ3JhdGVkIGFuZCBvZmMg aXQgaGFzIHNsaWdodGx5Cj4gZGlmZmVyZW50IHJ1bGVzIHRvIG1hcmsgdXAgcmVmZXJlbmNlcyB0 byBzdHJ1Y3RzL2VudW1zKS4KPiAKPiBJJ20gYWxzbyB0cnlpbmcgdG8gYnVpbGQgdXAgYSBkb2Mg dGVhbSBoZXJlIHdpdGggYSBmdWxsLXRpbWUgdGVjaAo+IHdyaXRlciBmb3IgZHJtL2k5MTUgdG9w aWNzLiBTbyBJJ20gdmVyeSBtdWNoIGludGVyZXN0ZWQgaW4ga2VlcGluZwo+IHRoaXMgYWxsIGFs aXZlLiBCdXQgSSBkb24ndCBoYXZlIHRoZSB0aW1lIHRvIG1hc3MtY29udmVydCBldmVyeXRoaW5n Cj4gZWxzZSwgYW5kIEknbSBhbHNvIG5vdCBzdXJlIGl0J3MgYSBnb29kIGlkZWE6IEluIG15IGV4 cGVyaWVuY2UgYWxsIHRoZQo+IGRvYyB0b29sY2hhaW4gc3VjayBzb21ld2hhdCwgYW5kIGl0J3Mg YmV0dGVyIHRvIGJlIGNvbnNpc3RlbnQgd2l0aGluIGEKPiBwcm9qZWN0IGluc3RlYWQgb2YgcHJv bGlmZXJhdGluZyBkaWZmZXJlbnQgc29sdXRpb25zLiBJdCdzIGhhcmQgZW5vdWdoCj4gYWxyZWFk eSB0byBnZXQgZGV2ZWxvcGVycyB0byB3cml0ZSBkb2NzIGFuZCBldmVuIGhhcmRlciB0byBmaW5k Cj4gc29tZW9uZSB3aG8gd3JpdGVzIGdvb2QgZG9jcyAuLi4KPiAKPiBPZmMgd2UgYWxyZWFkeSBo YXZlIGEgYmlnIHNwbGl0IGJldHdlZW4gdGhlIGFkLWhvYyB0ZXh0IGZpbGVzIGluCj4gRG9jdW1l bnRhdGlvbiBhbmQgdGhlIGRvY2Jvb2sgc3R1ZmYgaW4gRG9jdW1lbnRhdGlvbi9Eb2NCb29rLiBP dG9oCj4gZG9jYm9vayBpcyB0aGUgb25seSB3YXkgdG8gZXh0cmFjdCB0aGUga2VybmVsZG9jIGNv bW1lbnRzIGludG8KPiBzb21ldGhpbmcgcmVhZGFibGUgYW5kIGluZGV4ZWQuCj4gCj4+Pj4gSSB3 aWxsIG5vdCBtYWtlICMyIGJlIGEgcHJlY29uZGl0aW9uIHRvIGdldHRpbmcgc29tZSBmb3JtIG9m IHRoaXMgd29yawo+Pj4+IG1lcmdlZCwgYnV0IEkgd291bGQgbGlrZSB0byBoYXZlIGEgZ29vZCBh bnN3ZXIgZm9yICMxLiAgQWRkaW5nIHN1Y2ggYQo+Pj4+IGhlYXZ5d2VpZ2h0IGRlcGVuZGVuY3kg KGV2ZW4gYXMgYW4gb3B0aW9uYWwgb25lKSBuZWVkcyB0byBoYXZlIGEgcHJldHR5Cj4+Pj4gZ29v ZCBzdG9yeSBiZWhpbmQgaXQuCj4+Pgo+Pj4gU2hvdWxkIHdlIGRpc2N1c3MgIzEgYXQga3M/IElt byBhcyBsb25nIGFzIG5vIG9uZSBwaXBlcyB1cCB0byBkbyB0aGUKPj4+IG1hc3NpdmUgY29udmVy c2lvbiBhd2F5IGZyb20gdGhlIGN1cnJlbnQgdG9vbGNoYWluIChhbmQgc3Vic3lzdGVtCj4+PiBt YWludGFpbmVycyB3b24ndCBqdXN0IGtpbGwgdGhhdCBlZmZvcnQgYmVjYXVzZSBpdCBjYXVzZXMg dG9vIG11Y2ggY2h1cm4pCj4+PiBtb3ZpbmcgZm9yd2FyZCB3aXRoIHRoZSBrZXJuZWxkb2MgdG9v bGNoYWluIHdlIGhhdmUgbWFrZXMgc2Vuc2UuIEhlbmNlIEknZAo+Pj4gbGlrZSB0byBzZWUgdGhv c2UgcGF0Y2hlcyBsYW5kZWQgYmVmb3JlIHdlIHJlc29sdmUgIzEgaWYgcG9zc2libGUuCj4+Cj4+ IEkndmUgdG9zc2VkIHRoZSB0b3BpYyBvdXQgdGhlcmU7IHRoZSBrZXJuZWwgc3VtbWl0IGFnZW5k YSBoYXNuJ3QgYmVlbiBtYWRlCj4+IHlldCwgdGhvdWdoLiAgSW4gYW55IGNhc2UsIEknZCBiZSBo YXBweSB0byByZXNvbHZlIHRoaXMgcGFydGljdWxhciBpc3N1ZQo+PiBiZWZvcmUgdGhlbiBpZiBp dCB3ZXJlIHBvc3NpYmxlLgo+IAo+IEkgZG9uJ3QgbWluZCBtdWNoIGlmIHdlIGRlbGF5IHRoaXMg cGFydCB1bnRpbCBLUy4gQWxsIHRoZSB0ZXh0IG1hcmt1cAo+IHN0eWxlcyBhcmUgcHJldHR5IGNs b3NlLiBTbyBmaXhpbmcgdXAgb25lIGRpYWxlY3QgZm9yIGFub3RoZXIgZm9yIHRoZQo+IGZldyBw YXRjaGVzIEknbGwgbGlrZWx5IHB1bGwgaW4gZm9yIDQuNCB3b24ndCBiZSBhIGxvdCBvZiB3b3Jr IGlmIHdlCj4gZGVjaWRlIHRvIGdvIHdpdGggc29tZXRoaW5nIGVsc2UuIE9yIGV2ZW4gaWYgd2Ug ZGVjaWRlIHRvIHN3aXRjaAo+IG1hcmt1cCBzdHlsZXMgbXVjaCBsYXRlciwgaXQgc2hvdWxkIGFs bCBiZSBkb2FibGUgd2l0aCBhIGZldyBzZWQgam9icy4KPiAKPiBPbmx5IHByb2JsZW0gSSBzZWUg aXMgdGhhdCB0aHVzIGZhciBubyBvbmUgZWxzZSBzZWVtcyB0byBjYXJlIG11Y2gsCj4gYW5kIGlm IHdlIGNoYW5nZSB0aGUgYXBwcm9hY2ggSSBuZWVkIHRvIGNvbnZpbmNlIG1hbmFnZW1lbnQgaGVy ZSBhZ2Fpbgo+IHRoYXQgd2UgbmVlZCB0byBpbnZlc3Qgc29tZSB0aW1lIHRvIG1ha2UgaXQgaGFw cGVuIChhbmQgc29tZSBleGN1c2VzCj4gd2h5IHRoaXMgYXBwcm9hY2ggaGVyZSB3YXNuJ3Qgb2sp LiBUaGF0IHdpbGwgcHJvYmFibHkgc3VjayBkb3duIG1vcmUKPiB0aW1lIHRoYW4gY29udmVydGlu ZyB0byB3aGF0ZXZlciB3ZSBkZWNpZGUgb24uIEFuZCBsaWtlIEkgc2FpZCBJCj4gcGVyc29uYWxs eSBkb24ndCBjYXJlIG9uZSBiaXQgd2hhdCB0aGUgdG9vbGNoYWluIGxvb2tzIGxpa2Ugb3IgdGhl Cj4gZXhhY3QgZmxhdm91ciBvZiB0ZXh0IG1hcmt1cCB3ZSBwaWNrLgo+IAo+IENoZWVycywgRGFu aWVsCj4gCl9fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fCmRy aS1kZXZlbCBtYWlsaW5nIGxpc3QKZHJpLWRldmVsQGxpc3RzLmZyZWVkZXNrdG9wLm9yZwpodHRw Oi8vbGlzdHMuZnJlZWRlc2t0b3Aub3JnL21haWxtYW4vbGlzdGluZm8vZHJpLWRldmVsCg== From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752655AbbINMLL (ORCPT ); Mon, 14 Sep 2015 08:11:11 -0400 Received: from bhuna.collabora.co.uk ([93.93.135.160]:47198 "EHLO bhuna.collabora.co.uk" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751285AbbINMLJ (ORCPT ); Mon, 14 Sep 2015 08:11:09 -0400 Subject: Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements To: Daniel Vetter , Jonathan Corbet References: <1441656124-8997-1-git-send-email-danilo.cesar@collabora.co.uk> <20150912152449.1cdc1710@lwn.net> <20150913103607.GA3383@phenom.ffwll.local> <20150913131356.780426e9@lwn.net> Cc: Andrew Morton , Johannes Berg , Linux Kernel Mailing List , linux-doc@vger.kernel.org, intel-gfx , dri-devel From: Danilo Cesar Lemes de Paula X-Enigmail-Draft-Status: N1110 Message-ID: <55F6B954.30506@collabora.co.uk> Date: Mon, 14 Sep 2015 09:11:00 -0300 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.2.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 09/13/2015 05:58 PM, Daniel Vetter wrote: > On Sun, Sep 13, 2015 at 9:13 PM, Jonathan Corbet wrote: >> On Sun, 13 Sep 2015 12:36:07 +0200 >> Daniel Vetter wrote: >> >>> Personally I don't care which kind of text markup we pick and wich >>> converter, as long as the project looks reasonable far away from >>> immeninent death (way too many one-person projects on github in this >>> area). I wouldn't care either. I choose pandoc as it's old, kind of stable and has a decent community around it, so it won't probably die due the lack of interested developers. That said, cmark is not a option (at least for now). With the current approach we need a tool capable of reading markdown text and output DocBook tags, as we're actually still using docbook to spit all kinds of Documentation formats (html, man, pdf). Looks like cmark can only do markdown->html. I did look into other options though, but they were all mostly one-man job. But yeah, basically any tool capable of converting markdown->docbook will work. I'm always listening to suggestions =) >>> >>> But if we have this discussion I'd like to decouple it from the other >>> kerneldoc improvemnts in this series (patches 1, 5 and 6). If we cant >>> agree on the text markup then drm docs will simply look a bit funny for >>> everyone else. But if the inline struct stuff won't happen 0-day will >>> scream around (and there's already patches which use the new layout). >> >> Those patches are: >> >> 1) scripts/kernel-doc: Replacing highlights hash by an array >> 5) scripts/kernel-doc: Improve Markdown results >> 6) scripts/kernel-doc: Processing -nofunc for functions only >> >> #1 is fine, I'll merge that today. #6 is already merged. #5 is a markdown >> patch, though, and doesn't make sense without the others? Are you thinking >> about #3 (drm/doc: Convert to markdown)? That one would almost work (it >> depends on #2 currently) and it nicely shows *why* I'd like to get away from >> XML... #5 is the DRM markdown conversion, which depends on #2 and #4. So if a decision about this is going during KS, we need to hold those three patches. > > Sorry I mixed things up, #5 is ok to leave out. I thought about > "scripts/kernel-doc Allow struct arguments documentation in struct > body" but you already merged that one for 4.2. Which I missed, but > which is great since that's the one that would cause the big > conflicts. > >>>> 2 We're constructing an increasingly complicated document-processing >>>> mechanism with a lot of independently moving parts. What if we >>>> converted the whole document to markdown and dispensed with the XML >>>> part altogether? Making the source files simpler and dispensing with >>>> the xmlto requirement would be a big win, IMO. >>> >>> Who's going to convert the almost 30kloc of xml template (which often have >>> large amounts of texts) and the over 60k kerneldoc comments that we have >>> already? >> >> I thought you'd do that :) >> >> Seriously, though, a change would be a big job. There's a reason I've said >> several times that it would make no sense to delay the work at hand in the >> hopes of somebody doing this whole job instead. But we can certainly >> ponder what might be better. >> >> Getting rid of the XML stuff may well simplify the whole process and make >> the documentation much more accessible for those who would change it; that >> could be a goal worth going for. Oh, and anything requiring changes to the >> kerneldoc comments is going nowhere, that was never something I'd >> contemplated. Those comments are fine. > > Well my goal is to be able to have all the programmer docs in the > code, including any high-level overview sections to tie everything > together (hence hyperlinks and better formatting). But then you still > need some skeleton to make a coherent whole out of all the parts, and > I think the docbook xml templates we have serve rather fine for that > role. Writing text in xml is indeed horrid, but if we can create > in-line DOC: sections with decent formatting there's really no need > for that. From that angle this work here already has the goal to get > rid of the xml - I plane to move all the existing text in the drm.tmpl > xml into inline DOC: kerneldoc commets. > > And at least gtkdoc (which we use extensively for the userpace > test/tools repo) relies on some xml thing to tie different topics > together too. So that seems pretty standard. > >> But any such change needs a lot of thought and a reasonable proof of >> concept. Meanwhile we have work that can make the docs better now, and I >> want to merge it. But we should choose the tools we use carefully, and I >> anticipate a lot of opposition to one that has to drag in 70 Haskell >> packages with it. > > Well personally I don't care about the exact tooling, as long as: > - it's a reasonable alive project > - packages available on distros (works for me on both debian and fedora) > - we can muck around with how things are integrated into overall docs > (which is the case since pandoc is only used as a paragraph formatter > here). > > The last one is something we stumbled over for the userspace side > where we wanted to have better tooling for documenting testcases. > Upstream gtkdoc is receptive, but getting anything in takes forever > and then there's the 6 month release schedule too. And there's also > the problem that we can't change the kerneldoc grammar (e.g. gtkdoc > has the code comment parser integrated and ofc it has slightly > different rules to mark up references to structs/enums). > > I'm also trying to build up a doc team here with a full-time tech > writer for drm/i915 topics. So I'm very much interested in keeping > this all alive. But I don't have the time to mass-convert everything > else, and I'm also not sure it's a good idea: In my experience all the > doc toolchain suck somewhat, and it's better to be consistent within a > project instead of proliferating different solutions. It's hard enough > already to get developers to write docs and even harder to find > someone who writes good docs ... > > Ofc we already have a big split between the ad-hoc text files in > Documentation and the docbook stuff in Documentation/DocBook. Otoh > docbook is the only way to extract the kerneldoc comments into > something readable and indexed. > >>>> I will not make #2 be a precondition to getting some form of this work >>>> merged, but I would like to have a good answer for #1. Adding such a >>>> heavyweight dependency (even as an optional one) needs to have a pretty >>>> good story behind it. >>> >>> Should we discuss #1 at ks? Imo as long as no one pipes up to do the >>> massive conversion away from the current toolchain (and subsystem >>> maintainers won't just kill that effort because it causes too much churn) >>> moving forward with the kerneldoc toolchain we have makes sense. Hence I'd >>> like to see those patches landed before we resolve #1 if possible. >> >> I've tossed the topic out there; the kernel summit agenda hasn't been made >> yet, though. In any case, I'd be happy to resolve this particular issue >> before then if it were possible. > > I don't mind much if we delay this part until KS. All the text markup > styles are pretty close. So fixing up one dialect for another for the > few patches I'll likely pull in for 4.4 won't be a lot of work if we > decide to go with something else. Or even if we decide to switch > markup styles much later, it should all be doable with a few sed jobs. > > Only problem I see is that thus far no one else seems to care much, > and if we change the approach I need to convince management here again > that we need to invest some time to make it happen (and some excuses > why this approach here wasn't ok). That will probably suck down more > time than converting to whatever we decide on. And like I said I > personally don't care one bit what the toolchain looks like or the > exact flavour of text markup we pick. > > Cheers, Daniel >