Add cross references for the documents mentioned at HOWTO and
are under the Documentation/ directory, using the ReST notation.

It should be noticed that HOWTO also mentions the /README file.
We opted to not touch it, for now, as making it build on
Sphinx would require it to be moved to a Documentation/foo
directory.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There are two places there where there are notes that should
be highlighted. So, use the ReST note markup for such texts.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Sphinx doesn't accept underline markups by purpose.
While there are ways to support underline via CSS, this won't
be portable with non-html outputs.

As we want CodingStyle to do emphasis, replace _foo_ by **foo**,
using bold emphasis.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

On Sphinx/ReST notation, ``foo`` means that foo will be will be
marked as inline literal, effectively making it to be presented
as a monospaced font.

As we want this document to be parsed by Sphinx, instead of using
"foo", use ``foo`` for the names that are literal, because it is an
usual typographic convention to use monospaced fonts for functions
and language commands on documents, and we're following such
convention on the other ReST books.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

- Fix all chapter identation;
- add c blocks where needed;
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Because Linus may still be reading source code on greenbar paper
instead of color terminals with code syntax highlighting and
appropriate font decorations.

Link: http://lkml.kernel.org/r/CA+55aFyQYJerovMsSoSKS7PessZBr4vNp-3QUUwhqk4A4_jcbg@mail.gmail.comSigned-off-by: NJoe Perches <joe@perches.com>

Chapter 7 (Centralized exiting of functions) of the coding style
documentation is unclear at times, and lacks some information (such
as the possibility to indent labels with a single space.) Clarify and
complete it.
Signed-off-by: NJean Delvare <jdelvare@suse.de>
Cc: Markus Elfring <elfring@users.sourceforge.net>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Now that the new Sphinx world order is taking over, the information in
kernel-doc-nano-HOWTO.txt is outmoded.  I hate to remove it altogether,
since it's one of those files that people expect to find.  But we can add a
warning and fix all the other pointers to it.
Reminded-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NThomas Gardner <tmg@fastmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Simple typo: "it" for "is".
Signed-off-by: NManuel Pégourié-Gonnard <mpg@elzevir.fr>
Cc: Trivial Patch Monkey <trivial@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Remove 2 broken links for programming reference books in Appendix I. After
a lookup on an Internet archives web site, it seems that these links have
been broken for around 3 months. We can then assume that they will not be
back up and safely remove them from the documentation.
Signed-off-by: NOlivier C. Larocque <olivier.c.larocque@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Cc: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Cc: Andrew Morton <akpm@linux-foundation.org>
Fixes: f2027543 ('documentation: update CodingStyle on local variables naming in macros')
Signed-off-by: NBaruch Siach <baruch@tkos.co.il>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Describe proper naming convention for local variables in macros
resembling functions.
Signed-off-by: NBartosz Golaszewski <bgolaszewski@baylibre.com>
Cc: Guenter Roeck <linux@roeck-us.net>
Cc: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

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: NPavel Kretov <firegurafiku@gmail.com>
Signed-off-by: NJonathan 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: NPavel Kretov <firegurafiku@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Suggest to developers who use emacs that they turn on the
instantaneous trailing-whitespace warning feature.
Signed-off-by: NAlison Chaiken <alison_chaiken@mentor.com>
[jc: untabified to match its surroundings]
Signed-off-by: NJonathan 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: NDan Carpenter <dan.carpenter@oracle.com>
Acked-by: NJulia Lawall <julia.lawall@lip6.fr>
[jc: added GFP_KERNEL to kmalloc() call]
Signed-off-by: NJonathan 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: NJosh Triplett <josh@joshtriplett.org>
Acked-by: NGeert Uytterhoeven <geert@linux-m68k.org>
Signed-off-by: NJonathan 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: NRaymond L. Rivera <ray.l.rivera@gmail.com>
Signed-off-by: NJiri 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: NDan Streetman <ddstreet@ieee.org>
Cc: Joe Perches <joe@perches.com>
Cc: Fabian Frederick <fabf@skynet.be>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NDan Carpenter <dan.carpenter@oracle.com>
Cc: Eduardo Valentin <eduardo.valentin@ti.com>
Cc: Rob Landley <rob@landley.net>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

The CONFIG_EXPERIMENTAL config item has not carried much meaning for a
while now and is almost always enabled by default. As agreed during the
Linux kernel summit, remove it from any "depends on" lines in Kconfigs.

CC: Rob Landley <rob@landley.net>
CC: Jiri Kosina <jkosina@suse.cz>
CC: Masanari Iida <standby24x7@gmail.com>
CC: Jason Wessel <jason.wessel@windriver.com>
CC: Richard L Maliszewski <richard.l.maliszewski@intel.com>
CC: Gang Wei <gang.wei@intel.com>
CC: Shane Wang <shane.wang@intel.com>
CC: Harry Wei <harryxiyou@gmail.com>
Signed-off-by: NKees Cook <keescook@chromium.org>
Acked-by: NJason Wessel <jason.wessel@windriver.com>

The block comment style in net/ and drivers/net is non-standard.
Document it.
Signed-off-by: NJoe Perches <joe@perches.com>
Cc: "Allan, Bruce W" <bruce.w.allan@intel.com>
Cc: Andy Whitcroft <apw@canonical.com>
Cc: David Miller <davem@davemloft.net>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Add the new kmalloc_array() to the list of general-purpose memory
allocators in chapter 14.
Signed-off-by: NXi Wang <xi.wang@gmail.com>
Acked-by: NJesper Juhl <jj@chaosbits.net>
Acked-by: NPekka Enberg <penberg@kernel.org>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Signed-off-by: NJosh Triplett <josh@joshtriplett.org>
Signed-off-by: NRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

After commit 38829dc9 ("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: NAntonio Ospite <ospite@studenti.unina.it>
Signed-off-by: NRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Patch reviewers now recommend not splitting long user-visible strings,
such as printk messages, even if they exceed 80 columns.  This avoids
breaking grep.  However, that recommendation did not actually appear
anywhere in Documentation/CodingStyle.

See, for example, the thread at
  http://news.gmane.org/find-root.php?message_id=%3c1312215262.11635.15.camel%40Joe%2dLaptop%3eSigned-off-by: NJosh Triplett <josh@joshtriplett.org>
Signed-off-by: NLinus 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: NJesper Juhl <jj@chaosbits.net>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NLinus 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: NHarry Wei <harryxiyou@gmail.com>
Cc: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

pr_info() and pr_debug() are in linux/printk.h, not linux/kernel.h.
Last updated is unnecessary, we have git for that.
Signed-off-by: NRoland Kammerer <dev.rck@gmail.com>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Acked-by: NHarry Wei <harryxiyou@gmail.com>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Signed-off-by: NMartin Olsson <martin@minimum.se>
Signed-off-by: NJiri Kosina <jkosina@suse.cz>

I don't think emacs understands tilde expansion, so use
"expand-file-name" to do that.
Signed-off-by: NDan Carpenter <error27@gmail.com>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NLinus 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: NTeemu Likonen <tlikonen@iki.fi>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Describe a setup that integrates better with Emacs' cc-mode and also fixes
up the alignment of continuation lines to really only use tabs.
Signed-off-by: NJohannes Weiner <hannes@saeurebad.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NAlan Cox <alan@redhat.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Update CodingStyle to talk about "-DDEBUG" message conventions and the
new "-DVERBOSE_DEBUG" convention.
Signed-off-by: NDavid Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NGreg Kroah-Hartman <gregkh@suse.de>

I recently received a patch including a file that had a vim modeline,
and I realized that nothing specifically proscribed that practice.
Signed-off-by: NJosh Triplett <josh@freedesktop.org>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Signed-off-by: NJosh Triplett <josh@kernel.org>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Fix the obvious errors in the explanation of Kconfig files.
Signed-off-by: NRobert P. J. Day <rpjday@mindspring.com>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

commit 226a6b84 renumbered Chapter 11 in
Documentation/CodingStyle to Chapter 12, but it didn't update the reference
to that chapter further down in the file.  This patch corrects the chapter
reference.
Signed-off-by: NJesper Juhl <jesper.juhl@gmail.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>