Commit Graph

109 Commits

Author SHA1 Message Date
Linus Torvalds
5ebe0ee802 There is a nice new document from Neil on how pathname lookups work and
some new CAN driver documentation.  Beyond that, we have kernel-doc fixes,
 a bit more work to support reproducible builds, and the usual collection of
 small fixes.
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1
 
 iQIcBAABAgAGBQJWO6HiAAoJEI3ONVYwIuV6ihwQAK0KC72h0706bdwDJ1p1/aJU
 QLuPeiKYWgGAXq2zgOyw3Povj4bkMwkiq1IGHLyK0Id4tg3ngxOXjimk4YKrqarI
 BD5HdpOm7IyQEe66ZU9b1RFDVst+bg3yp6ZIZsH5vQxl/KnyJ6AyaaDk8TPYId8S
 1+CykJzxyi7GyT/jlLpHbKtBKrraoVke+cNPMAvOf0NjSyO7Ix5B+qH50sttG6Eu
 9qcQ8hlKXOdZRTiGW6P+jeZNA+e5+CRpnG9VHBquHy4lI85kQThhWq41UMH690PP
 eRbLipeUybb0FwW2KwuMjGKEMDkMvrGJh0TzSXX9lGHd+5/41v7zcyKh8vJcpLjh
 bNQ2WOAKUBd2d15EP1MNoKXDLGJXusJczLwOjigWiSCQvgouAWwMrpWEw+Obv8Yl
 rdoH1oQqDFfDnk6mnKrSaqLWGNuLxDtkEl/1P0jsGSK6lM3FDkOgTuNPYXTJJgxN
 rXuGmPhyUlS2srERUeQJw2rISN0WRBvcKJGkMX6IpvrXHkItbelqK+yY1DeKPmcm
 qgbIx9ZWNqtltFpG22VVByqAVwucO5Nu8cAIQ2ysJsTnKOvQCQmhu5UKTjBCkEJM
 VpeMm32BfNiJFLuLTQGWBZ8bkRl2shQyXhOaR3uyqG4T+rpPD3qJi6dtFRpsAzOB
 q1nZuJCpOaxJFzjSKvpJ
 =emZ7
 -----END PGP SIGNATURE-----

Merge tag 'docs-for-linus' of git://git.lwn.net/linux

Pull documentation update from Jon Corbet:
 "There is a nice new document from Neil on how pathname lookups work
  and some new CAN driver documentation.  Beyond that, we have
  kernel-doc fixes, a bit more work to support reproducible builds, and
  the usual collection of small fixes"

* tag 'docs-for-linus' of git://git.lwn.net/linux: (34 commits)
  Documentation: add new description of path-name lookup.
  Documentation/vm/slub.txt: document slabinfo-gnuplot.sh
  Doc: ABI/stable: Fix typo in ABI/stable
  doc: Clarify that nmi_watchdog param is for hardlockups
  Typo correction for description in gpio document.
  DocBook: Fix kernel-doc to be case-insensitive for private:
  kernel-docs.txt: update kernelnewbies reference
  Doc:kvm: Fix typo in Doc/virtual/kvm
  Documentation/Changes: Add bc in "Current Minimal Requirements" section
  Documentation/email-clients.txt: remove trailing whitespace
  DocBook: Use a fixed encoding for output
  MAINTAINERS: The docs tree has moved
  Docs/kernel-parameters: Add earlycon devicetree usage
  SubmittingPatches: make Subject examples match the de facto standard
  Documentation: gpio: mention that <function>-gpio has been deprecated
  Documentation: cgroups: just fix a few typos
  Documentation: Update kselftest.txt
  Documentation: DMA API: Be more explicit that nents is always the same
  Documentation: Update the default value of crashkernel low
  zram: update documentation
  ...
2015-11-05 15:59:24 -08:00
Mauro Carvalho Chehab
0d8c39e6c6 DocBook: Fix kernel-doc to be case-insensitive for private:
On some places, people could use Private: to tag the private fields
of an struct. So, be case-insensitive when parsing "private:"
meta-tag.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-10-11 15:37:37 -06:00
Mauro Carvalho Chehab
837664528e kernel-doc: better format typedef function output
A typedef function looks more likely a function and not a
normal typedef. Change the code to use the output_function_*,
in order to properly parse the function prototype parameters.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
2015-10-10 10:29:06 -03:00
Mauro Carvalho Chehab
3a80a76632 kernel-doc: Add a parser for function typedefs
The current typedef parser only works for non-function typedefs.

As we need to also document some function typedefs, add a
parser for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
2015-10-10 10:29:05 -03:00
Danilo Cesar Lemes de Paula
4d73270192 scripts/kernel-doc: Replacing highlights hash by an array
The "highlight" code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted. It generates
faulty DocBook entries like:
	- @<function>device_for_each_child</function>

Sorting the result is not enough some times (as it's deterministic but
we can't control it).
We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight is correct.

[jc: I think this is kind of papering around the real problem, that people
 are saying @function() when "function" is not a parameter.  But this makes
 things better than they were before, so...]

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-09-13 14:38:51 -06:00
Ben Hutchings
68f8666238 Documentation: Avoid creating man pages in source tree
Currently kernel-doc generates a dummy DocBook file when asked to
convert a C source file with no structured comments.  For an
out-of-tree build (objtree != srctree), the title of the output file
is the absolute path name of the C source file, which later results
in a manual page being created alongside the C source file.

Change the title to be a relative path.

Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-09-13 14:38:50 -06:00
Danilo Cesar Lemes de Paula
23aebb3c05 scripts/kernel-doc: Processing -nofunc for functions only
Docproc processes the EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to
avoid duplicated documentation in the next call.
It works for most of the cases, but there are some specific situations
where a struct has the same name of an already-exported function.

Current kernel-doc behavior ignores those structs and does not add them
to the final documentation. This patch fixes it.

This is unusual, the only case I've found is the drm_modeset_lock
(function and struct) defined in drm_modeset_lock.h and
drm_modeset_lock.c. Considering this, it should only affect the DRM
documentation by including struct drm_modeset_lock to the final Docbook.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-09-13 14:38:50 -06:00
Bart Van Assche
d40e1e6532 kerneldoc: Convert error messages to GNU error message format
Editors like emacs and vi recognize a number of error message formats.
The format used by the kerneldoc tool is not recognized by emacs.

Change the kerneldoc error message format to the GNU style such that the
emacs prev-error and next-error commands can be used to navigate through
kerneldoc error messages.  For more information about the GNU error
message format, see also
  https://www.gnu.org/prep/standards/html_node/Errors.html.

This patch has been generated via the following sed command:

  sed -i.orig 's/Error(\${file}:\$.):/\${file}:\$.: error:/g;s/Warning(\${file}:\$.):/\${file}:\$.: warning:/g;s/Warning(\${file}):/\${file}:1: warning:/g;s/Info(\${file}:\$.):/\${file}:\$.: info:/g' scripts/kernel-doc

Signed-off-by: Bart Van Assche <bart.vanassche@sandisk.com>
Cc: Johannes Berg <johannes.berg@intel.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2015-09-04 16:54:41 -07:00
Jonathan Corbet
f007492964 kernel-doc: ignore unneeded attribute information
The kernel-doc script gets confused by __attribute__(()) strings in
structures, so just clean the out.  Also ignore the CRYPTO_MINALIGN_ATTR
macro used in the crypto subsystem.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-08-23 13:54:33 -06:00
Danilo Cesar Lemes de Paula
a4c6ebede2 scripts/kernel-doc Allow struct arguments documentation in struct body
Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work well
for struct with a huge list of elements.

Keeping the arguments list inside the struct body makes it easier
to maintain the documentation.
ie:
/**
 * 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 patch allows the use of this kind of syntax. Only one argument
per comment and user can use how many paragraphs he needs. It should
start with /**, which is already being used by kernel-doc. If those
comment doesn't follow those rules, it will be ignored.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Stephan Mueller <smueller@chronox.de>
Cc: Michal Marek <mmarek@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: intel-gfx <intel-gfx@lists.freedesktop.org>
Cc: dri-devel <dri-devel@lists.freedesktop.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-08-06 13:05:35 -06:00
Ben Hutchings
b2c4105b08 scripts/kernel-doc: Use $KBUILD_BUILD_TIMESTAMP as man page date
Together with the preceding changes, this allows man pages to be built
reproducibly.

Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-07-10 11:03:25 -06:00
Jérémy Bobbio
2e106e4df2 scripts/kernel-doc: parse kernel-doc deterministically
Regular expressions for highlights in kernel-doc are stored in a Perl
hash.  These hashes are ordered differently for each Perl run. This will
prevent kernel-doc to behave deterministically when parsing “@foo()” as
in some runs it will be interpreted as a parameter and in the others it
will be interpreted as a function.

We now sort the %highlights hash to get the same behavior on every run.

Signed-off-by: Jérémy Bobbio <lunar@debian.org>
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-07-10 11:03:05 -06:00
Johannes Berg
7b990789a4 scripts/kernel-doc: don't eat struct members with __aligned
The change from \d+ to .+ inside __aligned() means that the following
structure:

  struct test {
        u8 a __aligned(2);
        u8 b __aligned(2);
  };

essentially gets modified to

  struct test {
        u8 a;
  };

for purposes of kernel-doc, thus dropping a struct member, which in
turns causes warnings and invalid kernel-doc generation.

Fix this by replacing the catch-all (".") with anything that's not a
semicolon ("[^;]").

Fixes: 9dc30918b2 ("scripts/kernel-doc: handle struct member __aligned without numbers")
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Cc: Nishanth Menon <nm@ti.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Michal Marek <mmarek@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2014-12-10 17:41:02 -08:00
Randy Dunlap
270a00963c scripts/kernel-doc: recognize __meminit
Fix scripts/kernel-doc to recognize __meminit in a function prototype
and to strip it, as done with many other attributes.

Fixes this warning:

  Warning(..//mm/page_alloc.c:2973): cannot understand function prototype: 'void * __meminit alloc_pages_exact_nid(int nid, size_t size, gfp_t gfp_mask) '

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2014-08-26 13:49:57 -07:00
Horia Geanta
cbb4d3e651 scripts/kernel-doc: handle object-like macros
Object-like macros are different than function-like macros:
https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.html
https://gcc.gnu.org/onlinedocs/cpp/Function-like-Macros.html

They are not parsed correctly, generating invalid intermediate
files (xmls) for cases like:
    #define BIT_MASK    (0xFF << BIT_SHIFT)
where "OxFF <<" is considered to be parameter type.

When parsing, we can differentiate beween these two types of macros by
checking whether there is at least one whitespace b/w "#define" and
first opening parenthesis.

Signed-off-by: Horia Geanta <horia.geanta@freescale.com>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2014-07-12 11:30:36 -07:00
Linus Torvalds
e4528d696f Merge branch 'misc' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild
Pull misc kbuild changes from Michal Marek:
 - make tags fixes again
 - scripts/show_delta fix for newer python
 - scripts/kernel-doc does not fail on unknown function prototype
 - one less coccinelle check this time

* 'misc' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild:
  scripts/tags.sh: remove obsolete __devinit[const|data]
  scripts/kernel-doc: make unknown function prototype a Warning instead of an Error
  show_delta: Update script to support python versions 2.5 through 3.3
  scripts/coccinelle/api: remove devm_request_and_ioremap.cocci
  scripts/tags.sh: Increase identifier list
2013-11-15 14:09:15 -08:00
Johannes Berg
e946c43a11 kernel-doc: improve "no structured comments found" error
When using '!Ffile function' in a docbook template, and the function no
longer exists, you get a "no structured comments found" error from the
kernel-doc processing script.  It's useful to know which functions it was
looking for, so print them out in this case.  Also do the same for '!Pfile
doc-section'

The same error also happens when using '!Efile' when some exported
functions aren't documented (in the same file.) There's a very large
number of such functions though, so don't print the message in this case
-- right now it would give ~850 messages.

Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Cc: Rob Landley <rob@landley.net>
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2013-11-13 12:09:32 +09:00
Randy Dunlap
9645ae84ef scripts/kernel-doc: make unknown function prototype a Warning instead of an Error
When scripts/kernel-doc cannot understand a function prototype,
it had been generating a fatal error and stopping immediately.
Make this a Warning instead of an Error and keep going.

Note that this can happen if the kernel-doc notation that is being
parsed is not actually a function prototype; maybe it's a struct or
something else, so I added "function" to the warning message to try
to make it clearer that scripts/kernel-doc is looking for a function
prototype here.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc:	Mark Brown <broonie@kernel.org>
Signed-off-by: Michal Marek <mmarek@suse.cz>
2013-11-06 22:00:35 +01:00
Nishanth Menon
9dc30918b2 scripts/kernel-doc: handle struct member __aligned without numbers
Commit ef5da59f12 ("scripts/kernel-doc: handle struct member
__aligned") permits "char something [123] __aligned(8);".

However, by using \d we constraint ourselves with integers.  This is not
always the case.  In fact, it might be better to do char something[123]
__aligned(sizeof(u16));

For example, With wireless_dev defining:

    u8 address[ETH_ALEN] __aligned(sizeof(u16));

With \d, scripts/kernel-doc erroneously says:

    Warning(include/net/cfg80211.h:2618): Excess struct/union/enum/typedef member 'address' description in 'wireless_dev'

This is because the regex __aligned\s*\(\d+\) fails match at \d as
sizeof is used.

So replace \d with .  to indicate "something" in kernel-doc to ignore
__aligned(SOMETHING) in structs.  With this change, we can use integers
OR sizeof() or macros as we please.

Signed-off-by: Nishanth Menon <nm@ti.com>
Cc: Fengguang Wu <fengguang.wu@intel.com>
Cc: Johannes Berg <johannes.berg@intel.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Michal Marek <mmarek@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2013-02-27 19:10:09 -08:00
Greg Kroah-Hartman
6ae141718e misc: remove __dev* attributes.
CONFIG_HOTPLUG is going away as an option.  As a result, the __dev*
markings need to be removed.

This change removes the last of the __dev* markings from the kernel from
a variety of different, tiny, places.

Based on patches originally written by Bill Pemberton, but redone by me
in order to handle some of the coding style issues better, by hand.

Cc: Bill Pemberton <wfp5p@virginia.edu>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2013-01-03 15:57:16 -08:00
Yacine Belkadi
4092bac771 scripts/kernel-doc: check that non-void fcts describe their return value
If a function has a return value, but its kernel-doc comment doesn't contain a
"Return" section, then emit the following warning:

   Warning(file.h:129): No description found for return value of 'fct'

Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.

Signed-off-by: Yacine Belkadi <yacine.belkadi.1@gmail.com>
Signed-off-by: Rob Landley <rob@landley.net>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
2012-11-27 21:09:35 +01:00
Linus Torvalds
cbd8aca472 Merge branch 'misc' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild
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
2012-10-12 10:32:29 +09:00
Daniel Santos
12ae677933 kernel-doc: don't mangle whitespace in Example section
A section with the name "Example" (case-insensitive) has a special meaning
to kernel-doc.  These sections are output using mono-type fonts.  However,
leading whitespace is stripped, thus robbing a lot of meaning from this,
as indented code examples will be mangled.

This patch preserves the leading whitespace for "Example" sections.  More
accurately, it preserves it for all sections, but removes it later if the
section isn't an "Example" section.

Signed-off-by: Daniel Santos <daniel.santos@pobox.com>
Cc: Randy Dunlap <rdunlap@xenotime.net>
Cc: Michal Marek <mmarek@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2012-10-06 03:05:13 +09:00
Daniel Santos
e314ba3130 kernel-doc: bugfix - empty line in Example section
If you have a section named "Example" that contains an empty line,
attempting to generate htmldocs give you the error:

/path/Documentation/DocBook/kernel-api.xml:3455: parser error : Opening and ending tag mismatch: programlisting line 3449 and para
   </para><para>
          ^
/path/Documentation/DocBook/kernel-api.xml:3473: parser error : Opening and ending tag mismatch: para line 3467 and programlisting
</programlisting></informalexample>
                 ^
/path/Documentation/DocBook/kernel-api.xml:3678: parser error : Opening and ending tag mismatch: programlisting line 3672 and para
   </para><para>
          ^
/path/Documentation/DocBook/kernel-api.xml:3701: parser error : Opening and ending tag mismatch: para line 3690 and programlisting
</programlisting></informalexample>
                 ^
unable to parse
/path/Documentation/DocBook/kernel-api.xml

Essentially, the script attempts to close a <programlisting> with a
closing tag for a <para> block.  This patch corrects the problem by
simply not outputting anything extra when we're dumping pre-formatted
text, since the empty line will be rendered correctly anyway.

Signed-off-by: Daniel Santos <daniel.santos@pobox.com>
Cc: Randy Dunlap <rdunlap@xenotime.net>
Cc: Michal Marek <mmarek@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2012-10-06 03:05:13 +09:00
Daniel Santos
6547842844 kernel-doc: bugfix - multi-line macros
Prior to this patch the following code breaks:

/**
 * multiline_example - this breaks kernel-doc
 */
 #define multiline_example( \
myparam)

Producing this error:

Error(somefile.h:983): cannot understand prototype: 'multiline_example( \ '

This patch fixes the issue by appending all lines ending in a blackslash
(optionally followed by whitespace), removing the backslash and any
whitespace after it prior to appending (just like the C pre-processor
would).

This fixes a break in kerel-doc introduced by the additions to rbtree.h.

Signed-off-by: Daniel Santos <daniel.santos@pobox.com>
Cc: Randy Dunlap <rdunlap@xenotime.net>
Cc: Michal Marek <mmarek@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2012-10-06 03:05:13 +09:00
Dan Luedtke
1b40c1944d scripts/kernel-doc: added support for html5
New output option html5 writes validating HTML5 and adds
CSS classes ready to be selected by third-party stylesheets.
HTML ids have been added to block-level elements "article" for
direct reference of particular objects via URL.

Signed-off-by: Dan Luedtke <mail@danrl.de>
Acked-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Michal Marek <mmarek@suse.cz>
2012-08-31 15:34:39 +02:00
Randy Dunlap
0df7c0e3a7 scripts/kernel-doc: fix fatal script error
Fix fatal error in scripts/kernel-doc by ignoring the "__weak" attribute:

  Error(drivers/pci/pci.c:2820): cannot understand prototype: 'char * __weak pcibios_setup(char *str) '

Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2012-08-17 09:19:07 -07:00
Randy Dunlap
70c95b00b8 scripts/kernel-doc: fix fatal error caused by cfg80211.h
include/net/cfg80211.h uses __must_check in functions that
have kernel-doc notation.  This was confusing scripts/kernel-doc,
so have scripts/kernel-doc ignore "__must_check".

Error(include/net/cfg80211.h:2702): cannot understand prototype: 'struct cfg80211_bss * __must_check cfg80211_inform_bss(...)

Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Cc:	Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2012-01-23 08:44:53 -08:00
Lucas De Marchi
25985edced Fix common misspellings
Fixes generated by 'codespell' and manually reviewed.

Signed-off-by: Lucas De Marchi <lucas.demarchi@profusion.mobi>
2011-03-31 11:26:23 -03:00
Randy Dunlap
8484baaa50 kernel-doc: code reorganization
Move 'main' code vs. subroutines around so that they are not so
intermixed, for better readability/understanding (relative to Perl).
It was messy to follow the primary flow of code execution with the
code being mixed.  Now the code begins with data initialization,
followed by all subroutines, then ends with the main code execution.

This is almost totally source code movement, with a few changes as
needed for forward declarations.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2011-01-06 09:59:38 -08:00
Randy Dunlap
2b35f4d9ca kernel-doc: escape xml for structs
scripts/kernel-doc was leaving unescaped '<', '>', and '&' in
generated xml output for structs.  This causes xml parser errors.
Convert these characters to "&lt;", "&gt;", and "&amp;" as needed
to prevent errors.

Most of the conversion was already done; complete it just before
output.

Documentation/DocBook/device-drivers.xml:41883: parser error : StartTag: invalid element name
#define INPUT_KEYMAP_BY_INDEX	(1 << 0)

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-11-18 15:00:46 -08:00
Johannes Berg
eda603f6cd docbook: warn on unused doc entries
When you don't use !E or !I but only !F, then it's very easy to miss
including some functions, structs etc.  in documentation.  To help
finding which ones were missed, allow printing out the unused ones as
warnings.

For example, using this on mac80211 yields a lot of warnings like this:

  Warning: didn't use docs for DOC: mac80211 workqueue
  Warning: didn't use docs for ieee80211_max_queues
  Warning: didn't use docs for ieee80211_bss_change
  Warning: didn't use docs for ieee80211_bss_conf

when generating the documentation for it.

Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-09-11 16:49:21 -07:00
Johannes Berg
1f3a66889c kernel-doc: ignore case when stripping attributes
There are valid attributes that could have upper case letters, but we
still want to remove, like for example
	__attribute__((aligned(NETDEV_ALIGN)))
as encountered in the wireless code.

Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-09-11 16:49:21 -07:00
Randy Dunlap
b6d676db35 mtd/nand_base: fix kernel-doc warnings & typos
Fix mtd/nand_base.c kernel-doc warnings and typos.

Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'invert'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:2087): No description found for parameter 'len'

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: David Woodhouse <dwmw2@infradead.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-08-11 08:59:18 -07:00
Randy Dunlap
20072205fc scripts/kernel-doc: fix fatal error on function prototype
Fix a fatal error in scripts/kernel-doc when a function signature uses
__init_or_module (just ignore that string):

Error(drivers/base/platform.c:568): cannot understand prototype: 'struct platform_device * __init_or_module platform_create_bundle(struct platform_driver *driver, int (*probe)(struct platform_device *), struct resource *res, unsigned int n_res, const void *data, size_t size) '

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-03-24 16:31:20 -07:00
Randy Dunlap
ef5da59f12 scripts/kernel-doc: handle struct member __aligned
scripts/kernel-doc erroneously says:

Warning(include/linux/skbuff.h:410): Excess struct/union/enum/typedef member 'cb' description in 'sk_buff'

on this line in struct sk_buff:
	char			cb[48] __aligned(8);

due to treating the last field as the struct member name, so teach
kernel-doc to ignore __aligned(x) in structs.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-03-24 16:31:19 -07:00
Randy Dunlap
4c98ecaf35 scripts/kernel-doc: fix empty function description section
scripts/kernel-doc mishandles a function that has a multi-line function
short description and no function parameters.  The observed problem was
from drivers/scsi/scsi_netlink.c:

/**
 * scsi_netlink_init - Called by SCSI subsystem to intialize
 * 	the SCSI transport netlink interface
 *
 **/

kernel-doc treated the " * " line as a Description: section with only a
newline character in the Description contents.  This caused
output_highlight() to complain: "output_highlight got called with no
args?", plus produce a perl call stack backtrace.

The fix is just to ignore Description sections if they only contain "\n".

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-03-12 15:52:35 -08:00
Ilya Dryomov
1c32fd0c5a kernel-doc: drop the -filelist option, it doesn't work
I also found the -filelist option, but apparently the implementation
is broken, and it was broken from the very first git commit.
For the -filelist option I suggest the removal (I wasn't able to find
any users of it, moreover it's not even listed in the
usage() output, so presumably nobody knows about it).

Signed-off-by: Ilya Dryomov <idryomov@gmail.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-02-26 17:23:50 -08:00
Ilya Dryomov
a9e7314b79 kernel-doc: track line numbers for each file separately
The problem is that $. keeps track of the current record number (which
is line number by default). But if you pass it multiple files, it does
not wrap at the end of file, and therefore contains the *total* number
of processed lines.
I suppose we can fix line numbering by introducing a simple assignment
$. = 1
before processing every new file.

Signed-off-by: Ilya Dryomov <idryomov@gmail.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-02-26 17:23:49 -08:00
Jason Baron
3a9089fd78 tracing: Add DEFINE_EVENT(), DEFINE_SINGLE_EVENT() support to docbook
The introduction of the new 'DECLARE_EVENT_CLASS()' obviates the
need for the 'TRACE_EVENT()' macro in some cases. Thus, docbook
style comments that used to live with 'TRACE_EVENT()' are now
moved to 'DEFINE_EVENT()'. Thus, we need to make the docbook
system understand the new 'DEFINE_EVENT()' macro. In addition
I've tried to futureproof the patch, by also adding support for
'DEFINE_SINGLE_EVENT()', since there has been discussion about
renaming: TRACE_EVENT() -> DEFINE_SINGLE_EVENT().

Without this patch the tracepoint docbook fails to build.

I've verified that this patch correctly builds the tracepoint
docbook which currently covers signals, and irqs.

Changes in v2:
 - properly indent perl 'if' statements

Signed-off-by: Jason Baron <jbaron@redhat.com>
Acked-by: Steven Rostedt <rostedt@goodmis.org>
Acked-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: William Cohen <wcohen@redhat.com>
Cc: Frederic Weisbecker <fweisbec@gmail.com>
Cc: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
Cc: Masami Hiramatsu <mhiramat@redhat.com>
LKML-Reference: <200912011718.nB1HIn7t011371@int-mx04.intmail.prod.int.phx2.redhat.com>
Signed-off-by: Ingo Molnar <mingo@elte.hu>
2009-12-02 09:57:37 +01:00
Johannes Weiner
6423133bde kernel-doc: allow multi-line declaration purpose descriptions
Allow the short description after symbol name and dash in a kernel-doc
comment to span multiple lines, e.g. like this:

	/**
	 * unmap_mapping_range - unmap the portion of all mmaps in the
	 *	specified address_space corresponding to the specified
	 *	page range in the underlying file.
	 * @mapping: the address space containing mmaps to be unmapped.
	 * ...
	 */

The short description ends with a parameter description, an empty line
or the end of the comment block.

Signed-off-by: Johannes Weiner <hannes@cmpxchg.org>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-09-18 09:48:52 -07:00
Randy Dunlap
d960eea974 kernel-doc: move ignoring kmemcheck
Somehow I managed to generate a diff that put these 2 lines
into the wrong function:  should have been in dump_struct()
instead of in dump_enum().

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-07-01 11:26:40 -07:00
Randy Dunlap
e34e7dbb35 kernel-doc: fix param matching for array params
Fix function actual parameter vs. kernel-doc description matching
so that a warning is not printed when it should not be:

Warning(include/linux/etherdevice.h:199): Excess function parameter 'addr' description in 'is_etherdev_addr'

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2009-06-20 13:35:01 +02:00
Randy Dunlap
b2fd6dbf25 kernel-doc: ignore kmemcheck_bitfield_begin/end
Teach kernel-doc to ignore kmemcheck_bitfield_{begin,end} sugar
so that it won't generate warnings like this:

Warning(include/net/sock.h:297): No description found for parameter 'kmemcheck_bitfield_begin(flags)'
Warning(include/net/sock.h:297): No description found for parameter 'kmemcheck_bitfield_end(flags)'

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2009-06-20 13:35:00 +02:00
Linus Torvalds
45e3e1935e Merge branch 'master' of git://git.kernel.org/pub/scm/linux/kernel/git/sam/kbuild-next
* 'master' of git://git.kernel.org/pub/scm/linux/kernel/git/sam/kbuild-next: (53 commits)
  .gitignore: ignore *.lzma files
  kbuild: add generic --set-str option to scripts/config
  kbuild: simplify argument loop in scripts/config
  kbuild: handle non-existing options in scripts/config
  kallsyms: generalize text region handling
  kallsyms: support kernel symbols in Blackfin on-chip memory
  documentation: make version fix
  kbuild: fix a compile warning
  gitignore: Add GNU GLOBAL files to top .gitignore
  kbuild: fix delay in setlocalversion on readonly source
  README: fix misleading pointer to the defconf directory
  vmlinux.lds.h update
  kernel-doc: cleanup perl script
  Improve vmlinux.lds.h support for arch specific linker scripts
  kbuild: fix headers_exports with boolean expression
  kbuild/headers_check: refine extern check
  kbuild: fix "Argument list too long" error for "make headers_check",
  ignore *.patch files
  Remove bashisms from scripts
  menu: fix embedded menu presentation
  ...
2009-06-14 14:12:18 -07:00
Randy Dunlap
b9d97328e2 kernel-doc: cleanup perl script
Various cleanups of scripts/kernel-doc:
- don't use **/ as an ending kernel-doc block since it's not preferred;
- typos/spellos
- add whitespace around ==, after comma, & around . operator;

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2009-06-09 23:02:30 +02:00
Ingo Molnar
44347d947f Merge branch 'linus' into tracing/core
Merge reason: tracing/core was on a .30-rc1 base and was missing out on
              on a handful of tracing fixes present in .30-rc5-almost.

Signed-off-by: Ingo Molnar <mingo@elte.hu>
2009-05-07 11:17:34 +02:00
Randy Dunlap
52dc5aec9f kernel-doc: restrict syntax for private: and public:
scripts/kernel-doc can (incorrectly) delete struct members that are
surrounded by /* ...  */ <struct members> /* ...  */ if there is a /*
private: */ comment in there somewhere also.

Fix that by making the "/* private:" only allow whitespace between /* and
"private:", not anything/everything in the world.

This fixes some erroneous kernel-doc warnings that popped up while
processing include/linux/usb/composite.h.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-05-02 15:36:10 -07:00
Jason Baron
56afb0f882 kerneldoc, tracing: make kernel-doc understand TRACE_EVENT() macro (take #2)
Add support to kernel-doc for tracepoint comments above TRACE_EVENT()
macro definitions. Paves the way for tracepoint docbook.

[ Impact: extend DocBook infrastructure ]

Signed-off-by: Jason Baron <jbaron@redhat.com>
Acked-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: akpm@linux-foundation.org
Cc: rostedt@goodmis.org
Cc: fweisbec@gmail.com
Cc: mathieu.desnoyers@polymtl.ca
Cc: wcohen@redhat.com
LKML-Reference: <d80706b6797e277924d2f3ec9af176c6b2951f88.1241107197.git.jbaron@redhat.com>
Signed-off-by: Ingo Molnar <mingo@elte.hu>
2009-05-01 14:03:35 +02:00
Randy Dunlap
b4870bc5ee kernel-doc: fix syscall wrapper processing
Fix kernel-doc processing of SYSCALL wrappers.

The SYSCALL wrapper patches played havoc with kernel-doc for
syscalls.  Syscalls that were scanned for DocBook processing
reported warnings like this one, for sys_tgkill:

Warning(kernel/signal.c:2285): No description found for parameter 'tgkill'
Warning(kernel/signal.c:2285): No description found for parameter 'pid_t'
Warning(kernel/signal.c:2285): No description found for parameter 'int'

because the macro parameters all "look like" function parameters,
although they are not:

/**
 *  sys_tgkill - send signal to one specific thread
 *  @tgid: the thread group ID of the thread
 *  @pid: the PID of the thread
 *  @sig: signal to be sent
 *
 *  This syscall also checks the @tgid and returns -ESRCH even if the PID
 *  exists but it's not belonging to the target process anymore. This
 *  method solves the problem of threads exiting and PIDs getting reused.
 */
SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
{
...

This patch special-cases the handling SYSCALL_DEFINE* function
prototypes by expanding them to
	long sys_foobar(type1 arg1, type1 arg2, ...)

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-02-11 14:25:36 -08:00