Received: by 10.192.165.148 with SMTP id m20csp1153025imm; Thu, 10 May 2018 06:31:06 -0700 (PDT) X-Google-Smtp-Source: AB8JxZrzfjZRVKI2aj/mwg0xipHsU2tNVJ93FQxmQ5JacNxiWVGpg8KOSWreBT4fu+NROU8tjyHK X-Received: by 2002:a17:902:2006:: with SMTP id n6-v6mr1434806pla.125.1525959066158; Thu, 10 May 2018 06:31:06 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1525959066; cv=none; d=google.com; s=arc-20160816; b=0B0Pz+xmsgoliK+G48GgEAD/7hjqpm2+h2h8NwhZ3L5W6lBpYxZBqjiHmQhXE0CVa1 Vb7KVL0pGLEmRewWDX/iKpWSQ352dstbJbwEu35R9bE/NN+iAtJx3p4cuO5cZ1Vw9q3z wzYmeMpSKJS8XpErVkvYqhI9qoDS5mju7CL9zd3zxRp0tgTECrFj7u9FUc786FTt6CaA WfIZzUFMYR7RyyEHNdTDujotV0yLF9Fg0nvnCqLoelKS2BdoIGT8Kur6HLHtCi77u0yd 4t0bvXSs6gMEgtsyxlkdpX7eZOBvxCAZ9TaRJlmwGYRCe43Te69Y148csJgz8LkA966e prYg== 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=L2ITXsrPw9LIhi54a6fRoyGuGXmpKA0Lnxc9PrcXBmw=; b=O+DUwfZmjFywHNTOQ08ZaMyh2Bsg8dj+gn80uhXG/MZ/vHb+8HwaMpFICCwY5huCDg nh6Nzb2RHqY5oTAeT6U8vcpTPdVrmWT6lTkBAxG7WoXbnm62gKCwCTKiw2Z9xsbZzy4u 4jgqzsqwVaYty3wWwmZFPq3MgaLY781ZB5OyBjCvQfICY6A+oKKeF5OjdnZozWvCSZqm RcJuxjDAzICmxbJS699bPhPZCQeIz3LEFuYvSSFCdAU/KKoZCQMQQMw/HJxtA7aySEBj MTL7Zp5gt7bOOuFb5CbaFzjn+6Gw4gPq3T6rS7ZGiVTOUCaddsdPjZxsu3N4Q1nZneBL ZV2Q== 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 z20-v6si657991pgu.377.2018.05.10.06.30.52; Thu, 10 May 2018 06:31:06 -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 S964869AbeEJNaT (ORCPT + 99 others); Thu, 10 May 2018 09:30:19 -0400 Received: from ms.lwn.net ([45.79.88.28]:56974 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S934693AbeEJNaS (ORCPT ); Thu, 10 May 2018 09:30:18 -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 8F231318; Thu, 10 May 2018 13:30:16 +0000 (UTC) Date: Thu, 10 May 2018 07:30:12 -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: <20180510073012.5902088e@lwn.net> In-Reply-To: <20180510063805.1859b1aa@vento.lan> References: <6b9b3184cbfabab1ad89c974ddf1c61631e8f1bf.1525684985.git.mchehab+samsung@kernel.org> <20180510083838.GA21846@infradead.org> <20180510063805.1859b1aa@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 06:38:05 -0300 Mauro Carvalho Chehab wrote: > (Peter said): > > 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. FWIW, there's no problem with a sentence ending with a single colon. It's only an issue if you want to flag a special interpretation for the text that follows that sentence. Just to be precise. > Patches are welcome, although I don't see any easy way to solve it. I could envision some sort of heuristic that would recognize an indented block containing code. Probably we could go simpler and force the "literal block" treatment for any indented block that lacks explicit enumeration markers. So: this->would_be("a literal block"); but: - This would not be Such a thing would likely be a bit fragile (people feel, rightly, that they can put anything into normal text) but it might just work well enough. For best results, it should probably be done as part of Sphinx itself, rather than yet another ugly hack in the kerneldoc script. This particular problem may be solvable, and I'll look into it, but not right away. The offline world is being rather insistently obnoxious these days... jon