From patchwork Fri Mar 31 07:16:31 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Johannes Berg X-Patchwork-Id: 9655543 X-Patchwork-Delegate: johannes@sipsolutions.net Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 35440602BD for ; Fri, 31 Mar 2017 07:16:40 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 25C4F28663 for ; Fri, 31 Mar 2017 07:16:40 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 1AF8728683; Fri, 31 Mar 2017 07:16:40 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id BF0F928663 for ; Fri, 31 Mar 2017 07:16:39 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932437AbdCaHQh (ORCPT ); Fri, 31 Mar 2017 03:16:37 -0400 Received: from s3.sipsolutions.net ([5.9.151.49]:42942 "EHLO sipsolutions.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932271AbdCaHQg (ORCPT ); Fri, 31 Mar 2017 03:16:36 -0400 Received: by sipsolutions.net with esmtpsa (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.89_RC7) (envelope-from ) id 1ctqnS-0007WX-5L; Fri, 31 Mar 2017 09:16:34 +0200 From: Johannes Berg To: linux-wireless@vger.kernel.org, linux-doc@vger.kernel.org Cc: Johannes Berg Subject: [PATCH 1/2] Documentation/sphinx: kerneldoc: add "unused-functions" Date: Fri, 31 Mar 2017 09:16:31 +0200 Message-Id: <20170331071632.6209-1-johannes@sipsolutions.net> X-Mailer: git-send-email 2.11.0 Sender: linux-wireless-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-wireless@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Johannes Berg When adding functions one by one into documentation, in order to order/group things properly, it's easy to miss things. Allow use of the kernel-doc directive with "unused-functions" like this .. kernel-doc:: :unused-functions: to output anything previously unused from that file. This allows grouping things but still making sure that the documentation has all the functions. Internally this works by collecting (per-file) those functions (and enums, structs, doc sections...) that are explicitly used, and invoking the kernel-doc script with "-nofunction" later. Signed-off-by: Johannes Berg --- Documentation/sphinx/kerneldoc.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index d15e07f36881..79fc1491348a 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -41,6 +41,9 @@ from sphinx.ext.autodoc import AutodocReporter __version__ = '1.0' +# per-file list +_used_fns = {} + class KernelDocDirective(Directive): """Extract kernel-doc comments from the specified file""" required_argument = 1 @@ -50,6 +53,7 @@ class KernelDocDirective(Directive): 'functions': directives.unchanged_required, 'export': directives.unchanged, 'internal': directives.unchanged, + 'unused-functions': directives.unchanged, } has_content = False @@ -60,6 +64,10 @@ class KernelDocDirective(Directive): filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] export_file_patterns = [] + if not filename in _used_fns: + _used_fns[filename] = [] + _used_fns_this_file = _used_fns[filename] + # Tell sphinx of the dependency env.note_dependency(os.path.abspath(filename)) @@ -73,10 +81,16 @@ class KernelDocDirective(Directive): cmd += ['-internal'] export_file_patterns = str(self.options.get('internal')).split() elif 'doc' in self.options: - cmd += ['-function', str(self.options.get('doc'))] + f = str(self.options.get('doc')) + cmd += ['-function', f] + _used_fns_this_file.append(f) + elif 'unused-functions' in self.options: + for f in _used_fns_this_file: + cmd += ['-nofunction', f] elif 'functions' in self.options: for f in str(self.options.get('functions')).split(): cmd += ['-function', f] + _used_fns_this_file.append(f) for pattern in export_file_patterns: for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):