summaryrefslogtreecommitdiff
path: root/Documentation/CodingStyle
AgeCommit message (Collapse)Author
2016-09-21docs: Remove space-before-label guidance from CodingStyleJonathan Corbet
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>
2016-09-20Documentation/HOWTO: add cross-references to other documentsMauro Carvalho Chehab
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>
2016-09-20Documentation/CodingStyle: use the .. note:: markup where neededMauro Carvalho Chehab
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>
2016-09-20Documentation/CodingStyle: replace underline markupsMauro Carvalho Chehab
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>
2016-09-20Documentation/CodingStyle: use the proper tag for verbatim fontMauro Carvalho Chehab
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>
2016-09-20Documentation/CodingStyle: Convert to ReST markupMauro Carvalho Chehab
- 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>
2016-08-14CodingStyle: Remove "Don't use C99-style comments"Joe Perches
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>
2016-08-14CodingStyle: Clarify and complete chapter 7Jean Delvare
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>
2016-07-20docs: deprecate kernel-doc-nano-HOWTO.txtJonathan Corbet
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>
2016-01-25Documentation/CodingStyle: add space before parenthesis in example macroThomas Gardner
Signed-off-by: Thomas Gardner <tmg@fastmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-01-11Documentation: fix typo in CodingStyleManuel Pégourié-Gonnard
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>
2015-07-10Documentation: CodingStyle: remove broken links in the References sectionOlivier C. Larocque
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>
2015-05-07Documentation/CodingStyle: fix example macro parenthesis imbalanceBaruch Siach
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>
2015-04-18Merge tag 'docs-for-linus' of git://git.lwn.net/linux-2.6Linus Torvalds
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 ...
2015-04-17documentation: update CodingStyle on local variables naming in macrosBartosz Golaszewski
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>
2015-02-27Documentation/CodingStyle: improve text layoutPavel Kretov
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>
2015-02-27Documentation/CodingStyle: fix tab-spaces mixturePavel Kretov
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>
2015-01-28CodingStyle: enable emacs display of trailing whitespaceAlison Chaiken
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>
2014-12-02CodingStyle: add some more error handling guidelinesDan Carpenter
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>
2014-11-03CodingStyle: Add a chapter on conditional compilationJosh Triplett
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>
2014-08-26CodingStyle: fix a minor typoRaymond L. Rivera
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>
2014-06-04Documentation: expand/clarify debug documentationDan Streetman
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>
2013-07-03Documentation/CodingStyle: allow multiple return statements per functionDan Carpenter
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>
2013-01-11Documentation: remove depends on CONFIG_EXPERIMENTALKees Cook
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>
2012-10-06CodingStyle: add networking specific block comment styleJoe Perches
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>
2012-05-31CodingStyle: add kmalloc_array() to memory allocatorsXi Wang
Add the new kmalloc_array() to the list of general-purpose memory allocators in chapter 14. Signed-off-by: Xi Wang <xi.wang@gmail.com> Acked-by: Jesper Juhl <jj@chaosbits.net> Acked-by: Pekka Enberg <penberg@kernel.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2012-03-30Documentation: CodingStyle: add inline assembly guidelinesJosh Triplett
Signed-off-by: Josh Triplett <josh@joshtriplett.org> Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2011-11-04Documentation: update CodingStyle use of bracesAntonio Ospite
After commit 38829dc9d7b4 ("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>
2011-08-06CodingStyle: Document the exception of not splitting user-visible strings, ↵Josh Triplett
for grepping 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%3e Signed-off-by: Josh Triplett <josh@joshtriplett.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2011-07-06Documentation: update CodingStyle memory allocatorsJesper Juhl
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>
2011-03-22Documentation/CodingStyle: flesh out if-else examplesHarry Wei
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>
2011-03-16Documentation: update header filename in CodingStyleRoland Kammerer
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: Roland Kammerer <dev.rck@gmail.com> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Acked-by: Harry Wei <harryxiyou@gmail.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-06-12trivial: fix typo milisecond/millisecond for documentation and source comments.Martin Olsson
Signed-off-by: Martin Olsson <martin@minimum.se> Signed-off-by: Jiri Kosina <jkosina@suse.cz>
2009-01-29fix emacs indenting howto filename expansionDan Carpenter
I don't think emacs understands tilde expansion, so use "expand-file-name" to do that. Signed-off-by: Dan Carpenter <error27@gmail.com> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-01-29Documentation: update CodingStyle tips for Emacs usersTeemu Likonen
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>
2008-07-25documentation: update CodingStyle tips for Emacs usersJohannes Weiner
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: Johannes Weiner <hannes@saeurebad.de> Cc: Jonathan Corbet <corbet@lwn.net> 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>
2007-10-17CodingStyle: relax the 80-cole ruleAlan Cox
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>
2007-07-18dev_vdbg() documentationDavid Brownell
Update CodingStyle to talk about "-DDEBUG" message conventions and the new "-DVERBOSE_DEBUG" convention. Signed-off-by: David Brownell <dbrownell@users.sourceforge.net> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
2007-07-16CodingStyle: add information about editor modelinesJosh Triplett
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: Josh Triplett <josh@freedesktop.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-07-16CodingStyle: add information about trailing whitespaceJosh Triplett
Signed-off-by: Josh Triplett <josh@kernel.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-05-23Documentation: fix the explanation of Kconfig filesRobert P. J. Day
Fix the obvious errors in the explanation of Kconfig files. Signed-off-by: Robert P. J. Day <rpjday@mindspring.com> 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>
2007-05-08Fix chapter reference in CodingStyleJesper Juhl
commit 226a6b84aaaf1fac7a5d41cf4e7387fd9ba895d5 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: Jesper Juhl <jesper.juhl@gmail.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-05-08CodingStyle: start flamewar about use of bracesOliver Neukum
Signed-off-by: Oliver Neukum <oneukum@suse.de> Cc: Tilman Schmidt <tilman@imap.cc> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2006-12-22[PATCH] Add a new section to CodingStyle, promoting include/linux/kernel.hRobert P. J. Day
Add a new section to the CodingStyle file, encouraging people not to re-invent available kernel macros such as ARRAY_SIZE(), FIELD_SIZEOF(), min() and max(), among others. Signed-off-by: Robert P. J. Day <rpjday@mindspring.com> Acked-by: Randy Dunlap <randy.dunlap@oracle.com> Acked-by: Jan Engelhardt <jengelh@gmx.de> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-12-10[PATCH] CodingStyle updatesRandy Dunlap
Add some kernel coding style comments, mostly pulled from emails by Andrew Morton, Jesper Juhl, and Randy Dunlap. - add paragraph on switch/case indentation (with fixes) - add paragraph on multiple-assignments - add more on Braces - add section on Spaces; add typeof, alignof, & __attribute__ with sizeof; add more on postfix/prefix increment/decrement operators - add paragraph on function breaks in source files; add info on function prototype parameter names - add paragraph on EXPORT_SYMBOL placement - add section on /*-comment style, long-comment style, and data declarations and comments - correct some chapter number references that were missed when chapters were renumbered Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Acked-by: Jesper Juhl <jesper.juhl@gmail.com> Acked-by: Jan Engelhardt <jengelh@gmx.de> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-09-29[PATCH] Add section on function return values to CodingStyleAlan Stern
This patch (as776) adds a new chapter to Documentation/CodingStyle, explaining the circumstances under which a function should return 0 for failure and non-zero for success as opposed to a negative error code for failure and 0 for success. Signed-off-by: Alan Stern <stern@rowland.harvard.edu> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-06-23[PATCH] CodingStyle: add typedefs chapterRandy Dunlap
Add a chapter on typedefs, copied from an email from Linus to lkml on Feb. 3, 2006. (Subject: Re: [RFC][PATCH 1/5] Virtualization/containers: startup) Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-01-10[PATCH] CodingStyle correctionJesper Juhl
Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-01-08[PATCH] Add a section about inlining to Documentation/CodingStyleArjan van de Ven
Adds a bit of text to Documentation/Codingstyle to state that inlining everything "just because" is a bad idea Signed-off-by: Arjan van de Ven <arjan@infradead.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-01-08[PATCH] docs: updated some code docsXose Vazquez Perez
Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>