Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751715AbdIQRrW (ORCPT ); Sun, 17 Sep 2017 13:47:22 -0400 Received: from mx0a-001b2d01.pphosted.com ([148.163.156.1]:43448 "EHLO mx0a-001b2d01.pphosted.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751554AbdIQRrU (ORCPT ); Sun, 17 Sep 2017 13:47:20 -0400 Date: Sun, 17 Sep 2017 10:47:16 -0700 From: "Paul E. McKenney" To: Randy Dunlap Cc: LKML , "linux-doc@vger.kernel.org" , Jonathan Corbet Subject: Re: rcu kernel-doc issues (4.14-rc1) Reply-To: paulmck@linux.vnet.ibm.com References: <20170917044145.GZ3521@linux.vnet.ibm.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20170917044145.GZ3521@linux.vnet.ibm.com> User-Agent: Mutt/1.5.21 (2010-09-15) X-TM-AS-GCONF: 00 x-cbid: 17091717-0008-0000-0000-00000281A03B X-IBM-SpamModules-Scores: X-IBM-SpamModules-Versions: BY=3.00007754; HX=3.00000241; KW=3.00000007; PH=3.00000004; SC=3.00000229; SDB=6.00918412; UDB=6.00461338; IPR=6.00698637; BA=6.00005593; NDR=6.00000001; ZLA=6.00000005; ZF=6.00000009; ZB=6.00000000; ZP=6.00000000; ZH=6.00000000; ZU=6.00000002; MB=3.00017188; XFM=3.00000015; UTC=2017-09-17 17:47:18 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 17091717-0009-0000-0000-000036BB4C86 Message-Id: <20170917174716.GA3611@linux.vnet.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:,, definitions=2017-09-17_12:,, signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 spamscore=0 suspectscore=0 malwarescore=0 phishscore=0 adultscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1707230000 definitions=main-1709170258 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 2920 Lines: 104 On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote: > On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote: > > On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc: > > > > .. kernel-doc:: include/linux/rcupdate.h > > :external: > > ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive: > > unknown option: "external". > > $ grep external include/linux/rcupdate.h > * by a single external-to-structure RCU-protected pointer, then you may > * external-to-structure pointer -after- you have completely initialized > > Do these comments somehow qualify as an "external" option? If so, how > do I tell kernel-doc to ignore them? Or must I reword them to avoid > the word "external"? > > > .. kernel-doc:: include/linux/rcupdate_wait.h > > :external: > > ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive: > > unknown option: "external". > > $ grep external include/linux/rcupdate_wait.h > > There is no occurrence of the string "external" in this file. So this > "external" option is unknown to me as well. So, any hints on how I > should interpret these error messages? And thanks to Akira Yokosawa for pointing out my confusion in reading these error messages. The line numbers of course apply to the file Documentation/core-api/kernel-api.rst rather than the various RCU C-language source files. The patch below removes the error messages for me. Is this what you had in mind? (Might need other options at some point, but somewhere to start.) Thanx, Paul ------------------------------------------------------------------------ diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 8282099e0cbf..30b2666bf494 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -352,44 +352,44 @@ Read-Copy Update (RCU) ---------------------- .. kernel-doc:: include/linux/rcupdate.h - :external: + :export .. kernel-doc:: include/linux/rcupdate_wait.h - :external: + :export .. kernel-doc:: include/linux/rcutree.h - :external: + :export .. kernel-doc:: kernel/rcu/tree.c - :external: + :export .. kernel-doc:: kernel/rcu/tree_plugin.h - :external: + :export .. kernel-doc:: kernel/rcu/tree_exp.h - :external: + :export .. kernel-doc:: kernel/rcu/update.c - :external: + :export .. kernel-doc:: include/linux/srcu.h - :external: + :export .. kernel-doc:: kernel/rcu/srcutree.c - :external: + :export .. kernel-doc:: include/linux/rculist_bl.h - :external: + :export .. kernel-doc:: include/linux/rculist.h - :external: + :export .. kernel-doc:: include/linux/rculist_nulls.h - :external: + :export .. kernel-doc:: include/linux/rcu_sync.h - :external: + :export .. kernel-doc:: kernel/rcu/sync.c - :external: + :export