From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1750972AbcFDMzJ (ORCPT ); Sat, 4 Jun 2016 08:55:09 -0400 Received: from mga02.intel.com ([134.134.136.20]:2808 "EHLO mga02.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750829AbcFDMzH (ORCPT ); Sat, 4 Jun 2016 08:55:07 -0400 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.26,417,1459839600"; d="scan'208";a="995139061" From: Jani Nikula To: Jonathan Corbet 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 In-Reply-To: <20160603141618.56417305@lwn.net> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20160603141618.56417305@lwn.net> User-Agent: Notmuch/0.22+9~g73339ad (http://notmuchmail.org) Emacs/24.4.1 (x86_64-pc-linux-gnu) Date: Sat, 04 Jun 2016 15:54:34 +0300 Message-ID: <87k2i5867p.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Fri, 03 Jun 2016, Jonathan Corbet wrote: > [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. Actually, mostly this is not a problem due to EXPORT_SYMBOL placement, but rather due to kernel-doc comments being placed in header files above function declarations while EXPORT_SYMBOL is where it should be next to the function definition. I don't think we can force people to move the kernel-doc comments for exported functions from header files next to the function definitions. The straightforward fix to this is to add an optional filename parameter to the kernel-doc extension :export: argument, to pass additional files to kernel-doc where to look for the EXPORT_SYMBOLs. For example: .. kernel-doc:: include/drm/foo.h :export: drivers/gpu/drm/foo/foo.c drivers/gpu/drm/foo/bar.c This would instruct kernel-doc to extract documentation from include/drm/foo.h for all functions that have been exported using EXPORT_SYMBOL (or _GPL) in include/drm/foo.h, drivers/gpu/drm/foo/foo.c, or drivers/gpu/drm/foo/bar.c. We have something along these lines in docproc already with the !D directive, so nothing altogether surprising. If my quick grep-fu serves me right, there are about a thousand exported symbols with kernel-doc comments in the headers. It's a ballpark figure. They come in batches; a small fraction of that many filenames in a fraction of the :export: statements would cover most of them. Before this fix, the workaround is to name the functions with :functions: argument instead of using :export:. I'm hoping this is not a blocker for merging the series. If the proposed fix is acceptable, I'll get it done before v4.8. BR, Jani. The ugly greps: $ git grep "^EXPORT_SYMBOL" | sed 's/^[^(]*(\([a-zA-Z0-9_]*\)).*/\1/' | sort > exports $ git grep -h -A1 "^/\*\*$" -- *.h | grep -v "^\(/\*\*\|--\)" | sed 's/^ \*[ ]*\([a-zA-Z0-9_][a-zA-Z0-9_]*\).*/\1/;' | sort > comments $ comm -1 -2 comments exports | wc -l 952 -- Jani Nikula, Intel Open Source Technology Center