Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <9fc9759d-ac74-ca8f-874c-5058758c3ea1@redhat.com>
Date:   Thu, 22 Sep 2022 16:41:49 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.2.1
Content-Language: en-US
To:     Akira Yokosawa <akiyks@gmail.com>
Cc:     David.Laight@ACULAB.COM, akpm@linux-foundation.org,
        apw@canonical.com, bhe@redhat.com, christophe.leroy@csgroup.eu,
        corbet@lwn.net, dwaipayanray1@gmail.com, dyoung@redhat.com,
        jani.nikula@linux.intel.com, joe@perches.com,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        linux-mm@kvack.org, linuxppc-dev@lists.ozlabs.org,
        lukas.bulwahn@gmail.com, mingo@kernel.org, mpe@ellerman.id.au,
        npiggin@gmail.com, torvalds@linux-foundation.org, vgoyal@redhat.com
References: <20220920122302.99195-2-david@redhat.com>
 <93343c05-f31e-cfbe-6650-8ea8d79e6d55@gmail.com>
From:   David Hildenbrand <david@redhat.com>
Organization: Red Hat
Subject: Re: [PATCH v1 1/3] coding-style.rst: document BUG() and WARN() rules
 ("do not crash the kernel")
In-Reply-To: <93343c05-f31e-cfbe-6650-8ea8d79e6d55@gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Precedence: bulk

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