From patchwork Sun Oct 20 13:17:17 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Changbin Du X-Patchwork-Id: 11200919 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 7008713B1 for ; Sun, 20 Oct 2019 13:17:41 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id 2786D21927 for ; Sun, 20 Oct 2019 13:17:41 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Ui3zDKwE" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 2786D21927 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id 44CCF8E0006; Sun, 20 Oct 2019 09:17:40 -0400 (EDT) Delivered-To: linux-mm-outgoing@kvack.org Received: by kanga.kvack.org (Postfix, from userid 40) id 3FE0D8E0003; Sun, 20 Oct 2019 09:17:40 -0400 (EDT) X-Original-To: int-list-linux-mm@kvack.org X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 2EAEA8E0006; Sun, 20 Oct 2019 09:17:40 -0400 (EDT) X-Original-To: linux-mm@kvack.org X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0119.hostedemail.com [216.40.44.119]) by kanga.kvack.org (Postfix) with ESMTP id 06E1B8E0003 for ; Sun, 20 Oct 2019 09:17:39 -0400 (EDT) Received: from smtpin13.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay05.hostedemail.com (Postfix) with SMTP id 973CA181AEF3C for ; Sun, 20 Oct 2019 13:17:39 +0000 (UTC) X-FDA: 76064215038.13.frame02_42cdfb6a22e42 X-Spam-Summary: 2,0,0,4afaba91aac297ab,d41d8cd98f00b204,changbin.du@gmail.com,:corbet@lwn.net:linux-pci@vger.kernel.org:linux-doc@vger.kernel.org:linux-kernel@vger.kernel.org::linux-crypto@vger.kernel.org:linux-kselftest@vger.kernel.org:linux-wireless@vger.kernel.org:linux-fpga@vger.kernel.org:linux-usb@vger.kernel.org:dri-devel@lists.freedesktop.org:intel-gfx@lists.freedesktop.org:willy@infradead.org:jani.nikula@linux.intel.com:tzimmermann@suse.de:changbin.du@gmail.com,RULES_HIT:41:69:355:379:541:800:960:973:988:989:1260:1311:1314:1345:1437:1515:1535:1544:1711:1730:1747:1777:1792:1801:2393:2559:2562:2693:2895:3138:3139:3140:3141:3142:3355:3865:3866:3867:3868:3870:3871:3872:4118:4250:4321:4605:5007:6119:6261:6653:6742:7514:7903:7904:8957:9121:9413:9592:10004:11026:11232:11658:11914:12043:12297:12438:12517:12519:12555:12679:12895:13161:13200:13229:13255:13894:14181:14394:14687:14721:21080:21444:21451:21619:21666:21740:30029:30054:30062,0,RBL:209.85.221.68:@gmail.com:.lbl8.mail shell.ne X-HE-Tag: frame02_42cdfb6a22e42 X-Filterd-Recvd-Size: 7636 Received: from mail-wr1-f68.google.com (mail-wr1-f68.google.com [209.85.221.68]) by imf03.hostedemail.com (Postfix) with ESMTP for ; Sun, 20 Oct 2019 13:17:38 +0000 (UTC) Received: by mail-wr1-f68.google.com with SMTP id q13so5882290wrs.12 for ; Sun, 20 Oct 2019 06:17:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=WBsUqs8jqBvSIFfpE9lf40jZypisanH4mwM2peO1OfA=; b=Ui3zDKwE8mZ777YswsWFDM41503cR/Au164MXSpukz7I9tzle0EewBrGeDlCbIWZ6i vQGRLB7rFK3sIW/etfrouDUQ+qrHkcDcadtR0ZQ9HzGRaNYnPYJc/4+OyAsM/VOxN+Oc HhyA8n7OBsUpzXdHgYIk0lM914nUHAh3gTUE6eY6n7e8HSz0zMXqthiDCNOM64hSIwMW IhP15NY/qvRK6hcBXOyVlt4tn9nF9t4D2/6uJhPaSGivQ8i/BX9NCQSWYM3P0jbo9/yd o7497MqB6WuUgiaDY67aSfuB69dn85j+JFCyaJ8er33uESicycKqiePQKnGb5URCnKMt hpCA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=WBsUqs8jqBvSIFfpE9lf40jZypisanH4mwM2peO1OfA=; b=Fqmfc98GSecWqZ2ECKjj8LUqAKWFdIhD3YpU7Mj8+qHLh5JEEzxsLVjODWYPJwaQBU mW7RoS6j2YXJVq9zBtFMtmX1Q7bZZnRtVUVGngII9eSVxhXgpsNV53TDUrNLZSvhk6Uw 7+h6NzPqhNCLipywj5yWiVocZU40Q8fmzok1EFMFSwCFaIdSui45WTZKzH/VcZ2h2Zdz whZxN5xqKnj7sQ9cWn/cNr7bdJWJ4piIgpubZdKrXT+mz941YHHYTykYfuCc+0kcaRez UO5pHoq7Ag+kzFcpHoXl4sIorDKyDDMKNaRlxA4T2AclyjV+Wj1VkIowyVdgPlOsdGp2 5uvw== X-Gm-Message-State: APjAAAVDdxxghq66T4BrZ4nLfIDXNcxYjrkKFY7bMej+NcYdqYpzLEFI wOXpnhyIhFRdTuBnmm7eMt4= X-Google-Smtp-Source: APXvYqxe9wBz7AvNQplFig0s8Ty42QjBm2sUBHVRMHsK3/4gvqgaFlt4aDECnevElIJZlxJGpTDrIg== X-Received: by 2002:adf:da42:: with SMTP id r2mr14944541wrl.383.1571577457611; Sun, 20 Oct 2019 06:17:37 -0700 (PDT) Received: from localhost.localdomain ([104.238.174.53]) by smtp.gmail.com with ESMTPSA id y3sm20177657wro.36.2019.10.20.06.17.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 20 Oct 2019 06:17:36 -0700 (PDT) From: Changbin Du To: Jonathan Corbet Cc: linux-pci@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org, linux-crypto@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-wireless@vger.kernel.org, linux-fpga@vger.kernel.org, linux-usb@vger.kernel.org, dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, Matthew Wilcox , jani.nikula@linux.intel.com, Thomas Zimmermann , Changbin Du Subject: [PATCH v2] kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers' Date: Sun, 20 Oct 2019 21:17:17 +0800 Message-Id: <20191020131717.28990-1-changbin.du@gmail.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: The 'functions' directive is not only for functions, but also works for structs/unions. So the name is misleading. This patch renames it to 'identifiers', which specific the functions/types to be included in documentation. We keep the old name as an alias of the new one before all documentation are updated. Signed-off-by: Changbin Du --- v2: o use 'identifiers' as the new directive name. --- Documentation/doc-guide/kernel-doc.rst | 29 ++++++++++++++------------ Documentation/sphinx/kerneldoc.py | 19 ++++++++++------- 2 files changed, 28 insertions(+), 20 deletions(-) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 192c36af39e2..fff6604631ea 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -476,6 +476,22 @@ internal: *[source-pattern ...]* .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :internal: +identifiers: *[ function/type ...]* + Include documentation for each *function* and *type* in *source*. + If no *function* is specified, the documentation for all functions + and types in the *source* will be included. + + Examples:: + + .. kernel-doc:: lib/bitmap.c + :identifiers: bitmap_parselist bitmap_parselist_user + + .. kernel-doc:: lib/idr.c + :identifiers: + +functions: *[ function/type ...]* + This is an alias of the 'identifiers' directive and deprecated. + doc: *title* Include documentation for the ``DOC:`` paragraph identified by *title* in *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* @@ -488,19 +504,6 @@ doc: *title* .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :doc: High Definition Audio over HDMI and Display Port -functions: *[ function ...]* - Include documentation for each *function* in *source*. - If no *function* is specified, the documentation for all functions - and types in the *source* will be included. - - Examples:: - - .. kernel-doc:: lib/bitmap.c - :functions: bitmap_parselist bitmap_parselist_user - - .. kernel-doc:: lib/idr.c - :functions: - Without options, the kernel-doc directive includes all documentation comments from the source file. diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 1159405cb920..0689f9c37f1e 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -59,9 +59,10 @@ class KernelDocDirective(Directive): optional_arguments = 4 option_spec = { 'doc': directives.unchanged_required, - 'functions': directives.unchanged, 'export': directives.unchanged, 'internal': directives.unchanged, + 'identifiers': directives.unchanged, + 'functions': directives.unchanged, # alias of 'identifiers' } has_content = False @@ -71,6 +72,7 @@ class KernelDocDirective(Directive): filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] export_file_patterns = [] + identifiers = None # Tell sphinx of the dependency env.note_dependency(os.path.abspath(filename)) @@ -86,19 +88,22 @@ class KernelDocDirective(Directive): export_file_patterns = str(self.options.get('internal')).split() elif 'doc' in self.options: cmd += ['-function', str(self.options.get('doc'))] + elif 'identifiers' in self.options: + identifiers = self.options.get('identifiers').split() elif 'functions' in self.options: - functions = self.options.get('functions').split() - if functions: - for f in functions: - cmd += ['-function', f] - else: - cmd += ['-no-doc-sections'] + identifiers = self.options.get('functions').split() for pattern in export_file_patterns: for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): env.note_dependency(os.path.abspath(f)) cmd += ['-export-file', f] + if identifiers: + for i in identifiers: + cmd += ['-function', i] + elif identifiers is not None: + cmd += ['-no-doc-sections'] + cmd += [filename] try: