Newer
Older
# SPDX-License-Identifier: GPL-2.0
use strict;
## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
## Copyright (C) 2001 Simon Huggins ##
## Copyright (C) 2005-2012 Randy Dunlap ##
## Copyright (C) 2012 Dan Luedtke ##
## ##
## #define enhancements by Armin Kuster <akuster@mvista.com> ##
## Copyright (c) 2000 MontaVista Software, Inc. ##
## ##
## This software falls under the GNU General Public License. ##
## Please read the COPYING file for more information ##
# 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 <ck@whoop.org>
# 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 <kaos@ocs.com.au>
# 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 <tim@tjansen.de>
# 25/07/2012 - Added support for HTML5
# -- Dan Luedtke <mail@danrl.de>
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/doc-guide/kernel-doc.rst for the documentation comment syntax.
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):
-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()
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
reStructuredText format.
-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.
Other parameters:
-v Verbose output, more warnings and other information.
-h Print this help.
-Werror Treat warnings as errors.
EOF
print $message;
exit 1;
}
#
# 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 line
# 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.
# 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.
Danilo Cesar Lemes de Paula
committed
# 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 functions
# can be called form interrupts. Unlike other sections you can end it with an
# 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 marked
# 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);
# */
# ...
#
#
Loading
Loading full blame...