Received: by 10.192.165.148 with SMTP id m20csp227730imm; Wed, 9 May 2018 11:36:13 -0700 (PDT) X-Google-Smtp-Source: AB8JxZoWxcrUYSWuIjgGurnr1VGhbnuzLuDGWlXtRR9wQOKFnZqVZhm5qfbBkSrbYmPElVvOXszV X-Received: by 10.98.159.21 with SMTP id g21mr43981918pfe.207.1525890973629; Wed, 09 May 2018 11:36:13 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1525890973; cv=none; d=google.com; s=arc-20160816; b=MEIHlOzjihwVQCDK8DVwoNG0ZtpejZf3epzK7OgFXcv7YsxeMpxOUyX9amsq4+sVqX B/SR72PxexgttfTmKz3Jb5hKNVei804aL9V4poPGZiNX4/vIt3Mxw91sgdevIB3mbl+i ubt7CdKQhWQWDQqODjSzBBJG7++tgWswwj7bPc6+NEmHQCnnxVeB4URXG2+Jc/PgKcLi /pPtKnWlQWhl7DiFjnCr4lHkE4Dj5HcPDuxUxxf5k4TQxBRRaPncKlj4xmJA+AArUY2V DLSMCkq9vTlRlKFkW6opaM9mbbnrE6F+Rs6M9TWopXC0c3AYYV/2FaHEjNiDQztionTd J5dw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :organization:references:in-reply-to:message-id:subject:cc:to:from :date:arc-authentication-results; bh=zkTQ0lXtLo1pSJztsJa6fztsAiZi2VSSIVi9VJztpGE=; b=tCGUkyY2WMbM/2hggiM3jp4GviIJDSJOvb7C30fxGO+7t8P7ryPvrBToaHAOmQ//Dr eQd+HYntwJTo/iyNB/hYL0n051fECKebFN10oCH9Da1Qpbn4cla8C1n8P0bMBv8jFlcf 9XfoQkEJlRy5JmslofRlDBM6dSU8xjKtOclobzeUZWaP/b9Xj8KQOdbAwTtIgKCxp8z9 LOqP0gPJHfrxgHSx9SCI+XCVm1UeoEVhGWwJaQaX+knxwPF4Rs1LoJO64koxuee3jQp0 LWhRetFCfN1rF6683auElAV1w8y8jRTq+j2vkd/2yalC5uvZqV2scvitLAXRQqGx1Yd7 j+6Q== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id 97-v6si26917483ple.426.2018.05.09.11.35.58; Wed, 09 May 2018 11:36:13 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S935545AbeEISfp (ORCPT + 99 others); Wed, 9 May 2018 14:35:45 -0400 Received: from ms.lwn.net ([45.79.88.28]:43084 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933577AbeEISfn (ORCPT ); Wed, 9 May 2018 14:35:43 -0400 Received: from localhost.localdomain (localhost [127.0.0.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id CE365318; Wed, 9 May 2018 18:35:42 +0000 (UTC) Date: Wed, 9 May 2018 12:35:40 -0600 From: Jonathan Corbet To: Peter Zijlstra Cc: Mauro Carvalho Chehab , Linux Doc Mailing List , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Ingo Molnar Subject: Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings Message-ID: <20180509123540.083b61d2@lwn.net> In-Reply-To: <20180509152026.GA12198@hirez.programming.kicks-ass.net> References: <6b9b3184cbfabab1ad89c974ddf1c61631e8f1bf.1525684985.git.mchehab+samsung@kernel.org> <20180509084120.GF12217@hirez.programming.kicks-ass.net> <20180509084518.247650e2@lwn.net> <20180509152026.GA12198@hirez.programming.kicks-ass.net> Organization: LWN.net X-Mailer: Claws Mail 3.15.1-dirty (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 9 May 2018 17:20:26 +0200 Peter Zijlstra wrote: > The whole rst wankery is detrimental to that interface in order to > pander to something else.. I don't see the value. I've objected before, > and I suppose I'll object again. One person's wankery is another's integrated, browsable, and searchable documentation that shows some signs of having actually been thought about, I guess. > > It's a simple colon. It goes along with the /** marker for kerneldoc > > comments and the @ markers found within them, both of which you seem to > > have found a way to live with. > > Barely, and personally I tend to not bother with kerneldoc much. Most of > the comments I write lack the extra *, and I note that the other fix to > this problem it to drop that spurious * here as well. Perhaps you'd like to post a patch removing the kerneldoc mechanism? It would make my life a lot easier...:) > The @arg thing is okay, it clearly distinguishes arguments/variable > names from regular text. But "::" is the C++ class member syntax, not > the start of an English enumeration or the like. Not sure what C++ has to do with anything, unless we want to bring in $LANGUAGE_WE_DISRESPECT spuriously. I'm sure it's the Perl do-five-different-things-magically syntax too. It's probably an entire natural-language processing system in Haskell. It also happens to be the Sphinx "start literal block" syntax. > > You're not the only consumer of the docs. You may not appreciate the > > improvements that have come, but others certainly do. I do hope that you > > can find it in youself to avoid vandalizing things for everybody else ...? > > Why should I care for people not using text editors to write code? The set of "people using text editors to write code" is a superset of the set containing only Peter Zijlstra. Many of the people who have used text editors to write the very code we all work on find a minimally structured documentation system to be useful. Out of respect for them, if nothing else, I'll ask again, please, that you suffer the substantial cognitive drain of skipping over an extra colon. Thanks, jon