From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 51F6EC433FE for ; Fri, 18 Feb 2022 18:16:49 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239072AbiBRSRE (ORCPT ); Fri, 18 Feb 2022 13:17:04 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53300 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233228AbiBRSQ7 (ORCPT ); Fri, 18 Feb 2022 13:16:59 -0500 Received: from mail-wr1-x432.google.com (mail-wr1-x432.google.com [IPv6:2a00:1450:4864:20::432]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E1E28B32; Fri, 18 Feb 2022 10:16:41 -0800 (PST) Received: by mail-wr1-x432.google.com with SMTP id p9so15892947wra.12; Fri, 18 Feb 2022 10:16:41 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=60WfrxgVMKQI4zJcrOBqZYpPlE/wCIZ8P+dtpfYXPkI=; b=fiIiBcLWdP+8+IT79yBp5InVJ72o+Pi2rARnrcsVrF/Wic68xivQH9tJNHtJ8erna4 qnpJ+rZt6UvniUuQcq7z7uc/PC+6AL2Zad5TiG3ZVFX6ih4xoxzqzdi33is+W936ae95 xeW4DX30A3vGQ0aCoZSToCMtxXRHNJkbI0Yd+PC0JUpn0nDNhImu61ldaR0qLhcSR+Jy 2DRE+I70k/PAm601odyuS6Y9RtWFeqXBYQ3yjvVnELsN4KGTHDNPiHHiUUquHEjywp31 xi/lDJFVf7k8A6ZHjrlNuJhYDF7zmzc/ioaustDTiKpSZmjCxY6McRAS9Z1byx7Xiv3r rmew== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=60WfrxgVMKQI4zJcrOBqZYpPlE/wCIZ8P+dtpfYXPkI=; b=ff/DZVPM9sqLjiZifp3YjOuhYXBtkr/mJHqUzJmChfkY2FQ+EGRvVFX97sEHMMytxY V5eL07ZGwiS4T+LX9myQJDl/h+tjoTIC57aOCXD23TEfNols1brmT8f9YQwGda37PErp OrHEWzquSywRhPFG9MaSufOVjLM+N4SJi2HYRocspxbl32hifdvr0g7wflmoAh/4ksM9 I4wd60lkmg7r32+U9JAeTcfq4GrzfB/faXk+8esb1GQ1uvQBVFL0nyKVF5VkDUofIHv/ oKsd5idQHgmyQQfrNdfX5QHP3l3gEynzTSo1FWxSTpn4dG05zYliIRxj0oKMHH6GR79f CpIg== X-Gm-Message-State: AOAM5313EXRVdQsnd2j87q0ZCjxoTxF5dN5eryasWk55tcMG9sJOyrE/ tN2lpFTbf1DlQMPBkmOLqyE= X-Google-Smtp-Source: ABdhPJzkA8jJy2xMB1ke00Fe2OJZPVG0khdRBVSZDzdbyFv7GWWNj70xhDzGRSPr6OM6yvtknvTleQ== X-Received: by 2002:a05:6000:1881:b0:1e8:f75c:591d with SMTP id a1-20020a056000188100b001e8f75c591dmr5353507wri.257.1645208200437; Fri, 18 Feb 2022 10:16:40 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.39 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:40 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v4 01/11] scripts: kernel-doc: Add the basic POD sections Date: Fri, 18 Feb 2022 19:16:18 +0100 Message-Id: <20220218181628.1411551-2-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org The NAME section provides the doc title, while SYNOPSIS contains the basic syntax and usage description, which will be printed in the help document and in the error output produced on wrong script usage. The rationale is to give users simple and succinct enlightment, at the same time structuring the script internally for the maintainers. In the synopsis, Rst-only options are grouped around rst, and the rest is arranged as in the OPTIONS subsections (yet to be translated into POD, check at the end of the series). The third of the basic sections, DESCRIPTION, is added separately. Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- scripts/kernel-doc | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 3106b7536b89..c8fbf1d3d5aa 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -16,6 +16,31 @@ use strict; ## This software falls under the GNU General Public License. ## ## Please read the COPYING file for more information ## =20 +=3Dhead1 NAME + +kernel-doc - Print formatted kernel documentation to stdout + +=3Dhead1 SYNOPSIS + + kernel-doc [-h] [-v] [-Werror] + [ -man | + -rst [-sphinx-version VERSION] [-enable-lineno] | + -none + ] + [ + -export | + -internal | + [-function NAME] ... | + [-nosymbol NAME] ... + ] + [-no-doc-sections] + [-export-file FILE] ... + FILE ... + +Run `kernel-doc -h` for details. + +=3Dcut + # 18/01/2001 - Cleanups # Functions prototyped as foo(void) same as foo() # Stop eval'ing where we don't need to. --=20 2.30.2 From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 71C7BC4332F for ; Fri, 18 Feb 2022 18:16:53 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239084AbiBRSRI (ORCPT ); Fri, 18 Feb 2022 13:17:08 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53382 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239057AbiBRSRB (ORCPT ); Fri, 18 Feb 2022 13:17:01 -0500 Received: from mail-wm1-x333.google.com (mail-wm1-x333.google.com [IPv6:2a00:1450:4864:20::333]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 233BAB2B; Fri, 18 Feb 2022 10:16:43 -0800 (PST) Received: by mail-wm1-x333.google.com with SMTP id l67-20020a1c2546000000b00353951c3f62so7000966wml.5; Fri, 18 Feb 2022 10:16:43 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=00cL4DnAgoaxV5Rvy8O7BsAp8kCiEs+BRzzZKLubkW4=; b=LihUMr/bfgZB1Kg75rq3aoIlBe1TN6lpW6pMJxsfVHUsAP2YCIcd6kcepAN2NmuJ/U mbVJhtgzKfT+lRFkulVV9Hbx+rAd7x6J7/TRxEczktniInTLNy/T1dAewsWVXR3TBI9C +qz083AKJRMCzZA/dEinS6LhPCWuwFURSODMg9v0CphGfMZ6Qh9mJ+pA5uncGZMzg3QX X+1Rw550NPI61O53t0W0SK2d5ftsDwWhiBhBc1Cq7xgM4VkPuZjCpWm/Ei8TpyyeeTzt yfQpRRn6goDtgEkDknKhUBijBn3QTgtmmFy/7LUEYgN2hHkoD+J+XuSQtfIStmxDuYY6 /ZDw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=00cL4DnAgoaxV5Rvy8O7BsAp8kCiEs+BRzzZKLubkW4=; b=RFuXE13FUgrhWLKVddR4vSzLkUof5Oaz04hOmEA7Qm3xdHctqGWfNFqFPPL1HCwt3N ifFkNoE+DBzlGkEghvZVXwyAtrCdgbcMk/26iSFjQ+ektEcZucDpQ+mfI0YX1jghfsJi TyuJCJGvIg9rMAPjfrJ0764vDV1DIOu9t24El/UTkLgCOvUjhXeP5mawmupqBNEiBrB/ X0G4ycrWzwwMHzwrZF4pN29LQ3dS2P1DwZ/XIOOl4/cTL9a6eyNEVasVPPjERcRYRfZJ BGHCgupOX0pTXMPeYGmBCI3rNrcR9MQmwmfnnllDLmPDicXae8dv3prCMfbcr7jEDTHA 32Sg== X-Gm-Message-State: AOAM533VszqBUXLLmw6wK88mE0C/ahEVIlS4jkDLlE58AkK+JPxLl9OI xa+crVd1mgac/tlo0jMnqXs= X-Google-Smtp-Source: ABdhPJxpDXyQWtueLGM+MHmeoIlox+QZOBsVKOayEKds+7gqifmctcLzfmr2JZyDvUFIXU86e1QRkw== X-Received: by 2002:a05:600c:4e8a:b0:37d:1bcf:de22 with SMTP id f10-20020a05600c4e8a00b0037d1bcfde22mr11421031wmq.195.1645208201448; Fri, 18 Feb 2022 10:16:41 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:40 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v4 02/11] scripts: kernel-doc: Relink argument parsing error handling to pod2usage Date: Fri, 18 Feb 2022 19:16:19 +0100 Message-Id: <20220218181628.1411551-3-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org The former usage function is substituted, although not as the -h and -help parameter handler yet. Purpose: Use Pod::Usage to handle documentation printing in an integrated way. Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- If the indentation is still wrong, please state, what you expect exactly. To me the style in the script is random or eclectic. --- scripts/kernel-doc | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c8fbf1d3d5aa..e7f7251771bb 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -16,6 +16,8 @@ use strict; ## This software falls under the GNU General Public License. ## ## Please read the COPYING file for more information ## =20 +use Pod::Usage qw/pod2usage/; + =3Dhead1 NAME =20 kernel-doc - Print formatted kernel documentation to stdout @@ -298,7 +300,13 @@ my $blankline_rst =3D "\n"; =20 # read arguments if ($#ARGV =3D=3D -1) { - usage(); + pod2usage( + -message =3D> "No arguments!\n", + -exitval =3D> 1, + -verbose =3D> 99, + -sections =3D> 'SYNOPSIS', + -output =3D> \*STDERR, + ); } =20 my $kernelversion; @@ -518,8 +526,14 @@ while ($ARGV[0] =3D~ m/^--?(.*)/) { die "Sphinx version should either major.minor or major.minor.patch fo= rmat\n"; } } else { - # Unknown argument - usage(); + # Unknown argument + pod2usage( + -message =3D> "Argument unknown!\n", + -exitval =3D> 1, + -verbose =3D> 99, + -sections =3D> 'SYNOPSIS', + -output =3D> \*STDERR, + ); } } =20 --=20 2.30.2 From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 01CF5C43217 for ; Fri, 18 Feb 2022 18:16:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239087AbiBRSRL (ORCPT ); Fri, 18 Feb 2022 13:17:11 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53386 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239060AbiBRSRB (ORCPT ); Fri, 18 Feb 2022 13:17:01 -0500 Received: from mail-wm1-x32b.google.com (mail-wm1-x32b.google.com [IPv6:2a00:1450:4864:20::32b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id CDBDAB32; Fri, 18 Feb 2022 10:16:43 -0800 (PST) Received: by mail-wm1-x32b.google.com with SMTP id k41so5760383wms.0; Fri, 18 Feb 2022 10:16:43 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=u266b+q8DWQtLBDTpUPs6zbs4k5v/SuOwsj80SYD5EU=; b=ECGPAd/MXong9ZMK6CthGlD/mwjV0pnvoJtpEpiCc62rkwpDSrOpx1GUby6lwJSHVl 76PVZxx2vYsNlNB31+wvj0UFXYCX5wA84bD1NSqEhOtobs4T8/sPI+wNZsI+B+udLXBq nwxUfcEYrI5vI0QC02cb661WZCO5jtIwNnw6wdnWNwclrnH8Wkw8n2xCYWkhzU5+9i8M glU7Ia4owIClKHovN/kZcvDEh/SP7nbAYIjLvmJ37YOwGLGNdggqUY+67GLdpd+kZe2f XUhJ7xmwqAa3RgraoTLAv1UH07mvcT6IkMfQDb71gZ5Gc7mImOwRABl2aWd96+sZYyd4 5tpg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=u266b+q8DWQtLBDTpUPs6zbs4k5v/SuOwsj80SYD5EU=; b=1ZkykU3VmluatwkhPiED0CP9Cfuj8sHXlSaHEllA/jTA5Ufho+xMk/UH8SdWCzDaJn iw8wPyJayF/5u5A33D30U2ikgPJdl7+HQBrfirgjbfApUjKRA+Wutm+AXW6Svz8htqMO wB1HdFBMUgNJiXBJE4g4IcuAwzPolZ1Cg0WNREuMXS31ehXwwwDBEtAgRmKJdNoj9BkN T9H8jr6VtZdndhzNLJpSP4UlfOW8e+zob2qE+S5OmX98w40gYMACOtmdvsXWrNNqQZ2L 3g39gp5HKZ7QoAj2qy8/r9fhArGHMOmUEmY4Fe2oDIEjCtfKnGKUKuSm9kCUSnyWUwhR WELw== X-Gm-Message-State: AOAM531bIct8Y5MwRb8N5o0bd/OrfJkegyZe6oSTNVKTffzdm1Ia+D9V aC6N5uZX8L3cquYciXOhsQVtNelOvD14vQ== X-Google-Smtp-Source: ABdhPJza6kIMlScBd7xSsCHIq78rTSq6V+kxh5jEIVdDyw0gZXyjitJN+lsYm31OTdkozWNjaLFkzw== X-Received: by 2002:a05:600c:3491:b0:37b:d710:f565 with SMTP id a17-20020a05600c349100b0037bd710f565mr11943366wmq.10.1645208202430; Fri, 18 Feb 2022 10:16:42 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:42 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v4 03/11] scripts: kernel-doc: Translate the DESCRIPTION section Date: Fri, 18 Feb 2022 19:16:20 +0100 Message-Id: <20220218181628.1411551-4-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Transition the description section into POD. This is one of the standard documentation sections. This adjustment makes the section available for POD and makes it look better. Notes: - an article addition - paragraphing correction Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- scripts/kernel-doc | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e7f7251771bb..e4203f13fa93 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -41,6 +41,15 @@ kernel-doc - Print formatted kernel documentation to std= out =20 Run `kernel-doc -h` for details. =20 +=3Dhead1 DESCRIPTION + +Read C language source or header FILEs, extract embedded documentation com= ments, +and print formatted documentation to standard output. + +The documentation comments are identified by the "/**" opening comment mar= k. + +See Documentation/doc-guide/kernel-doc.rst for the documentation comment s= yntax. + =3Dcut =20 # 18/01/2001 - Cleanups @@ -72,12 +81,6 @@ sub usage { my $message =3D <<"EOF"; Usage: $0 [OPTION ...] FILE ... =20 -Read C language source or header FILEs, extract embedded documentation com= ments, -and print formatted documentation to standard output. - -The documentation comments are identified by "/**" opening comment mark. S= ee -Documentation/doc-guide/kernel-doc.rst for the documentation comment synta= x. - Output format selection (mutually exclusive): -man Output troff manual page format. This is the default. -rst Output reStructuredText format. --=20 2.30.2 From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 50FF3C4332F for ; Fri, 18 Feb 2022 18:17:05 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S238510AbiBRSRT (ORCPT ); Fri, 18 Feb 2022 13:17:19 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53456 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239066AbiBRSRC (ORCPT ); Fri, 18 Feb 2022 13:17:02 -0500 Received: from mail-wr1-x42c.google.com (mail-wr1-x42c.google.com [IPv6:2a00:1450:4864:20::42c]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 1CDC4E46; Fri, 18 Feb 2022 10:16:45 -0800 (PST) Received: by mail-wr1-x42c.google.com with SMTP id x5so11077970wrg.13; Fri, 18 Feb 2022 10:16:44 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=4uog9y8e2uGEDe7ul64TEQZKDjtI1qlVaFMwkdOVDqo=; b=BcRgIjpCjdKsmD1hifDCxyFo7H8M+pelERGXldq/KXqEHk6EkcL0zFiu1G2aBagFdw Ycm5NTRmPepuel/RcIcGgKLiU63n4TeV+wyDXRQ74M4FfpY9yra8PkRUVI48MD9yG7X6 LEsAaWL5q0YdJq3jali0uTa0KMBZOxnI4jQ0urGcoSyxmBiv1rsDzRtPxxxklKpUyb5r 6z2rnXkWYoN+Lq2hCHKajRhJNEvXBF0jL8vhdiFU+GuxEe07eDxUGJB/iZCbZtRv9xPD VxRiKf2hf3QCBy1JgYQi+77olsvbVEeYpN76PCxKMuPZsDn552gH3dfHts44S+phhn0Z 0BtQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=4uog9y8e2uGEDe7ul64TEQZKDjtI1qlVaFMwkdOVDqo=; b=qEWj5OruEeRwzOxjV3rWIeBfi7mCh6EC0UTc4Tk5UnLy4i8VaE7bHpbHTBWOqplZCj jnbk8Qgc2GiZ7ApgbKbDIrK33h6o+jg+16/2cLmLq9fXlUJn31v1PQwP5qp7PGcp8lWO HuQF6EJ/46I0OgdTwaMFTpTVFJvungvzmgLSy1LQsaX7UOrkNzr2fN6W2C1djleJQ5zf 8D1vBZseh3RlHCoIpEcAk8v18RcmeHsZ7ND6wM8oBchtq+F/8r7JC2ROGUqcT2fhM5U6 0YsK44OZ3UhsUqLEgPl4kK7kUsi3gmNO494QDvdxMCOM+qqU2aOz5+hYg5wKmHOW1Spg ZRcg== X-Gm-Message-State: AOAM531b1vjpGhxhEjY9B/txsPrETQAZ1VYQbdLiM47q5Ako3jApNnI6 8Gktm/b8NYa7z0dv+FXn91M= X-Google-Smtp-Source: ABdhPJwoGAqCnTbH6+8pCXavYOeKOon6tieBJ1Aoa51OqKaHWYhCdLMszt/uM6Vdcl8otOgbgFTMUQ== X-Received: by 2002:a05:6000:144c:b0:1e8:50e5:fec1 with SMTP id v12-20020a056000144c00b001e850e5fec1mr7113263wrx.648.1645208203688; Fri, 18 Feb 2022 10:16:43 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:43 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v4 04/11] scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS Date: Fri, 18 Feb 2022 19:16:21 +0100 Message-Id: <20220218181628.1411551-5-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Another step in the direction of a uniform POD documentation, which will make users happier. Options land at the end of the script, not to clutter the file top. The default output format is corrected to rst. That's what it is now. A POD delimiting comment is added to the script head, which improves the script logical structure. Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- scripts/kernel-doc | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e4203f13fa93..18eca172c4b5 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -52,6 +52,8 @@ See Documentation/doc-guide/kernel-doc.rst for the docume= ntation comment syntax. =20 =3Dcut =20 +# more perldoc at the end of the file + # 18/01/2001 - Cleanups # Functions prototyped as foo(void) same as foo() # Stop eval'ing where we don't need to. @@ -81,11 +83,6 @@ sub usage { my $message =3D <<"EOF"; Usage: $0 [OPTION ...] FILE ... =20 -Output format selection (mutually exclusive): - -man Output troff manual page format. This is the default. - -rst Output reStructuredText format. - -none Do not output documentation, only warnings. - Output format selection modifier (affects only ReST output): =20 -sphinx-version Use the ReST C domain dialect compatible with an @@ -2563,3 +2560,27 @@ if ($Werror && $warnings) { } else { exit($output_mode eq "none" ? 0 : $errors) } + +__END__ + +=3Dhead1 OPTIONS + +=3Dhead2 Output format selection (mutually exclusive): + +=3Dover 8 + +=3Ditem -man + +Output troff manual page format. + +=3Ditem -rst + +Output reStructuredText format. This is the default. + +=3Ditem -none + +Do not output documentation, only warnings. + +=3Dback + +=3Dcut --=20 2.30.2 From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1CA66C433F5 for ; Fri, 18 Feb 2022 18:16:59 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239119AbiBRSRN (ORCPT ); Fri, 18 Feb 2022 13:17:13 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53568 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239074AbiBRSRE (ORCPT ); Fri, 18 Feb 2022 13:17:04 -0500 Received: from mail-wr1-x429.google.com (mail-wr1-x429.google.com [IPv6:2a00:1450:4864:20::429]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C16E42655; Fri, 18 Feb 2022 10:16:46 -0800 (PST) Received: by mail-wr1-x429.google.com with SMTP id h6so15903724wrb.9; Fri, 18 Feb 2022 10:16:46 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=sVpw/YkSpECxioHiJcwwjO5cIgkz+JQrp0Z1102tsjs=; b=WMEnfHw96wCX1wphCv5/NoHdkP+bH/Booqpf2gva3Qsnq1R2UY6qm8wGmfuwDem2se aeJSSeQe2dShQ4tJVADNkDfDAy7ySS3vbdeh0KgNLfZBiiB4Y8frX8tuRMEfltB69i/M sl6YxSABSWDm9MSXmAai7ccUigRl4mDbU2ODjAaRGk6Gl49Zr12BNmWxKULtOIkISX1E OAv8qKYoOCZ74TEetkUTK5IUOK0vNoUZOyyt4+dAzJxuZE/64ekRG2rXa0eMwOwJ1wH+ MMoXac89ZygyNDk0YpAy82ABrk/fGmUBWQlzUWFy2DIZZxgmqScawfILyB2ir+X+5KIu KqTA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=sVpw/YkSpECxioHiJcwwjO5cIgkz+JQrp0Z1102tsjs=; b=Thpbq+l5u4RxP98XhtjvN1q7c+lPGIfbwQ26/lHVJGCULc5sXCf8J9cAuUSyJ1kO6n sjJ/rmyrKWPrOT0Dn39+ni4Mnk1jFX7i+TgGeJIhxK87Q7yEUS405T37QVXwP1mL8l7C g12uWEPiSa0XBGpvRzRyCtcbzRYAlfCco98hg8NFtxKCDN7mE51uQXsYZwWgu6blIVen wHFP57KCjnFwa9pfliLJ0JBWa/K2c/k4IQeyq8c0NtPu54h4FTIDbVeeGNbyJojteCoQ 6HxyL/dsnfhHwurCp0Zg+qOL/4fwIgiCqKKqJXj+XR9xOMNyj/YUpYMW/eLEIDH5eW9W WTFg== X-Gm-Message-State: AOAM530Y9ljiH0l35wt8W0c4r57LmsKguDJ6K0fDRNG9Gx4dXohR39+2 844MxTQMmZ0ijnrLnqYviLVRJBAQKtiLbA== X-Google-Smtp-Source: ABdhPJws4VKz76/Rj4ocyZfLWDIEslDjzDyROQuhjJG1xPu9xGMlfPjmNX7CdHYFHno8/clRALSaHw== X-Received: by 2002:a5d:6309:0:b0:1e4:9a62:d46f with SMTP id i9-20020a5d6309000000b001e49a62d46fmr6651438wru.50.1645208205059; Fri, 18 Feb 2022 10:16:45 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:44 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v4 05/11] scripts: kernel-doc: Translate the "Output format selection modifier" subsection of OPTIONS Date: Fri, 18 Feb 2022 19:16:22 +0100 Message-Id: <20220218181628.1411551-6-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Aim: unified POD, user more happy This section is renamed to "Output format modifiers" to make it simple. To make it even more simple, a subsection is added: "reStructuredText only". Other notes: - paragraphing correction - article correction Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- scripts/kernel-doc | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 18eca172c4b5..b926faa16b00 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -83,13 +83,6 @@ sub usage { my $message =3D <<"EOF"; Usage: $0 [OPTION ...] FILE ... =20 -Output format selection modifier (affects only ReST output): - - -sphinx-version Use the ReST C domain dialect compatible with an - specific Sphinx Version. - If not specified, kernel-doc will auto-detect using - the sphinx-build version found on PATH. - Output selection (mutually exclusive): -export Only output documentation for symbols that have been exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() @@ -2583,4 +2576,19 @@ Do not output documentation, only warnings. =20 =3Dback =20 +=3Dhead2 Output format modifiers + +=3Dhead3 reStructuredText only + +=3Dover 8 + +=3Ditem -sphinx-version VERSION + +Use the ReST C domain dialect compatible with a specific Sphinx Version. + +If not specified, kernel-doc will auto-detect using the sphinx-build versi= on +found on PATH. + +=3Dback + =3Dcut --=20 2.30.2 From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 54D14C433EF for ; Fri, 18 Feb 2022 18:17:01 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S237237AbiBRSRQ (ORCPT ); Fri, 18 Feb 2022 13:17:16 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53566 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239075AbiBRSRE (ORCPT ); Fri, 18 Feb 2022 13:17:04 -0500 Received: from mail-wr1-x434.google.com (mail-wr1-x434.google.com [IPv6:2a00:1450:4864:20::434]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9BF2612A85; Fri, 18 Feb 2022 10:16:47 -0800 (PST) Received: by mail-wr1-x434.google.com with SMTP id d27so15932267wrc.6; Fri, 18 Feb 2022 10:16:47 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=wo5NvcwHFFtStXDoiS+t0v8LcaxRXSvFfszKiww2PfQ=; b=GfWkT0p66agfM59hEUjlXkfOQ9Whc+0BMoWQBJHgcPyWAzecHSbFDTEedwgPtZulln n3tQyPqiTJL7jZBrR5e+QjRyP5v1txZ9H7ZYeI7C9k0CFzrZK0vyR7Ke5AAMUydQBmBm d+v3PuHISGVVzWfI8dd4KAbZu660+WQ+M9MocgWUchazcf2C+a47A9XFNKVn7FDNnRra buctkZkCDHeBIsva7fyXRD+vSeOzBkbB12yaDfzFeHDICuWD48LTXUuvQwipNTQNyjkR 8MUR5DNXXeFDLFZvaO5CmFhs8mK+DO0x5cX+T96M4Q94qW3CpgTzGZ8x6/Gax1wL35JU JyCg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=wo5NvcwHFFtStXDoiS+t0v8LcaxRXSvFfszKiww2PfQ=; b=r7N5j9x4BA/WwUCWucNOvPqeuGfGXpmKr3mhbOy2lxyCtV6wmFhQYSJEfiMnDFbape R84iSMU9xtSwlo5wiWq74Qqfn5uFKw5RHkHwZRSvRK2/RBR/OlLB0KEoWAVvav3dq1uh Yw8Tlu9Qho21CGuNOljmWG5e81SjB2OLBl4n1+YhOsLBDt1+d4znmi/xUeDy0OE6bdwJ U1K89G4LXOXfopjJGW7bQZKZYOdspwJrYexWzTHY1PWDmUdIilfJGkclDu5/odL0a1Fc WJKWfS2EaJf39N6TmMS0BG9tQwGBMPygus8K9vPZzgTxBRapVn8TWKpixSoEuxsrMLvN xITw== X-Gm-Message-State: AOAM533fDSPeXWjAGz/kiigsgM90uwzORZakYPVBkYd/QfQbD332PO1z OIaN48PTIc1m5qrUdk/399SRgErOyL7Efg== X-Google-Smtp-Source: ABdhPJyvtVQCat2Gzd6TH1LkB71Yv/+tQBWH7sJ6gcZtJJ/rLkoMyyvOTZPTpogGcmYApiITz7VlXA== X-Received: by 2002:a05:6000:c5:b0:1e3:2a0d:fe6 with SMTP id q5-20020a05600000c500b001e32a0d0fe6mr7009551wrx.421.1645208205886; Fri, 18 Feb 2022 10:16:45 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:45 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v4 06/11] scripts: kernel-doc: Translate the "Output selection" subsection of OPTIONS Date: Fri, 18 Feb 2022 19:16:23 +0100 Message-Id: <20220218181628.1411551-7-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Aim: unified POD, user more satisfied, script better structured The plurals in -function and -nosymbol are corrected to singulars. That's how the script works now. I think this describes the syntax better. The plurar suggests multiple FILE arguments might be possible. So this seems more coherent. Other notes: - paragraphing correction - article correction Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- scripts/kernel-doc | 42 +++++++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 13 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index b926faa16b00..e49cdb307a35 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -83,19 +83,6 @@ sub usage { my $message =3D <<"EOF"; Usage: $0 [OPTION ...] FILE ... =20 -Output selection (mutually exclusive): - -export Only output documentation for symbols that have been - exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() - in any input FILE or -export-file FILE. - -internal Only output documentation for symbols that have NOT been - exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() - in any input FILE or -export-file FILE. - -function NAME Only output documentation for the given function(s) - or DOC: section title(s). All other functions and DOC: - sections are ignored. May be specified multiple times. - -nosymbol NAME Exclude the specified symbols from the output - documentation. May be specified multiple times. - Output selection modifiers: -no-doc-sections Do not output DOC: sections. -enable-lineno Enable output of #define LINENO lines. Only works = with @@ -2591,4 +2578,33 @@ found on PATH. =20 =3Dback =20 +=3Dhead2 Output selection (mutually exclusive): + +=3Dover 8 + +=3Ditem -export + +Only output documentation for the symbols that have been exported using +EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file F= ILE. + +=3Ditem -internal + +Only output documentation for the symbols that have NOT been exported using +EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file F= ILE. + +=3Ditem -function NAME + +Only output documentation for the given function or DOC: section title. +All other functions and DOC: sections are ignored. + +May be specified multiple times. + +=3Ditem -nosymbol NAME + +Exclude the specified symbol from the output documentation. + +May be specified multiple times. + +=3Dback + =3Dcut --=20 2.30.2 From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 77DA8C433EF for ; Fri, 18 Feb 2022 18:17:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235173AbiBRSR2 (ORCPT ); Fri, 18 Feb 2022 13:17:28 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53640 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239079AbiBRSRG (ORCPT ); Fri, 18 Feb 2022 13:17:06 -0500 Received: from mail-wr1-x42a.google.com (mail-wr1-x42a.google.com [IPv6:2a00:1450:4864:20::42a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D0BB7B32; Fri, 18 Feb 2022 10:16:48 -0800 (PST) Received: by mail-wr1-x42a.google.com with SMTP id d27so15932334wrc.6; Fri, 18 Feb 2022 10:16:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=1rWH/BsccXg4cqTVnl88SeuUMSVFDqYiKoq6y7EUDcA=; b=pIq7/7L5LAbPU+GGcDbqzcRpe2RdjLEYz/ApzoAOpU6QIibs0WAHiCmv41nmjZhL5S mQZ2HCEIG6SvhLLB7IfJpsWIjDAe40svARasskZnxMpTkkDGUauSyy+tcSLD7AESPTW4 JjBVCXoHf/9qi/6P8rXvY3NdCg/EBgI/NMJWl8H7/Ti0XRFbW8Cfqs+eyLCh86r4JEEo 2TIhpF1BjWoysZVgH2ziKkcu1mY8Wpn+Mv3ohBooipI96vcyggHlqDjLZ+a/J7taMgif 5RzlamyetYosnHCVhK1wgprKAlr2Vv3Jtez8vEZhSBFKN0gRIBMyTkGq6/agcpGUO2lU hFvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=1rWH/BsccXg4cqTVnl88SeuUMSVFDqYiKoq6y7EUDcA=; b=R3YBam8QwIuY88jD50Vx5n7/NvAihqCogCYSnoZ78jVCB+XubMVeCOotn3Pf3sBhDb vl3INhEHVldHSm1CCUdJZwaEZJCtWFGLRnMnLRHX+IIjJ/R6Eh1eYeAyvIgX/4cYShmX k1ab1dmrJJUmj59gz3vBWkhjgEms4BjQyca7iBzwnatqD/zavqDk8u7ctBJbfDmY0/jK aiv+2ZT6iGCzqNTK0TvtTlY01qGhn6FfvkiU1s/3boRCJzTNjlQ0WFpH6UXFTUR3tRVH btLGOGx7goak0+FwA7ON+I9J+rx48fIaqXD8FBTmybLUHGS/V3lbiW6BPTjTyOJ4ZMDX QmXA== X-Gm-Message-State: AOAM533HdCEtVfnKhxXZGX/xJiRJsOaJ5qZ+yXZY/StMmL5KYkH1EIJN 3q3MbD6lp3tWzlbXwFwcFHA= X-Google-Smtp-Source: ABdhPJy4XiLWgnAAaFNYDRnx8H+L9AOS8cpRcg3UDdflougEBjxkv7xtTrSwDa92rYFTkBwfZowVIg== X-Received: by 2002:a5d:44c4:0:b0:1e6:8878:8cb2 with SMTP id z4-20020a5d44c4000000b001e688788cb2mr7021889wrr.434.1645208206841; Fri, 18 Feb 2022 10:16:46 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:46 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v4 07/11] scripts: kernel-doc: Translate the "Output selection modifiers" subsection of OPTIONS Date: Fri, 18 Feb 2022 19:16:24 +0100 Message-Id: <20220218181628.1411551-8-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Aim: unified POD, user more satisfied, script better structured A subsection "reStructuredText only" is added for -enable-lineno. Other notes: - paragraphing correction Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- scripts/kernel-doc | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e49cdb307a35..210e7e3b501b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -83,14 +83,6 @@ sub usage { my $message =3D <<"EOF"; Usage: $0 [OPTION ...] FILE ... =20 -Output selection modifiers: - -no-doc-sections Do not output DOC: sections. - -enable-lineno Enable output of #define LINENO lines. Only works = with - reStructuredText format. - -export-file FILE Specify an additional FILE in which to look for - EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be use= d with - -export or -internal. May be specified multiple ti= mes. - Other parameters: -v Verbose output, more warnings and other information. -h Print this help. @@ -2607,4 +2599,33 @@ May be specified multiple times. =20 =3Dback =20 +=3Dhead2 Output selection modifiers: + +=3Dover 8 + +=3Ditem -no-doc-sections + +Do not output DOC: sections. + +=3Ditem -export-file FILE + +Specify an additional FILE in which to look for EXPORT_SYMBOL() and +EXPORT_SYMBOL_GPL(). + +To be used with -export or -internal. + +May be specified multiple times. + +=3Dback + +=3Dhead3 reStructuredText only + +=3Dover 8 + +=3Ditem -enable-lineno + +Enable output of #define LINENO lines. + +=3Dback + =3Dcut --=20 2.30.2 From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id B9B25C433FE for ; Fri, 18 Feb 2022 18:17:09 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239130AbiBRSRY (ORCPT ); Fri, 18 Feb 2022 13:17:24 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53642 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239080AbiBRSRG (ORCPT ); Fri, 18 Feb 2022 13:17:06 -0500 Received: from mail-wr1-x42c.google.com (mail-wr1-x42c.google.com [IPv6:2a00:1450:4864:20::42c]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 51F3FBA5; Fri, 18 Feb 2022 10:16:49 -0800 (PST) Received: by mail-wr1-x42c.google.com with SMTP id e3so16005223wra.0; Fri, 18 Feb 2022 10:16:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=2lb5EpDrjZ7Ucka1D9DCg1WHob0SHwbW9oEXk90RPrs=; b=WS3QZY6M3UB9909PRkjQxHh3MFAbnv5w63hkV438NIYYd84kFghIWSJErVXRGpgY0e VA9gO3pQHfB3JAgF4hwCGe+jI3x8Cg5SFDmg2hxcw1AkWq+C7+g0rovX3YNrqw7Pb39Y fAhcCLHtVPZNe+G8/v2s82g/qP48s6gIz76tD3ouu4DBh1qTDVMqQ7AZ3LH745yG8lzq +N2P0x7dE4eTabpuiBSICqwZ+Ppzm7keyoBtfgcKt6q3nhRCRD+ntfQB3EWD/uWWpqA6 fng7F/+TtGEivESLN0mw35wwju7YqME3CeNDV+Bn+JE2b6MYu6SDYXmo+fFRYw850W2U MVZw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=2lb5EpDrjZ7Ucka1D9DCg1WHob0SHwbW9oEXk90RPrs=; b=vN2P1SQPDZCr/ctIY8xl8kxdr+z7HGQxUSudFg6P2ZEWsOMLKma2AI3cyhIfDperHp OQR2M/7+v/Lw19uhcci6EXS3YDlPc3a5uKfwxrEsuMAte3er/jJG8PrOPH0MPJMYEe04 f67wYWszp28BAdi/4tCRzRMmchbmckP6kPva+x8xhzBuZaRV95+Oiie38wByeI1Os9qA wA/Lz54ZTRhxLbDNRDTNO8BJkaY1FHWGtFSOB/6Rkqn/yH94TCXypK7pFKrOFi+9iijl MMVl6Qhgi1lRTyA8xTL29FOtyLiW2ypCt3eanGBCnxo0WW+4y7LXQvIxhuuUPjRn7oWH zXRA== X-Gm-Message-State: AOAM5321gwA+P7FdeKr55H9Z7AwoVOhvsDdr4BdmLZJwIueQ32ibgLtN po7c2oBQpx4pk23fRINC6sY= X-Google-Smtp-Source: ABdhPJwlQXbzR3MwBSz9x39dlEhRav6nu/HafcNw9vr9feXS38Bl6Inn00TaH4YdXR9hbOsIhWbFgA== X-Received: by 2002:a5d:6244:0:b0:1e7:686d:41e7 with SMTP id m4-20020a5d6244000000b001e7686d41e7mr6785305wrv.491.1645208207924; Fri, 18 Feb 2022 10:16:47 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:47 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v4 08/11] scripts: kernel-doc: Translate the "Other parameters" subsection of OPTIONS Date: Fri, 18 Feb 2022 19:16:25 +0100 Message-Id: <20220218181628.1411551-9-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Aim: unified POD, user more satisfied, script better structured Notes: - The -help token is added. - The entries are sorted alphbetically. Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- scripts/kernel-doc | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 210e7e3b501b..4a26a74318e6 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -83,11 +83,6 @@ sub usage { my $message =3D <<"EOF"; Usage: $0 [OPTION ...] FILE ... =20 -Other parameters: - -v Verbose output, more warnings and other information. - -h Print this help. - -Werror Treat warnings as errors. - EOF print $message; exit 1; @@ -2628,4 +2623,22 @@ Enable output of #define LINENO lines. =20 =3Dback =20 +=3Dhead2 Other parameters: + +=3Dover 8 + +=3Ditem -h, -help + +Print this help. + +=3Ditem -v + +Verbose output, more warnings and other information. + +=3Ditem -Werror + +Treat warnings as errors. + +=3Dback + =3Dcut --=20 2.30.2 From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 414A6C433F5 for ; Fri, 18 Feb 2022 18:17:18 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239151AbiBRSRd (ORCPT ); Fri, 18 Feb 2022 13:17:33 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53850 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239092AbiBRSRJ (ORCPT ); Fri, 18 Feb 2022 13:17:09 -0500 Received: from mail-wr1-x42f.google.com (mail-wr1-x42f.google.com [IPv6:2a00:1450:4864:20::42f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6DB8A1A387; Fri, 18 Feb 2022 10:16:50 -0800 (PST) Received: by mail-wr1-x42f.google.com with SMTP id u1so15904592wrg.11; Fri, 18 Feb 2022 10:16:50 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=BKVwInCpVkxcu4QibmqUE+njZypLWjFf62FZiJ7RfDY=; b=idcfe+gYBoodhi/dxSiO7KNkyG85wSPk/fEcAhTr842WEIMqs266rypz/qc0pY0r7w gxvoTs5LE/DJ7w9tMOGgkba5oGTh6brZA4KLOiXKGllY3kC2mX3U0MWhLYBnwY4TkftW i2XKR8WC/vJjhZGSh9KYTOzIueFLw5SZZfv433Kkz6Owx+nQPCfrXF2VoHQMm57ZOKRJ txYAzMcrkanYrZvUWhFYrBJCQDKhM8gBZSrYNBWCA8ARvfX2jsPDnxayJzrAjFtOaxvf gmVmdtS6ILnDiPjHg2vH2XfUWEhBpoAPAzP+XgqCXnrxIHlT8B+Ay44dfhsXggSq1/uN 7OuQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=BKVwInCpVkxcu4QibmqUE+njZypLWjFf62FZiJ7RfDY=; b=whF1xSq0/nGLQlhZGr5DX2ZNGnDPc3Njh5lZ+hGkDyBpUvca4+Y1Pfgqft1W24R/28 +Vnz7EgT+b6wTGyU6TkGPDPkG+lqwQUh5sOymb0NxkQpy7OsOgJOibbFcVRiZrnOpx4i wZ1OG8XayOCbXkoA0d0wDfYN4pFHTZEbEv93XsPI4KbfFkm8eSHZqxG3uWqT3r/YjeZz nYcHbrB5ghb7gXkdeouGUe8yixWAvty84Lrz3JSZBe8I136jaCRkPk5FpnUM1TUarEaD A2QUylpMj1/F+UFrNSoX7tsaFyG8I3B/6DRl+6ywxAZnQWZpTQD27l9fhr/R7Z6eNXzO XpEg== X-Gm-Message-State: AOAM533SyqLG0KPis+9sTztMQGWswMFYveUXhsD1e5HI0x6YdQpXiZWI /G0y7NUWlJd90Yzqfb+FFrg= X-Google-Smtp-Source: ABdhPJwc1hqz5DkZxJCKnWZoWDp85ZWAwbozBuikgb2fXWlk2vNfr0PYY7Kw/ghPB9JEZnrI+7J2xQ== X-Received: by 2002:a05:6000:c9:b0:1e4:bcc1:f806 with SMTP id q9-20020a05600000c900b001e4bcc1f806mr6966527wrx.372.1645208209067; Fri, 18 Feb 2022 10:16:49 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:48 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v4 09/11] scripts: kernel-doc: Replace the usage function Date: Fri, 18 Feb 2022 19:16:26 +0100 Message-Id: <20220218181628.1411551-10-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Aim: unified POD, user more satisfied, script better structured You can see the results with: $ scripts/kernel-doc -help Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- This ends the fundamental POD transformation. --- scripts/kernel-doc | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4a26a74318e6..d7ca4877eeda 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -79,15 +79,6 @@ See Documentation/doc-guide/kernel-doc.rst for the docum= entation comment syntax. # 25/07/2012 - Added support for HTML5 # -- Dan Luedtke =20 -sub usage { - my $message =3D <<"EOF"; -Usage: $0 [OPTION ...] FILE ... - -EOF - print $message; - exit 1; -} - # # format of comments. # In the following table, (...)? signifies optional structure. @@ -468,7 +459,7 @@ while ($ARGV[0] =3D~ m/^--?(.*)/) { } elsif ($cmd eq "Werror") { $Werror =3D 1; } elsif (($cmd eq "h") || ($cmd eq "help")) { - usage(); + pod2usage(-exitval =3D> 0, -verbose =3D> 2); } elsif ($cmd eq 'no-doc-sections') { $no_doc_sections =3D 1; } elsif ($cmd eq 'enable-lineno') { --=20 2.30.2 From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 71266C433EF for ; Fri, 18 Feb 2022 18:17:22 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239177AbiBRSRh (ORCPT ); Fri, 18 Feb 2022 13:17:37 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53848 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239078AbiBRSRK (ORCPT ); Fri, 18 Feb 2022 13:17:10 -0500 Received: from mail-wr1-x42b.google.com (mail-wr1-x42b.google.com [IPv6:2a00:1450:4864:20::42b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0C25C2BB09; Fri, 18 Feb 2022 10:16:52 -0800 (PST) Received: by mail-wr1-x42b.google.com with SMTP id p9so15893589wra.12; Fri, 18 Feb 2022 10:16:51 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Zy0x5Exl42nPFRLYIWGzellcEZxdd2iOka5tuDBPYC8=; b=cyjXjfe3ONdltPjRdTnXzyxbcybIdQNRtyvVzBCT6kdlJHlLJ1HOp9B7tE3KqdiGG1 DL54NEkkZeZZXX6HHRkqsmLlDobihm91Ff5NLnEe8J2bxpPW3IK7JVZ3BqKWlJ9moC9N kVp3jMKfnwCwYTUqrx0ZaSRcX9EefehtWyGV14W+oe6DArFmFgRO8SoSyysCZtxf1/cM iHDY3t+07hkIMZEh/vpvynSgIwKuOh6zxb4jj/FwL1V5VnBbh0p1w413RKKyFwblbjwf +lABf2GRLwK8Cxvv44uSXEfYjhk+/bqgTakwg+yPSaizb7TSjCgqJKq5SNwWT9EbFg9m ViIQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Zy0x5Exl42nPFRLYIWGzellcEZxdd2iOka5tuDBPYC8=; b=d7mLPPJ0k8RiS6v9u2vxeSxKu/GMbRG1sESBOmvr0QkRU3uoUSOTeVmeFZiAj5eUVT hGV6H/TqxQ/QuFkWg9YhIKZX8hXxcaO1gQXLqF3e6RCicjbT/Jz7THOMMsoIaDSdd+EF CHhmvJTingRx4ygjN4RVwUP34KHewbPFKsK/PaF5+gQanFKjtJ/CzvM0kP3wuOIBdpzG PNKBv9up1tiEMnHqwt7mMnBKmojTmoYfnZ/RV5aXLMyZ6EXskJFreim13y5k9KLLQpib PTcjfrLMBcVTxSeHUlVsqBN9NUSEgvIOyMY+D2lKJRFZnSV0K7vtJmlN/Hem3O1/cg0G gzBw== X-Gm-Message-State: AOAM530aHMcm+ckv2gM4O8ewzTenarbWlzwkQIV2GiAGhkHxd6m8fYmG uj+r5gCmiJ3J7zEsDbUsX+E= X-Google-Smtp-Source: ABdhPJzpovEpj7/M1EHMrOkky5VoS8NsJiOXMRA/hm047XIGVhy+R7UCEnZAe3QNt9GU/1U/M9t87g== X-Received: by 2002:a5d:64cc:0:b0:1e8:f4ad:bf85 with SMTP id f12-20020a5d64cc000000b001e8f4adbf85mr5953050wri.630.1645208210622; Fri, 18 Feb 2022 10:16:50 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:50 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Jani Nikula Subject: [PATCH v4 10/11] scripts: kernel-doc: Drop obsolete comments Date: Fri, 18 Feb 2022 19:16:27 +0100 Message-Id: <20220218181628.1411551-11-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org What for? To improve the script maintainability. 1. License As stated by Jonathan Corbet in the reply to my version 1, the SPDX line is enough. 2. The to-do list comment As suggested by Jonathan Corbet in reply to my version 3, this section doesn't need to be transitioned. And so it is removed for clarity. 3. The historical changelog comments As suggested by Jonathan Corbet in a reply to v3, this section can go. I wanted to keep it, but since it doesn't contain copyright notices, let's just have it clean and simple. 4. The "format of comments" comment block As suggested by Jani Nikula in a reply to my first version of this transformation, Documentation/doc-guide/kernel-doc.rst can serve as the information hub for comment formatting. The section DESCRIPTION already points there, so the original comment block can just be removed. Suggested-by: Jonathan Corbet Suggested-by: Jani Nikula Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- scripts/kernel-doc | 143 --------------------------------------------- 1 file changed, 143 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index d7ca4877eeda..a5a397e22ea7 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -12,9 +12,6 @@ use strict; ## ## ## #define enhancements by Armin Kuster ## ## Copyright (c) 2000 MontaVista Software, Inc. ## -## ## -## This software falls under the GNU General Public License. ## -## Please read the COPYING file for more information ## =20 use Pod::Usage qw/pod2usage/; =20 @@ -54,146 +51,6 @@ See Documentation/doc-guide/kernel-doc.rst for the docu= mentation comment syntax. =20 # more perldoc at the end of the file =20 -# 18/01/2001 - Cleanups -# Functions prototyped as foo(void) same as foo() -# Stop eval'ing where we don't need to. -# -- huggie@earth.li - -# 27/06/2001 - Allowed whitespace after initial "/**" and -# allowed comments before function declarations. -# -- Christian Kreibich - -# Still to do: -# - add perldoc documentation -# - Look more closely at some of the scarier bits :) - -# 26/05/2001 - Support for separate source and object trees. -# Return error code. -# Keith Owens - -# 23/09/2001 - Added support for typedefs, structs, enums and unions -# Support for Context section; can be terminated using empty = line -# Small fixes (like spaces vs. \s in regex) -# -- Tim Jansen - -# 25/07/2012 - Added support for HTML5 -# -- Dan Luedtke - -# -# format of comments. -# In the following table, (...)? signifies optional structure. -# (...)* signifies 0 or more structure elements -# /** -# * function_name(:)? (- short description)? -# (* @parameterx: (description of parameter x)?)* -# (* a blank line)? -# * (Description:)? (Description of function)? -# * (section header: (section description)? )* -# (*)?*/ -# -# So .. the trivial example would be: -# -# /** -# * my_function -# */ -# -# If the Description: header tag is omitted, then there must be a blank li= ne -# after the last parameter specification. -# e.g. -# /** -# * my_function - does my stuff -# * @my_arg: its mine damnit -# * -# * Does my stuff explained. -# */ -# -# or, could also use: -# /** -# * my_function - does my stuff -# * @my_arg: its mine damnit -# * Description: Does my stuff explained. -# */ -# etc. -# -# Besides functions you can also write documentation for structs, unions, -# enums and typedefs. Instead of the function name you must write the name -# of the declaration; the struct/union/enum/typedef must always precede -# the name. Nesting of declarations is not supported. -# Use the argument mechanism to document members or constants. -# e.g. -# /** -# * struct my_struct - short description -# * @a: first member -# * @b: second member -# * -# * Longer description -# */ -# struct my_struct { -# int a; -# int b; -# /* private: */ -# int c; -# }; -# -# All descriptions can be multiline, except the short function description. -# -# For really longs structs, you can also describe arguments inside the -# body of the struct. -# eg. -# /** -# * struct my_struct - short description -# * @a: first member -# * @b: second member -# * -# * Longer description -# */ -# struct my_struct { -# int a; -# int b; -# /** -# * @c: This is longer description of C -# * -# * You can use paragraphs to describe arguments -# * using this method. -# */ -# int c; -# }; -# -# This should be use only for struct/enum members. -# -# You can also add additional sections. When documenting kernel functions = you -# should document the "Context:" of the function, e.g. whether the functio= ns -# can be called form interrupts. Unlike other sections you can end it with= an -# empty line. -# A non-void function should have a "Return:" section describing the return -# value(s). -# Example-sections should contain the string EXAMPLE so that they are mark= ed -# appropriately in DocBook. -# -# Example: -# /** -# * user_function - function that can only be called in user context -# * @a: some argument -# * Context: !in_interrupt() -# * -# * Some description -# * Example: -# * user_function(22); -# */ -# ... -# -# -# All descriptive text is further processed, scanning for the following sp= ecial -# patterns, which are highlighted appropriately. -# -# 'funcname()' - function -# '$ENVVAR' - environmental variable -# '&struct_name' - name of a structure (up to two words including 'struct') -# '&struct_name.member' - name of a structure member -# '@parameter' - name of a parameter -# '%CONST' - name of a constant. -# '``LITERAL``' - literal string without any spaces on it. - ## init lots of data =20 my $errors =3D 0; --=20 2.30.2 From nobody Sat Jun 27 21:22:11 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 48AA7C433FE for ; Fri, 18 Feb 2022 18:17:25 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239092AbiBRSRk (ORCPT ); Fri, 18 Feb 2022 13:17:40 -0500 Received: from mxb-00190b01.gslb.pphosted.com ([23.128.96.19]:53972 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239108AbiBRSRK (ORCPT ); Fri, 18 Feb 2022 13:17:10 -0500 Received: from mail-wm1-x32f.google.com (mail-wm1-x32f.google.com [IPv6:2a00:1450:4864:20::32f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7CE0E36301; Fri, 18 Feb 2022 10:16:52 -0800 (PST) Received: by mail-wm1-x32f.google.com with SMTP id w13so5254947wmi.2; Fri, 18 Feb 2022 10:16:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=ETcVMH7Xr0E5efOZr2jk0ulPirFO8VUQbOlOEWLlTGA=; b=OBrG2ryyfhgdHOGpeDi7AoYwrGWdbVPm2RUjXjFLEK6YcFHAhj4u4QIqRqYQhF3UHE DOn53qAOt390Zh3ErdSxCPQIp5aQ+2zKFNyBPmps7fjZIiK3B3IudeYggkG1oW9RyjdT gK8o8Y51H7N8nbTcBHgYGDyNuT0qxx3JKAeqt8Cl7G6CSRPeKjuhzCQpdR/Nan1a+tm3 zufVJsS0Yto5VTIjvLfBc6iESZsiRXgb7U6pSRHO/JtZMv+H1c34bWSNvkq/aWQbO67t H442LAN4xyd6RNOeguRqEv6MjUm1DIeF+v7V0BjsWsw+IfWKKj0L+QIXINbNbvxBHosV /30g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=ETcVMH7Xr0E5efOZr2jk0ulPirFO8VUQbOlOEWLlTGA=; b=OFRKmGJwVGO7sH6rLx6C+Rjr8L422Gc+RXFvFtQEDfqpy7oScS55i+BSI1YTKYAGxK ovmGJY2tfOpxxL6HyXTILW1HHn2l7BF+Y+SSytYURoYvtVjL1uN1X8HSxaXvmmwZ+hho 9a6zh3EZGwfDkLQPRBsTiAAZYutz+0c4aqW/SSicoZ7WQM5Prq4lPqgeNdNgmKeLrEx8 cUa45ZOSWCzCDTJGtLLX4N2POSgrEcRwTdhYg38+d9SBu3YcrR+ClYVraFf0EVksSe9z SjFK/r7GY4a/fuXMberheayWTspFqy5Y/Huag1+SoUDRXarTTy6oTrh/XJ0Sv9D3MG7V KOzw== X-Gm-Message-State: AOAM530wp3iAjBZaYQ+XrHbIWJt78f2vv1RclW0b5/qXPJT5m+yQR9S8 levDksDTUBcvs0ASBVw998E= X-Google-Smtp-Source: ABdhPJzoubtI1LUd0IkrwtzvoBvjnX7U0ve1cBkdshNXS9MB2fQMBtFEa18QojEraqFDTutoictQ0w== X-Received: by 2002:a05:600c:1e0e:b0:37c:6c82:72a6 with SMTP id ay14-20020a05600c1e0e00b0037c6c8272a6mr11603865wmb.35.1645208211504; Fri, 18 Feb 2022 10:16:51 -0800 (PST) Received: from fuji.fritz.box (ip-89-161-76-237.tel.tkb.net.pl. [89.161.76.237]) by smtp.gmail.com with ESMTPSA id b2sm20978639wri.35.2022.02.18.10.16.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Feb 2022 10:16:51 -0800 (PST) From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= To: corbet@lwn.net Cc: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v4 11/11] scripts: kernel-doc: Refresh the copyright lines Date: Fri, 18 Feb 2022 19:16:28 +0100 Message-Id: <20220218181628.1411551-12-tomasz.warniello@gmail.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220218181628.1411551-1-tomasz.warniello@gmail.com> References: <20220218181628.1411551-1-tomasz.warniello@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org I wanted to clean up these lines, but in the end decided not to touch the old ones and just add my own about POD. I'll leave the cleanup for lawyers. Signed-off-by: Tomasz Warnie=C5=82=C5=82o Acked-by: Randy Dunlap Tested-by: Randy Dunlap --- Still credits go to Jonathat Corbet for alerting me when I moved them to POD in version 1. --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index a5a397e22ea7..f06f68f3c3d9 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -12,6 +12,8 @@ use strict; ## ## ## #define enhancements by Armin Kuster ## ## Copyright (c) 2000 MontaVista Software, Inc. ## +# +# Copyright (C) 2022 Tomasz Warnie=C5=82=C5=82o (POD) =20 use Pod::Usage qw/pod2usage/; =20 --=20 2.30.2