doc: re-add CodingStyle and SubmittingPatches

Those files got moved to Documentation/process, but as they're very
well known files, add pointers to their new locations.

PS.: I opted to not merge th

doc: re-add CodingStyle and SubmittingPatches

Those files got moved to Documentation/process, but as they're very
well known files, add pointers to their new locations.

PS.: I opted to not merge this patch with the previous one
in order to make the diff of the previous one more consistent,
as it will show only renames.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

show more ...

docs: Remove space-before-label guidance from CodingStyle

Recent discussion has made it clear that there is no community consensus on
this particular rule. Remove it now, lest it inspire yet anothe

docs: Remove space-before-label guidance from CodingStyle

Recent discussion has made it clear that there is no community consensus on
this particular rule. Remove it now, lest it inspire yet another set of
unwanted "cleanup" patches.

This partially reverts 865a1caa4b6b (CodingStyle: Clarify and complete
chapter 7).

Cc: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

Documentation/HOWTO: add cross-references to other documents

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

It should

Documentation/HOWTO: add cross-references to other documents

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

Documentation/CodingStyle: use the .. note:: markup where needed

There are two places there where there are notes that should
be highlighted. So, use the ReST note markup for such texts.

Signed-off

Documentation/CodingStyle: use the .. note:: markup where needed

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

Documentation/CodingStyle: replace underline markups

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 outpu

Documentation/CodingStyle: replace underline markups

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

Documentation/CodingStyle: use the proper tag for verbatim font

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

Documentation/CodingStyle: use the proper tag for verbatim font

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

Documentation/CodingStyle: Convert to ReST markup

- Fix all chapter identation;
- add c blocks where needed;

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan

Documentation/CodingStyle: Convert to ReST markup

- Fix all chapter identation;
- add c blocks where needed;

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

CodingStyle: Remove "Don't use C99-style comments"

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

CodingStyle: Remove "Don't use C99-style comments"

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.com

Signed-off-by: Joe Perches <joe@perches.com>

show more ...

CodingStyle: Clarify and complete chapter 7

Chapter 7 (Centralized exiting of functions) of the coding style
documentation is unclear at times, and lacks some information (such
as the possibility to

CodingStyle: Clarify and complete chapter 7

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: Jean Delvare <jdelvare@suse.de>
Cc: Markus Elfring <elfring@users.sourceforge.net>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

docs: deprecate kernel-doc-nano-HOWTO.txt

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 on

docs: deprecate kernel-doc-nano-HOWTO.txt

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: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

Documentation/CodingStyle: add space before parenthesis in example macro

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

Documentation: fix typo in CodingStyle

Simple typo: "it" for "is".

Signed-off-by: Manuel Pégourié-Gonnard <mpg@elzevir.fr>
Cc: Trivial Patch Monkey <trivial@kernel.org>
Signed-off-by: Jonathan Corb

Documentation: fix typo in CodingStyle

Simple typo: "it" for "is".

Signed-off-by: Manuel Pégourié-Gonnard <mpg@elzevir.fr>
Cc: Trivial Patch Monkey <trivial@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

Documentation: CodingStyle: remove broken links in the References section

Remove 2 broken links for programming reference books in Appendix I. After
a lookup on an Internet archives web site, it see

Documentation: CodingStyle: remove broken links in the References section

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: Olivier C. Larocque <olivier.c.larocque@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

show more ...

Documentation/CodingStyle: fix example macro parenthesis imbalance

Cc: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Cc: Andrew Morton <akpm@linux-foundation.org>
Fixes: f2027543b9 ('documentation

Documentation/CodingStyle: fix example macro parenthesis imbalance

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

show more ...

documentation: update CodingStyle on local variables naming in macros

Describe proper naming convention for local variables in macros
resembling functions.

Signed-off-by: Bartosz Golaszewski <bgola

documentation: update CodingStyle on local variables naming in macros

Describe proper naming convention for local variables in macros
resembling functions.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Cc: Guenter Roeck <linux@roeck-us.net>
Cc: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

show more ...

Documentation/CodingStyle: improve text layout

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

Documentation/CodingStyle: improve text layout

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>

show more ...

Documentation/CodingStyle: fix tab-spaces mixture

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
o

Documentation/CodingStyle: fix tab-spaces mixture

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>

show more ...

CodingStyle: enable emacs display of trailing whitespace

Suggest to developers who use emacs that they turn on the
instantaneous trailing-whitespace warning feature.

Signed-off-by: Alison Chaiken <

CodingStyle: enable emacs display of trailing whitespace

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>

show more ...

CodingStyle: add some more error handling guidelines

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

CodingStyle: add some more error handling guidelines

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>

show more ...

CodingStyle: Add a chapter on conditional compilation

Document several common practices and conventions regarding conditional
compilation, most notably the preference for ifdefs in headers rather
th

CodingStyle: Add a chapter on conditional compilation

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>

show more ...

CodingStyle: fix a minor typo

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>
Sig

CodingStyle: fix a minor typo

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>

show more ...

Documentation: expand/clarify debug documentation

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 d

Documentation: expand/clarify debug documentation

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>

show more ...

Documentation/CodingStyle: allow multiple return statements per function

A surprising number of newbies interpret this section to mean that only
one return statement is allowed per function. Part o

Documentation/CodingStyle: allow multiple return statements per function

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>

show more ...

Documentation: remove depends on CONFIG_EXPERIMENTAL

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
Li

Documentation: remove depends on CONFIG_EXPERIMENTAL

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: Kees Cook <keescook@chromium.org>
Acked-by: Jason Wessel <jason.wessel@windriver.com>

show more ...

CodingStyle: add networking specific block comment style

The block comment style in net/ and drivers/net is non-standard.
Document it.

Signed-off-by: Joe Perches <joe@perches.com>
Cc: "Allan, Bruce

CodingStyle: add networking specific block comment style

The block comment style in net/ and drivers/net is non-standard.
Document it.

Signed-off-by: Joe 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: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

show more ...