Received: by 10.192.165.148 with SMTP id m20csp1304615imm; Thu, 10 May 2018 08:39:44 -0700 (PDT) X-Google-Smtp-Source: AB8JxZpFQjnSPCDHQXZlt8HSnIsNrAXAo41u6+dsoaFP87z21u8wtXR747bR4t8G0CuOGNhvkGtC X-Received: by 2002:a17:902:d24:: with SMTP id 33-v6mr1859502plu.22.1525966784274; Thu, 10 May 2018 08:39:44 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1525966784; cv=none; d=google.com; s=arc-20160816; b=PqrOL+SWcMttc01QQzHr63fB1ZXFo9IIFukWU+/c2aWsQm4knsbgOPb1oNsgfi+zfi UD9gG57n4FKZL2lG88PsEZXjV6tf5jYFm/B8Qv73CAkPnfM3c1iQziOt9KIEtLsqJ1Es Mqgx9WlHbwrMEibtiZ+X7vSDt+t+DiBYNocMBUENObga9toGpY1ca+lGRYMRV+wOe2Zl LcAw/p66pDcHz2g06W8aihoZaC4W/8WQdke6Lg8gD27dk9ZJU/HLzEw6dex47VUKewrO OhK9DOyanw8JSWGI6Hc7KcmFqMW91fFQhqBin7/7IDRoZYTtkUnjnkz0EUs6sAfh6cPU dA8g== 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=tBFOc/XMQg4FWjlaNOL90FDxFKf5YWusVKZTZ7fv+fE=; b=MFfPDbIPEIiuVAEYJ8+dnMhNwIH/hgoyaKcnSVcl7qe1UoC2Heqtmcjb4+QdwK6BdB 6kgwRmwBJYwzPK5m395pojW9u+9O3IRbGFSC/R7OM/igpn4xPYUBiZ2W0FUJpAxQP3K6 Wpr4bKe/OTRi1qUn/3KjsfszF+ZuxMd7Fn1v47Pj/Jv+WTd3ILLpcQ3FNARKKO9+O5Cb 9k5yI1QVb0mtWguXffdgb4+GmXzTZHuDHJivHBpjQdIgX5lfaOWeBASZzk+Oj4C7byAk s2oRDe2vDoCIoL+9OWdiwBbptL/6n/s1su10RGfA+73Z7qCT25WepJm1VFvprDbxhD5L m58w== 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 k17-v6si1031479pfj.310.2018.05.10.08.39.29; Thu, 10 May 2018 08:39:44 -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 S966357AbeEJPiv (ORCPT + 99 others); Thu, 10 May 2018 11:38:51 -0400 Received: from ms.lwn.net ([45.79.88.28]:57732 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S966209AbeEJPiu (ORCPT ); Thu, 10 May 2018 11:38:50 -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 1EEA8308; Thu, 10 May 2018 15:38:49 +0000 (UTC) Date: Thu, 10 May 2018 09:38:46 -0600 From: Jonathan Corbet To: Mauro Carvalho Chehab Cc: Christoph Hellwig , Linux Doc Mailing List , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Ingo Molnar , Peter Zijlstra Subject: Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings Message-ID: <20180510093846.184f6de0@lwn.net> In-Reply-To: <20180510112113.4db65764@vento.lan> References: <6b9b3184cbfabab1ad89c974ddf1c61631e8f1bf.1525684985.git.mchehab+samsung@kernel.org> <20180510083838.GA21846@infradead.org> <20180510063805.1859b1aa@vento.lan> <20180510073012.5902088e@lwn.net> <20180510112113.4db65764@vento.lan> 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 Thu, 10 May 2018 11:21:13 -0300 Mauro Carvalho Chehab wrote: > The problem with a hint-based mechanism is that it will generate > false hints. If added, we may end by needing to add extra tags to > disable the hints mechanism where it gets wrong, or to periodically > do code changes at kernel-doc comments in order to make the hints > logic happy. > > So, IMO, we should provide non-hints based mechanism, like forcing the > string that prepends the colon to have a keyword that will make it to > parse the block as literal, where expressions like: > > See the code-block foo: > See the following code example: > See the following flow diagram: > See the following artwork: > > Is the best alternative to avoid "::", as on the enclosed patch. But this, too, is a hint-based mechanism. Thanks for the patches, I'll keep them around, but I would like an opportunity to try to do better before applying them. I fear that using magic words in this way will lead to a constant stream of surprises, and I'd like to avoid that if possible... Thanks, jon