Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1317809

[RFC 01/10] kernel-doc: rewrite usage description, remove duplicated comments

Show all headers | View raw

Instead of having the kernel-doc usage in both comments and in output to
the user, merge them all to one here document. While at it, imrove the
text and make it pretty. Give shoemaker's children some shoes.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 scripts/kernel-doc | 83 ++++++++++++++++++++++++------------------------------
 1 file changed, 37 insertions(+), 46 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c37255bb620d..29fd5cabb657 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -39,41 +39,43 @@ use strict;
 # 25/07/2012 - Added support for HTML5
 # -- Dan Luedtke <mail@danrl.de>
 
-#
-# This will read a 'c' file and scan for embedded comments in the
-# style of gnome comments (+minor extensions - see below).
-#
-
-# Note: This only supports 'c'.
-
-# usage:
-# kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
-#            [ -no-doc-sections ]
-#            [ -function funcname [ -function funcname ...] ]
-#            c file(s)s > outputfile
-# or
-#            [ -nofunction funcname [ -function funcname ...] ]
-#            c file(s)s > outputfile
-#
-#  Set output format using one of -docbook -html -html5 -text or -man.
-#  Default is man.
-#  The -list format is for internal use by docproc.
-#
-#  -no-doc-sections
-#	Do not output DOC: sections
-#
-#  -function funcname
-#	If set, then only generate documentation for the given function(s) or
-#	DOC: section titles.  All other functions and DOC: sections are ignored.
-#
-#  -nofunction funcname
-#	If set, then only generate documentation for the other function(s)/DOC:
-#	sections. Cannot be used together with -function (yes, that's a bug --
-#	perl hackers can fix it 8))
-#
-#  c files - list of 'c' files to process
-#
-#  All output goes to stdout, with errors to stderr.
+sub usage {
+    my $message = <<"EOF";
+Usage: $0 [OPTION ...] FILE ...
+
+Read C language source or header FILEs, extract embedded documentation comments,
+and print formatted documentation to standard output.
+
+The documentation comments are identified by "/**" opening comment mark. See
+Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
+
+Output format selection (mutually exclusive):
+  -docbook		Output DocBook format.
+  -html			Output HTML format.
+  -html5		Output HTML5 format.
+  -list			Output symbol list format. This is for use by docproc.
+  -man			Output troff manual page format. This is the default.
+  -text			Output plain text format.
+
+Output selection (mutually exclusive):
+  -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.
+  -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.
+
+Output selection modifiers:
+  -no-doc-sections	Do not output DOC: sections.
+
+Other parameters:
+  -v			Verbose output, more warnings and other information.
+  -h			Print this help.
+
+EOF
+    print $message;
+    exit 1;
+}
 
 #
 # format of comments.
@@ -437,17 +439,6 @@ while ($ARGV[0] =~ m/^-(.*)/) {
 
 # continue execution near EOF;
 
-sub usage {
-    print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n";
-    print "         [ -no-doc-sections ]\n";
-    print "         [ -function funcname [ -function funcname ...] ]\n";
-    print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
-    print "         [ -v ]\n";
-    print "         c source file(s) > outputfile\n";
-    print "         -v : verbose output, more warnings & other info listed\n";
-    exit 1;
-}
-
 # get kernel version from env
 sub get_kernel_version() {
     my $version = 'unknown kernel version';
-- 
2.1.4

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[RFC] A first shot at asciidoc-based formatted docs Jonathan Corbet <corbet@lwn.net> - 2016-01-26 00:30 +0100
  [PATCH 1/4] kernel-doc: add support for asciidoc output Jonathan Corbet <corbet@lwn.net> - 2016-01-26 00:30 +0100
  [PATCH 2/4] docproc: handle asciidoc templates Jonathan Corbet <corbet@lwn.net> - 2016-01-26 00:30 +0100
  [PATCH 3/4] Docs: Makefile tweaks for asciidoc templates Jonathan Corbet <corbet@lwn.net> - 2016-01-26 00:30 +0100
  [PATCH 4/4] Docs: add a sample asciidoc template Jonathan Corbet <corbet@lwn.net> - 2016-01-26 00:30 +0100
  [RFC 10/10] Documentation: build asciidoc documentation Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:10 +0100
  Re: [RFC] A first shot at asciidoc-based formatted docs Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:10 +0100
    [RFC 09/10] Documentation: convert gpu.tmpl to gpu.txt Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:10 +0100
    [RFC 05/10] scripts: add asciidoc-includes to extract includes from asciidoc Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:10 +0100
    [RFC 06/10] scripts: add a kernel-doc helper for special invocation Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:10 +0100
    [RFC 04/10] kernel-doc: add support for printing DOC: comments with escaped names Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    [RFC 01/10] kernel-doc: rewrite usage description, remove duplicated comments Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    Re: [RFC] A first shot at asciidoc-based formatted docs Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-01-26 13:20 +0100
      Re: [RFC] A first shot at asciidoc-based formatted docs Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:40 +0100
    [RFC 03/10] kernel-doc: support printing exported and non-exported symbols Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    [RFC 07/10] scripts: add tool for generating asciidoc dependencies and rules Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    [RFC 08/10] scripts: add a crude converter from DocBook tmpl to asciidoc Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    [RFC 02/10] kernel-doc: add support for asciidoc output Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    Re: [RFC] A first shot at asciidoc-based formatted docs Jonathan Corbet <corbet@lwn.net> - 2016-01-26 15:50 +0100
      Re: [RFC] A first shot at asciidoc-based formatted docs Jonathan Corbet <corbet@lwn.net> - 2016-01-26 16:00 +0100

csiph-web