Received: by 10.192.165.148 with SMTP id m20csp910414imm; Thu, 10 May 2018 02:39:46 -0700 (PDT) X-Google-Smtp-Source: AB8JxZrCfnFKh/EY7xxxNreWT7KBxQtfeVn7LHYKfOPK9GS+0pX3KKOyxjQIa9NVyT9XdjdErwiM X-Received: by 2002:a65:4542:: with SMTP id x2-v6mr588495pgr.24.1525945185968; Thu, 10 May 2018 02:39:45 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1525945185; cv=none; d=google.com; s=arc-20160816; b=JYjRxeWspxF5WipfDi9T4itEz92TJc4gfwrdlJjI3sAuNX93W9E9hZjTMrhPEdVEO/ L7OlmZBn3Th/kQsp98uP6/+fO0b6atTlF3QeSjFjLNva5GkyWmzDV7pj8nZa3ghrK3F4 FsT9rxabLU3mSwdyVAq5ucw1x1djWBhyC8z51saVrNkcfQ5QxtrxogHhpskyLooJSfcP J8a2LgLWmd8nW8geyRv9OarOVFCYbr38wx6+ndP/UEmKxAEcsza0UfHicMY8DD+ik8Hx uSERzeuShRQPKg4biWzaJvbtNJA7mxtcaPkZyARwGnG5GYKXBeqS3u02+zuEYt2toeYd K//g== 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=QkfilvyfcGTqnNrVqeY2ZdnBkSRJYUAax2MVW7h5nEs=; b=L009hycCxJOHc/reZCtI8hLH7+yKNbtWNfCzxFJvtq0kGQiAf3TXOH9f6MhmE57xQp apnTDkIy/CwFdSje4aGxwsmzYK/e9TyIwkqLhnMdf6ask78Ak/0SIZgNSMImnyh5Lsfv oonXaqtWbPXrhdtUL6Jv6tz8+ldpmHS6RbhGAmvKl8D7YEUhBqH10qGGs7yU1qJHEMi2 scIE1qiX0/qhQgGw579R45n8IachNwy0yTTIBedDeeS3uwQS4Kl/+VIt8cHZsr88TrGP fNfEieEPXwwNrYQeaK5jLf6kyxdyCirsGYnDwKOK1VPoVa5Sh6aAzRm7olT/1bc0PnZH 4grw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=Qe8Akkf4; 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 3-v6si407522plv.323.2018.05.10.02.39.31; Thu, 10 May 2018 02:39:45 -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=Qe8Akkf4; 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 S1757046AbeEJJiM (ORCPT + 99 others); Thu, 10 May 2018 05:38:12 -0400 Received: from bombadil.infradead.org ([198.137.202.133]:59570 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1756726AbeEJJiL (ORCPT ); Thu, 10 May 2018 05:38:11 -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=QkfilvyfcGTqnNrVqeY2ZdnBkSRJYUAax2MVW7h5nEs=; b=Qe8Akkf4aSrW2TQ+EvLGHCMja /92HDrPzJOx4nnRh72lq0nO+EONJp8mUg9B5/UeHBg0znH4249v5k0XLFgyOOnFkEVN0N7a5/txTv IwonOV85AwTPEbB6EB/VmTMUReobRWZVMZjnfVdKo91aan3cdtv4QvipLGSkpr9MrkTZ5N3h/QUvt +pmi2zSWDBIxanEu1+6q9gndaucfJ2iGnqDFrB2S8zZCPw4jPG/i0Uv9a6tC6fVo2avXswhXafDeq JpFCIQFl99XS4qeCGdtXYyrkqhyHve10OxXoq2cqYoJyhXVWMceYDKWC8TaY6WNOe3LEjNPBADovO c+vZl3esg==; 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 1fGi1a-0003zK-5s; Thu, 10 May 2018 09:38:10 +0000 Date: Thu, 10 May 2018 06:38:05 -0300 From: Mauro Carvalho Chehab To: Christoph Hellwig Cc: Linux Doc Mailing List , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Ingo Molnar , Peter Zijlstra Subject: Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings Message-ID: <20180510063805.1859b1aa@vento.lan> In-Reply-To: <20180510083838.GA21846@infradead.org> References: <6b9b3184cbfabab1ad89c974ddf1c61631e8f1bf.1525684985.git.mchehab+samsung@kernel.org> <20180510083838.GA21846@infradead.org> 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 01:38:38 -0700 Christoph Hellwig escreveu: > > * Use either while holding wait_queue_head::lock or when used for wakeups > > - * with an extra smp_mb() like: > > + * with an extra smp_mb() like:: > > Independent of any philosophical discussion not allowing a setence to > end with a single ':' is completely idiotic. Please fix the tooling > instead to allow it, as it is very important for being able to just > write understandable comments. Patches are welcome, although I don't see any easy way to solve it. In English, the common case is that a line with ends with a colon is followed by a list. E. g. foo: - bar1; - bar2. However, in this specific case, it is followed by an ascii artwork. The double colon is a notation that tells Sphinx to not parse the lines at the next block, placing the contents of it inside a literal block. It is used also when the next lines contain a code example, in order to avoid parsing things like @, () and * inside the code block. The kernel-doc tool might eventually have some parsing logic that would replace something to a '::' before sending it to Sphinx. It could, for example, have a "hint" regex that would expect a certain sequence of characters to be at the last line, like: s/ascii\s+artwork.*:/ascii artwork.*::/ or s/code\s+block.*:/code block.*::/ Then, change the kernel-doc comment to use it, like: * with an extra smp_mb() like shown at the following ascii artwork: but IMHO, this is a lot worse than "::": it would be more intrusive and more error-prune. Thanks, Mauro