cbd8aca472
Pull kbuild misc changes from Michal Marek:
"In the non-critical part of kbuild, I have
- Some make coccicheck improvements and two new tests
- Support for a cleaner html output in scripts/kernel-doc, named
html5 (no, it does not play videos, yet)
BTW, Randy wants to route further kernel-doc patches through the
kbuild tree."
* 'misc' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild:
Update SmPL/Coccinelle section of MAINTAINERS
coccicheck: Add the rep+ctxt mode
scripts/coccinelle/tests/odd_ptr_err.cocci: semantic patch for IS_ERR/PTR_ERR inconsistency
scripts/tags.sh: Add magic for pci access functions
scripts/coccinelle: ptr_ret: Add ternary operator version
scripts/kernel-doc: drop maintainer
scripts/kernel-doc: added support for html5
2572 lines
70 KiB
Perl
Executable File
2572 lines
70 KiB
Perl
Executable File
#!/usr/bin/perl -w
|
|
|
|
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>
|
|
|
|
#
|
|
# 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.
|
|
|
|
#
|
|
# 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.
|
|
# */
|
|
# 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.
|
|
#
|
|
# 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
|
|
# empty line.
|
|
# 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);
|
|
# */
|
|
# ...
|
|
#
|
|
#
|
|
# All descriptive text is further processed, scanning for the following special
|
|
# patterns, which are highlighted appropriately.
|
|
#
|
|
# 'funcname()' - function
|
|
# '$ENVVAR' - environmental variable
|
|
# '&struct_name' - name of a structure (up to two words including 'struct')
|
|
# '@parameter' - name of a parameter
|
|
# '%CONST' - name of a constant.
|
|
|
|
## init lots of data
|
|
|
|
my $errors = 0;
|
|