From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752861AbcFCUQ2 (ORCPT ); Fri, 3 Jun 2016 16:16:28 -0400 Received: from tex.lwn.net ([70.33.254.29]:52184 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751147AbcFCUQU (ORCPT ); Fri, 3 Jun 2016 16:16:20 -0400 Date: Fri, 3 Jun 2016 14:16:18 -0600 From: Jonathan Corbet To: Jani Nikula Cc: Markus Heiser , Daniel Vetter , Grant Likely , Mauro Carvalho Chehab , Dan Allen , Russel Winder , Keith Packard , LKML , linux-doc@vger.kernel.org, Hans Verkuil Subject: Re: [PATCH 00/10] Documentation/Sphinx Message-ID: <20160603141618.56417305@lwn.net> In-Reply-To: References: Organization: LWN.net X-Mailer: Claws Mail 3.13.2 (GTK+ 2.24.30; 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 [So I'm finally trying to get into this for real, hopefully I won't be interrupted too many times...expect a few mails as I catch up.] On Fri, 20 May 2016 16:39:31 +0300 Jani Nikula wrote: > There are a few tradeoffs, of course. First, this requires that the > EXPORT_SYMBOL markers are placed immediately after the function being > exported, as kernel-doc will only look at one file at a time. This is > the recommendation anyway. As I understand it, the technical reasons that kept some markers in separate files should no longer be relevant, so this is probably OK. It would be nice to have a sense for how many sites need to be fixed. > Second, we lose support for the !C docproc directive to check > that all kernel-doc comments in a file are used. This is probably > something we'd like to have back in the future, but at this time I think > it's an acceptable tradeoff wrt the gains. This is maybe a job for a separate tool. A related issue is the (fairly frequent) "oh look, none of the comments in $FILE are being used" realization that seems to happen fairly often. It would be nice to check for that, but that's going to be hard to shoehorn into Sphinx. jon