From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755351AbbIMV0V (ORCPT ); Sun, 13 Sep 2015 17:26:21 -0400 Received: from mailout1.hostsharing.net ([83.223.95.204]:39270 "EHLO mailout1.hostsharing.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752274AbbIMV0S (ORCPT ); Sun, 13 Sep 2015 17:26:18 -0400 X-Greylist: delayed 494 seconds by postgrey-1.27 at vger.kernel.org; Sun, 13 Sep 2015 17:26:18 EDT Date: Sun, 13 Sep 2015 23:17:58 +0200 From: Lukas Wunner To: Jonathan Corbet Cc: Danilo Cesar Lemes de Paula , Michal Marek , Herbert Xu , linux-doc@vger.kernel.org, Stephan Mueller , Daniel Vetter , intel-gfx , Randy Dunlap , linux-kernel@vger.kernel.org, dri-devel , Laurent Pinchart Subject: Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array Message-ID: <20150913211758.GA6103@wunner.de> References: <1441656124-8997-1-git-send-email-danilo.cesar@collabora.co.uk> <1441656124-8997-2-git-send-email-danilo.cesar@collabora.co.uk> <20150913143647.1c7a9b05@lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20150913143647.1c7a9b05@lwn.net> 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 Hi, On Sun, Sep 13, 2015 at 02:36:47PM -0600, Jonathan Corbet wrote: > On Mon, 7 Sep 2015 17:01:59 -0300 > Danilo Cesar Lemes de Paula wrote: > > The "highlight" code is very sensible to the order of the hash keys, > > but the order of the keys cannot be predicted. It generates > > faulty DocBook entries like: > > - @device_for_each_child > > > > Sorting the result is not enough some times (as it's deterministic but > > we can't control it). > > We should use an array for that job, so we can guarantee that the order > > of the regex execution on dohighlight is correct. > OK, I've spent a bunch of time with this, comparing the results before > and after. The output you mention is clearly wrong, but there might be > room to differ over what the root cause is. > > That output is caused by @device_for_each_child() in the comments. This > happens for a few other functions as well, and I think it's wrong. @ is > used to indicate parameters (or structure fields); I'm not sure why > people are using it for functions that are *not* one of the above. > Formatting the function names as a parameter doesn't seem right either. Shouldn't kernel-doc print a warning for syntactic mistakes like this rather than silently accomodating to it in whatever way? As to the usage of markdown in general, there's documentation coming up for vga_switcheroo which makes use of that so I'd love to see it merged: https://github.com/l1k/linux/commit/d1476d748b5f1adf5bffe8e0a8bafad1e879d22f https://github.com/l1k/linux/commit/11c55ae65788162970d8fa23cd1fd2518af55d34 The large set of dependencies pulled in on Fedora is likely to be blamed on the RedHat packaging being notoriously coarse-grained. By comparison, Debian is extremely fine-grained, kind of the opposite extreme, and therefore has comparatively few prerequisites: https://packages.debian.org/jessie/pandoc I do agree however that alternative tools with fewer dependencies should be supported and it would be great if the markdown patches were amended to that end. Best regards, Lukas