From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-9.5 required=3.0 tests=DKIM_ADSP_CUSTOM_MED, DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0C821CA9EA0 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 AD81A21897 for ; Sun, 20 Oct 2019 13:17:40 +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 AD81A21897 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) Received: by kanga.kvack.org (Postfix, from userid 40) id 3FE0D8E0003; Sun, 20 Oct 2019 09:17:40 -0400 (EDT) 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-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-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 Content-Transfer-Encoding: quoted-printable 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-g= uide/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: =20 +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 =20 -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 com= ments from the source file. =20 diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/ker= neldoc.py index 1159405cb920..0689f9c37f1e 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -59,9 +59,10 @@ class KernelDocDirective(Directive): optional_arguments =3D 4 option_spec =3D { 'doc': directives.unchanged_required, - 'functions': directives.unchanged, 'export': directives.unchanged, 'internal': directives.unchanged, + 'identifiers': directives.unchanged, + 'functions': directives.unchanged, # alias of 'identifiers' } has_content =3D False =20 @@ -71,6 +72,7 @@ class KernelDocDirective(Directive): =20 filename =3D env.config.kerneldoc_srctree + '/' + self.arguments= [0] export_file_patterns =3D [] + identifiers =3D None =20 # Tell sphinx of the dependency env.note_dependency(os.path.abspath(filename)) @@ -86,19 +88,22 @@ class KernelDocDirective(Directive): export_file_patterns =3D str(self.options.get('internal')).s= plit() elif 'doc' in self.options: cmd +=3D ['-function', str(self.options.get('doc'))] + elif 'identifiers' in self.options: + identifiers =3D self.options.get('identifiers').split() elif 'functions' in self.options: - functions =3D self.options.get('functions').split() - if functions: - for f in functions: - cmd +=3D ['-function', f] - else: - cmd +=3D ['-no-doc-sections'] + identifiers =3D self.options.get('functions').split() =20 for pattern in export_file_patterns: for f in glob.glob(env.config.kerneldoc_srctree + '/' + patt= ern): env.note_dependency(os.path.abspath(f)) cmd +=3D ['-export-file', f] =20 + if identifiers: + for i in identifiers: + cmd +=3D ['-function', i] + elif identifiers is not None: + cmd +=3D ['-no-doc-sections'] + cmd +=3D [filename] =20 try: --=20 2.20.1