From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756974AbeAJEFG (ORCPT + 1 other); Tue, 9 Jan 2018 23:05:06 -0500 Received: from out3-smtp.messagingengine.com ([66.111.4.27]:40615 "EHLO out3-smtp.messagingengine.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751097AbeAJEFE (ORCPT ); Tue, 9 Jan 2018 23:05:04 -0500 X-ME-Sender: From: "Tobin C. Harding" To: Jonathan Corbet Cc: "Tobin C. Harding" , "Paul E. McKenney" , Josh Triplett , Linux docs , LKML Subject: [RFC] doc: fix code snippet build warnings Date: Wed, 10 Jan 2018 15:04:53 +1100 Message-Id: <1515557093-7036-1-git-send-email-me@tobin.cc> X-Mailer: git-send-email 2.7.4 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: Posting as RFC in the hope that someone knows how to massage sphinx correctly to fix this patch. Currently function kernel-doc contains a multi-line code snippet. This is causing sphinx to emit 5 build warnings WARNING: Unexpected indentation. WARNING: Unexpected indentation. WARNING: Block quote ends without a blank line; unexpected unindent. WARNING: Block quote ends without a blank line; unexpected unindent. WARNING: Inline literal start-string without end-string. And the snippet is not rendering correctly in HTML. We can stop shpinx complaining by using '::' instead of the currently used '``' however this still does not render correctly in HTML. The rendering is [arguably] better but still incorrect. Sphinx renders two function calls thus: :c:func:`rcu_read_lock()`; The rest of the snippet does however have correct spacing. Use '::' to pre-fix code snippet. Clears build warnings but does not render correctly. Signed-off-by: Tobin C. Harding --- To view current broken rendering see https://www.kernel.org/doc/html/latest/core-api/kernel-api.html?highlight=rcu_pointer_handoff#c.rcu_pointer_handoff include/linux/rcupdate.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h index a6ddc42f87a5..cc10e772e3e9 100644 --- a/include/linux/rcupdate.h +++ b/include/linux/rcupdate.h @@ -568,7 +568,8 @@ static inline void rcu_preempt_sleep_check(void) { } * is handed off from RCU to some other synchronization mechanism, for * example, reference counting or locking. In C11, it would map to * kill_dependency(). It could be used as follows: - * `` + * :: + * * rcu_read_lock(); * p = rcu_dereference(gp); * long_lived = is_long_lived(p); @@ -579,7 +580,6 @@ static inline void rcu_preempt_sleep_check(void) { } * p = rcu_pointer_handoff(p); * } * rcu_read_unlock(); - *`` */ #define rcu_pointer_handoff(p) (p) -- 2.7.4