From patchwork Wed Feb 14 18:40:01 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 128375 Delivered-To: patch@linaro.org Received: by 10.46.124.24 with SMTP id x24csp911513ljc; Wed, 14 Feb 2018 10:40:34 -0800 (PST) X-Google-Smtp-Source: AH8x2268d2OqR1R2bLzKVA3abQMGfXH0KJP2Edj5WDuYGtai2/sen0uEyx7FDUkrRxuL0zyW5nRe X-Received: by 10.99.1.130 with SMTP id 124mr130462pgb.208.1518633634252; Wed, 14 Feb 2018 10:40:34 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518633634; cv=none; d=google.com; s=arc-20160816; b=M7XtNWsv1V9ioLc7xFIsyHu3SCuKQarvW/2tqqCEppAlPK4zv4cYZpJhRG8cCvfKf6 JliskP9DjyN9wCMqrIRSI6tSxp8OBYwEjhfzj6OfjmYE+SUxfHNJDauWco+Cgzjw6Vb8 mtuu/9tfkGmXOiZgJPrT1LJBxxkcdU6sLfk06LNkUV/rnKo9h4odNRNsxTjlLto9FEOu 8XMfwDy7EaJCQsRZIFTxyE4vzZgYZPy1yNuIecdLdqxNKnX0zlK2qAGIGMEx36/7/o18 XdzdlplcAYBZQSdkeIcV8C0sSh7EtO+/yimViLGtPcbSEHEiHgPSkyAen4P30wmLdjLc 6+fw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:message-id:date:subject:cc:to:from :arc-authentication-results; bh=7KDNazryvbEbNet7iy6kmov/vyegaTKR6/LmFq6QnRg=; b=iYUHUChP4SeDbzaIKbnD6JSnpG9+UTYyAJEJJlIylihJGLIe3DbC8myqTr75Qv1yMz 5jcwZeEcBYNubZMHHnInx5PFV9ZdoTk+riZq6Kp8Ek6VADWJMzV+QdpCZZxfO6HtRjat X5VaJUe5mS7ZJDFZ2V+kAoK5vfrURoA/kYiXtiXS3dPtamHtrkybI7JZaB/plr3Fw9fB PUsYUA9af/V29AnPMZ7gPZweWtnsUUcsuGjHfqJvQ8hWTlfYgH2lP4fZuFCowlCXU5zD pywZvp8ksNZ1EtNwdf/onAY5mxJdM1RRBoI5wZjhdfPUP6QI9mLbXUcDTgJ74TskQjvY lGrA== 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 bj1-v6si1748044plb.286.2018.02.14.10.40.33; Wed, 14 Feb 2018 10:40:34 -0800 (PST) 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 S1162186AbeBNSk3 (ORCPT + 28 others); Wed, 14 Feb 2018 13:40:29 -0500 Received: from ms.lwn.net ([45.79.88.28]:54632 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1161773AbeBNSk1 (ORCPT ); Wed, 14 Feb 2018 13:40:27 -0500 Received: from tpad.lan (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id F2C3930A; Wed, 14 Feb 2018 18:40:25 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, mchehab@kernel.org, me@tobin.cc, jani.nikula@linux.intel.com, Jonathan Corbet Subject: [PATCH v2 0/8] docs: Cleanup kernel-doc and fix literal block handling Date: Wed, 14 Feb 2018 11:40:01 -0700 Message-Id: <20180214184009.12657-1-corbet@lwn.net> X-Mailer: git-send-email 2.14.3 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org So once upon a time I set out to fix the problem reported by Tobin wherein a literal block within a kerneldoc comment would be corrupted in processing. On the way, though, I got annoyed at the way I have to learn how kernel-doc works from the beginning every time I tear into it. As a result, seven of the following eight patches just get rid of some dead code and reorganize the rest - mostly turning the 500-line process_file() function into something a bit more rational. Sphinx output is unchanged after these are applied. Then, at the end, there's a tweak to stop messing with literal blocks. If anybody was unaware that I've not done any serious Perl since the 1990's, they will certainly understand that fact now. Changes in v2: - Fix up old coding-style ugliness as I move the code - Handle ".. code-block::" literals as well. This fixed the formatting in dev-tools/kselftest.rst. Jonathan Corbet (8): docs: kernel-doc: Get rid of xml_escape() and friends docs: kernel-doc: Rename and split STATE_FIELD docs: kernel-doc: Move STATE_NORMAL processing into its own function docs: kernel-doc: Move STATE_NAME processing into its own function docs: kernel-doc: Move STATE_BODY processing to a separate function docs: kernel-doc: Move STATE_PROTO processing into its own function docs: kernel-doc: Finish moving STATE_* code out of process_file() docs: kernel-doc: Don't mangle literal code blocks in comments scripts/kernel-doc | 666 +++++++++++++++++++++++++++++------------------------ 1 file changed, 365 insertions(+), 301 deletions(-) -- 2.14.3