Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1750861AbdIQElx (ORCPT ); Sun, 17 Sep 2017 00:41:53 -0400 Received: from mx0a-001b2d01.pphosted.com ([148.163.156.1]:46690 "EHLO mx0a-001b2d01.pphosted.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750744AbdIQElv (ORCPT ); Sun, 17 Sep 2017 00:41:51 -0400 Date: Sat, 16 Sep 2017 21:41:45 -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: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.21 (2010-09-15) X-TM-AS-GCONF: 00 x-cbid: 17091704-0040-0000-0000-000003A349F3 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.00918150; UDB=6.00461181; IPR=6.00698375; BA=6.00005592; NDR=6.00000001; ZLA=6.00000005; ZF=6.00000009; ZB=6.00000000; ZP=6.00000000; ZH=6.00000000; ZU=6.00000002; MB=3.00017185; XFM=3.00000015; UTC=2017-09-17 04:41:48 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 17091704-0041-0000-0000-000007984D01 Message-Id: <20170917044145.GZ3521@linux.vnet.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:,, definitions=2017-09-17_03:,, 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-1709170067 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 3333 Lines: 95 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? Thanx, Paul > .. kernel-doc:: include/linux/rcutree.h > :external: > ./Documentation/core-api/kernel-api.rst:363: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: kernel/rcu/tree.c > :external: > ./Documentation/core-api/kernel-api.rst:366: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: kernel/rcu/tree_plugin.h > :external: > ./Documentation/core-api/kernel-api.rst:369: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: kernel/rcu/tree_exp.h > :external: > ./Documentation/core-api/kernel-api.rst:372: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: kernel/rcu/update.c > :external: > ./Documentation/core-api/kernel-api.rst:375: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: include/linux/srcu.h > :external: > ./Documentation/core-api/kernel-api.rst:378: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: kernel/rcu/srcutree.c > :external: > ./Documentation/core-api/kernel-api.rst:381: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: include/linux/rculist_bl.h > :external: > ./Documentation/core-api/kernel-api.rst:384: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: include/linux/rculist.h > :external: > ./Documentation/core-api/kernel-api.rst:387: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: include/linux/rculist_nulls.h > :external: > ./Documentation/core-api/kernel-api.rst:390: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: include/linux/rcu_sync.h > :external: > ./Documentation/core-api/kernel-api.rst:393: ERROR: Error in "kernel-doc" directive: > unknown option: "external". > > .. kernel-doc:: kernel/rcu/sync.c > :external: > > ../kernel/rcu/tree.c:3091: ERROR: Unexpected indentation. > ../kernel/rcu/tree.c:3118: ERROR: Unexpected indentation. > ../kernel/rcu/tree.c:3119: WARNING: Bullet list ends without a blank line; unexpected unindent. > > > -- > ~Randy >