Re: [PATCH v1 1/3] coding-style.rst: document BUG() and WARN() rules ("do not crash the kernel")

[David Hildenbrand]

> >   
> > +22) Do not crash the kernel
> > +---------------------------
> > +
> > +In general, it is not the kernel developer's decision to crash the kernel.
> > +
> > +Avoid panic()
> > +=============
> This looks to me like a subsection-level title.  The adornment symbol
> needs to be:
>
>     *************
>
> > +
> > +panic() should be used with care and primarily only during system boot.
> > +panic() is, for example, acceptable when running out of memory during boot and
> > +not being able to continue.
> > +
> > +Use WARN() rather than BUG()
> > +============================
> Ditto.
>
> > +
> > +Do not add new code that uses any of the BUG() variants, such as BUG(),
> > +BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably
> > +WARN_ON_ONCE(), and possibly with recovery code. Recovery code is not
> > +required if there is no reasonable way to at least partially recover.
> > +
> > +"I'm too lazy to do error handling" is not an excuse for using BUG(). Major
> > +internal corruptions with no way of continuing may still use BUG(), but need
> > +good justification.
> > +
> > +Use WARN_ON_ONCE() rather than WARN() or WARN_ON()
> > +**************************************************
> These wrong adornment symbol confuse ReST parser of Sphinx and results in
> the build error from "make htmldocs" at this title (long message folded):


Thanks,

the following on top should do the trick:


diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index e05899cbfd49..9efde65ac2f3 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -1192,14 +1192,14 @@ expression used.  For instance:
 In general, it is not the kernel developer's decision to crash the kernel.
 
 Avoid panic()
-=============
+*************
 
 panic() should be used with care and primarily only during system boot.
 panic() is, for example, acceptable when running out of memory during boot and
 not being able to continue.
 
 Use WARN() rather than BUG()
-============================
+****************************
 
 Do not add new code that uses any of the BUG() variants, such as BUG(),
 BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably


--
Thanks,

David / dhildenb