Received: by 10.192.165.148 with SMTP id m20csp1376085imm; Thu, 10 May 2018 09:44:03 -0700 (PDT) X-Google-Smtp-Source: AB8JxZqfLSF/MkTFfgSszRiFRVhansKQXQuZrQx3nJafK7FdsFQsFzZYbzbOKgOgrBDOWXWiMU9z X-Received: by 2002:a17:902:1744:: with SMTP id i62-v6mr2068068pli.267.1525970643727; Thu, 10 May 2018 09:44:03 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1525970643; cv=none; d=google.com; s=arc-20160816; b=r5LKctMj7GkV+ZLAwKIeyNGEjlos7xR0Cw9Su0Mr2xzKlOL+kyfN0kw/yjEz1YPM/z cEShS9XwVqdztf9ESkzgqcGC9TXeaGQI1vburbqttSvpK67DgY29Pw30mukoE4q5SSPI fN4yrWvqz8kDw9VhYhWWQ2zE5SiZ8J0ikiIwIlFbJg1dTMRbSpL/4HEgG+5axS1hrGER Xqzxpe4Xzt4TadvZxFO6kKYYWWvQlfXVMCxLlwTuSOnf/rEbjtX4/WUpSAeBHSAIqkOs 5AQyxMKvoIDnPtWgOGFfNJNhZhTeeuThy+5mtry7kkS5D7iOREPeeSLTl+U+zOjp2V9+ MaaQ== 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 :references:in-reply-to:message-id:subject:cc:to:from:date :dkim-signature:arc-authentication-results; bh=0Qyf77F5RYFrFrJrwFdzktwuJIO2GEyJT7GbOAziSew=; b=JCxpe8SrDq7G71qwcXKfj7pQ93gVB25+j5SJL5RE7N34SmN6YrjjvuzfhV6OTidjC8 7Ev0D0Mnlf7Ph6ufyTUnxzVlmigQ/CJV/93ATKeD39efQBmLPzAJxdrxC1/6YPx5QsUh B9RXfaZmrjDv7jh/49spjy/LZMUiOn3ZMlGrjaimaac1PbAZuPc9wTbL0gVIn/c+XUsB hBWG6f7di4UwpFcD4/uOu+vFDXNACeNQsFYwrRc/zjNHhGiUh7jns3afcSEFAHRl3SHZ Z1FgI2QrD2ab56nCX4dFoVU3+bglIDybsFPIbdqTnMXWcuLHNmnf/cW4qEAySoU8xV9G Vi4A== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=Cmp/dTit; 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; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id f5-v6si904439pga.595.2018.05.10.09.43.48; Thu, 10 May 2018 09:44:03 -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; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=Cmp/dTit; 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; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S966591AbeEJQnK (ORCPT + 99 others); Thu, 10 May 2018 12:43:10 -0400 Received: from bombadil.infradead.org ([198.137.202.133]:36782 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S966402AbeEJQnJ (ORCPT ); Thu, 10 May 2018 12:43:09 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Content-Transfer-Encoding: Content-Type:MIME-Version:References:In-Reply-To:Message-ID:Subject:Cc:To: From:Date:Sender:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=0Qyf77F5RYFrFrJrwFdzktwuJIO2GEyJT7GbOAziSew=; b=Cmp/dTit1izOiB1LGoS0s/Auw S7aFyIlAl5hbVJevj/hpzeOCLFRLPgtzVsAEIzakFPm/5dTRAOwoDF/QOGk+DLONxjar+BEqDpveA 5JaHHqQymb2QFBQ0Y13n+Sf4pdmLrqM1sMVLGnJwuU5W/n+22C7oc9MbjoNN4BgldQ8RpkehLxlsn r5a2VHXE07tUv4abizoBuMuLds0RcLzpgj3d8gGT00IPyHEQArOI34kuSskNqqc40zi55EBDmWhOh I/Idr4RPTZ6lP2Xt8E045JflgPKqYDNVD4VpFSjQH8X3+0PzI2Z4DiVk8idn4TSawgeWX4v1+5ojG w6bIwzRqg==; Received: from 177.41.96.165.dynamic.adsl.gvt.net.br ([177.41.96.165] helo=vento.lan) by bombadil.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1fGoek-0005ER-TG; Thu, 10 May 2018 16:43:03 +0000 Date: Thu, 10 May 2018 13:42:58 -0300 From: Mauro Carvalho Chehab To: Jonathan Corbet 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: <20180510134249.64445281@vento.lan> In-Reply-To: <20180510093846.184f6de0@lwn.net> References: <6b9b3184cbfabab1ad89c974ddf1c61631e8f1bf.1525684985.git.mchehab+samsung@kernel.org> <20180510083838.GA21846@infradead.org> <20180510063805.1859b1aa@vento.lan> <20180510073012.5902088e@lwn.net> <20180510112113.4db65764@vento.lan> <20180510093846.184f6de0@lwn.net> X-Mailer: Claws Mail 3.16.0 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Thu, 10 May 2018 09:38:46 -0600 Jonathan Corbet escreveu: > 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... Yes, it is still hint-based. A careful selection of the "magic spell words/phrases" would minimize the risks of false positives, but it could still lead into some unwanted surprises. IMO, "::" (or some other character combination that is not used elsewhere) is still the safest option. Thanks, Mauro