Pull documentation updates from Jonathan Corbet:
"Numerous fixes, the overdue removal of the i2o docs, some new Chinese
translations, and, hopefully, the README fix that will end the flow of
identical patches to that file"
* tag 'docs-for-linus' of git://git.lwn.net/linux-2.6: (34 commits)
Documentation/memcg: update memcg/kmem status
Documentation: blackfin: Makefile: Typo building issue
Documentation/vm/pagemap.txt: correct location of page-types tool
Documentation/memory-barriers.txt: typo fix
doc: Add guest_nice column to example output of `cat /proc/stat'
Documentation/kernel-parameters: Move "eagerfpu" to its right place
Documentation: gpio: Update ACPI part of the document to mention _DSD
docs/completion.txt: Various tweaks and corrections
doc: completion: context, scope and language fixes
Documentation:Update Documentation/zh_CN/arm64/memory.txt
Documentation:Update Documentation/zh_CN/arm64/booting.txt
Documentation: Chinese translation of arm64/legacy_instructions.txt
DocBook media: fix broken EIA hyperlink
Documentation: tweak the maintainers entry
README: Change gzip/bzip2 to xz compression format
README: Update version number reference
doc:pci: Fix typo in Documentation/PCI
Documentation: drm: Use '->' when describing access through pointers.
Documentation: Remove mentioning of block barriers
Documentation/email-clients.txt: Fix one grammar mistake, add extra info about TB
...
Try to make coding style documentation look a bit more readable and
consistent with the following:
- indent every code example in C to first tab-stop;
- surround every code example with empty lines, both top and bottom;
- remove empty lines where text looked way too spare;
- do not indent examples in elisp and kconfig;
- do not do any non-whitespace changes.
Signed-off-by: Pavel Kretov <firegurafiku@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Coding style description has a irregular mixture of tabs and spaces in two
places which is bad by any means and can possibly hurt somebody's sense
of beauty.
Signed-off-by: Pavel Kretov <firegurafiku@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Suggest to developers who use emacs that they turn on the
instantaneous trailing-whitespace warning feature.
Signed-off-by: Alison Chaiken <alison_chaiken@mentor.com>
[jc: untabified to match its surroundings]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
I added a paragraph on choosing label names, and updated the example
code to use a better label name. I also cleaned up the example code to
more modern style by moving the allocation out of the initializer and
changing the NULL check.
Perhaps the most common type of error handling bug in the kernel is "one
err bugs". CodingStyle already says that we should "avoid nesting" by
using error labels and one err style error handling tends to have
multiple indent levels, so this was already bad style. But I've added a
new paragraph explaining how to avoid one err bugs by using multiple
error labels which is, hopefully, more clear.
Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>
Acked-by: Julia Lawall <julia.lawall@lip6.fr>
[jc: added GFP_KERNEL to kmalloc() call]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Document several common practices and conventions regarding conditional
compilation, most notably the preference for ifdefs in headers rather
than .c files.
Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Acked-by: Geert Uytterhoeven <geert@linux-m68k.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There was a minor typo in the CodingStyle document where the word 'section'
had been spelled as 'secton'.
Signed-off-by: Raymond L. Rivera <ray.l.rivera@gmail.com>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
The pr_debug() and related debug print macros all differ from the normal
pr_XXX() macros, in that the normal ones print unconditionally, while
the debug macros are compiled out unless DEBUG is defined or
CONFIG_DYNAMIC_DEBUG is set. This isn't obvious, and the only way to
find this out is either to review the actual printk.h code or to read
CodingStyle, and the message there doesn't highlight the fact.
Change Documentation/CodingStyle to clearly indicate that pr_debug() and
related debug printing macros behave differently than all other pr_XXX()
macros, and attempt to clarify when and where the different debug
printing methods might be used.
Add short comment to printk.h above the pr_XXX() macros indicating that
while these macros print unconditionally, pr_debug() does not.
Signed-off-by: Dan Streetman <ddstreet@ieee.org>
Cc: Joe Perches <joe@perches.com>
Cc: Fabian Frederick <fabf@skynet.be>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
A surprising number of newbies interpret this section to mean that only
one return statement is allowed per function. Part of the problem is that
the "one return statement per function" rule is an actual style guideline
that people are used to from other projects.
Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>
Cc: Eduardo Valentin <eduardo.valentin@ti.com>
Cc: Rob Landley <rob@landley.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
After commit 38829dc9d7 ("Documentation/CodingStyle: flesh out if-else
examples") highlight that if _only_one_ branch of a conditional
statement is a single statement, then braces are to be used on both
branches.
Signed-off-by: Antonio Ospite <ospite@studenti.unina.it>
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
The list of available general purpose memory allocators in
Documentation/CodingStyle chapter 14 is incomplete. This patch adds
the missing vzalloc() to the list.
Signed-off-by: Jesper Juhl <jj@chaosbits.net>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
There is a missing case for "Chapter 3: Placing Braces and Spaces". We
often know we should not use braces where a single statement. The first
case is:
if (condition)
action();
Another case is:
if (condition)
do_this();
else
do_that();
However, I can not find a description of the second case.
Signed-off-by: Harry Wei <harryxiyou@gmail.com>
Cc: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
With the previous Emacs tips example the kernel style was made available
for files in the kernel-tree only. This patch updates the tip to add a
separate cc-mode indent style ("linux-tabs-only"). This makes it easy to
switch between different indent styles and also makes the kernel style
easily available for any filetype mode (c++, awk, ...) that is managed
by the Emacs cc-mode.
Signed-off-by: Teemu Likonen <tlikonen@iki.fi>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
I would suggest this change to make CodingStyle properly reflect the style
used by the kernel, rather than the current wording which is wishful
thinking and misleading, and comes from the same school of thought that
gets off on prescriptive grammar, latin and comp.std.c
Signed-off-by: Alan Cox <alan@redhat.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
