From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S965662AbcAZMLz (ORCPT ); Tue, 26 Jan 2016 07:11:55 -0500 Received: from mga02.intel.com ([134.134.136.20]:60829 "EHLO mga02.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S934470AbcAZMJI (ORCPT ); Tue, 26 Jan 2016 07:09:08 -0500 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.22,350,1449561600"; d="scan'208";a="901340190" From: Jani Nikula To: Jonathan Corbet , linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Daniel Vetter Subject: [RFC 04/10] kernel-doc: add support for printing DOC: comments with escaped names Date: Tue, 26 Jan 2016 14:08:49 +0200 Message-Id: X-Mailer: git-send-email 2.1.4 In-Reply-To: References: <1453764522-29030-1-git-send-email-corbet@lwn.net> In-Reply-To: References: Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org -function supports printing named DOC: sections, but spaces and braces and quotes etc. are allowed in section titles. This is tricky to handle in scripts, let alone Makefiles. Add a new -doc parameter for dumping doc sections (to not convolute -function more than it already is), with support for "escaped" names with everything non-alphanumeric repaced with underscores, in addition to verbatim names. For example, all these three now do the same thing: $ scripts/kernel-doc -function "Panel Self Refresh (PSR/SRD)" drivers/gpu/drm/i915/intel_psr.c $ scripts/kernel-doc -doc "Panel Self Refresh (PSR/SRD)" drivers/gpu/drm/i915/intel_psr.c $ scripts/kernel-doc -doc "Panel_Self_Refresh__PSR_SRD_" drivers/gpu/drm/i915/intel_psr.c Use of -function for extracting DOC: sections should probably be deprecated, but keep it around for backward compatibility. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index ee2ac9137a43..0e410daa92a9 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -71,6 +71,9 @@ Output selection (mutually exclusive): -nofunction NAME Do NOT output documentation for the given function(s); only output documentation for the other functions and DOC: sections. May be specified multiple times. + -doc NAME Only output documentation for the given DOC: section + titles. NAME is matched both as-is and with all + non-alphanumeric characters replaced with underscores. Output selection modifiers: -no-doc-sections Do not output DOC: sections. @@ -457,6 +460,10 @@ while ($ARGV[0] =~ m/^-(.*)/) { } elsif ($cmd eq "-internal") { # only non-exported symbols $function_only = 4; %function_table = () + } elsif ($cmd eq "-doc") { # to only output specific doc sections + $function_only = 5; + $function = shift @ARGV; + $function_table{$function} = 1; } elsif ($cmd eq "-v") { $verbose = 1; } elsif (($cmd eq "-h") || ($cmd eq "--help")) { @@ -520,14 +527,20 @@ sub dump_doc_section { my $file = shift; my $name = shift; my $contents = join "\n", @_; + my $escaped_name = $name; if ($no_doc_sections) { return; } + $escaped_name =~ s/[^a-zA-Z0-9]/_/g; + if (($function_only == 0) || ( $function_only == 1 && defined($function_table{$name})) || - ( $function_only == 2 && !defined($function_table{$name}))) + ( $function_only == 2 && !defined($function_table{$name})) || + ( $function_only == 5 && + (defined($function_table{$name}) || + defined($function_table{$escaped_name})))) { dump_section($file, $name, $contents); output_blockhead({'sectionlist' => \@sectionlist, -- 2.1.4