Commit fadc0b31 authored by Jani Nikula's avatar Jani Nikula Committed by Jonathan Corbet
Browse files

kernel-doc: rewrite usage description, remove duplicated comments 



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: default avatarJani Nikula <jani.nikula@intel.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 2fd872bd

scripts/kernel-doc

+37 −46
Original line number Original line Diff line number Diff line
@@ -39,41 +39,43 @@ use strict; 
# 25/07/2012 - Added support for HTML5

# 25/07/2012 - Added support for HTML5

# -- Dan Luedtke <mail@danrl.de>

# -- Dan Luedtke <mail@danrl.de>





#

sub usage {

# This will read a 'c' file and scan for embedded comments in the

    my $message = <<"EOF";

# style of gnome comments (+minor extensions - see below).

Usage: $0 [OPTION ...] FILE ...

#





Read C language source or header FILEs, extract embedded documentation comments,

# Note: This only supports 'c'.

and print formatted documentation to standard output.





# usage:

The documentation comments are identified by "/**" opening comment mark. See

# kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]

Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.

#            [ -no-doc-sections ]



#            [ -function funcname [ -function funcname ...] ]

Output format selection (mutually exclusive):

#            c file(s)s > outputfile

  -docbook		Output DocBook format.

# or

  -html			Output HTML format.

#            [ -nofunction funcname [ -function funcname ...] ]

  -html5		Output HTML5 format.

#            c file(s)s > outputfile

  -list			Output symbol list format. This is for use by docproc.

#

  -man			Output troff manual page format. This is the default.

#  Set output format using one of -docbook -html -html5 -text or -man.

  -text			Output plain text format.

#  Default is man.



#  The -list format is for internal use by docproc.

Output selection (mutually exclusive):

#

  -function NAME	Only output documentation for the given function(s)

#  -no-doc-sections

			or DOC: section title(s). All other functions and DOC:

#	Do not output DOC: sections

			sections are ignored. May be specified multiple times.

#

  -nofunction NAME	Do NOT output documentation for the given function(s);

#  -function funcname

			only output documentation for the other functions and

#	If set, then only generate documentation for the given function(s) or

			DOC: sections. May be specified multiple times.

#	DOC: section titles.  All other functions and DOC: sections are ignored.



#

Output selection modifiers:

#  -nofunction funcname

  -no-doc-sections	Do not output DOC: sections.

#	If set, then only generate documentation for the other function(s)/DOC:



#	sections. Cannot be used together with -function (yes, that's a bug --

Other parameters:

#	perl hackers can fix it 8))

  -v			Verbose output, more warnings and other information.

#

  -h			Print this help.

#  c files - list of 'c' files to process



#

EOF

#  All output goes to stdout, with errors to stderr.

    print $message;

    exit 1;

}





#

#

# format of comments.

# format of comments.
@@ -437,17 +439,6 @@ while ($ARGV[0] =~ m/^-(.*)/) { 




# continue execution near EOF;

# 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

# get kernel version from env

sub get_kernel_version() {

sub get_kernel_version() {

    my $version = 'unknown kernel version';

    my $version = 'unknown kernel version';