From patchwork Wed Feb 7 17:26:16 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 127193 Delivered-To: patch@linaro.org Received: by 10.46.124.24 with SMTP id x24csp682712ljc; Wed, 7 Feb 2018 09:26:40 -0800 (PST) X-Google-Smtp-Source: AH8x2269Xi+bepncDUxXEkgauMNyEHgY3CTCHCCB4IVNVlZPWsaj/k+uuF2dVvVz/SD6TgKlY+8r X-Received: by 10.98.65.13 with SMTP id o13mr6619316pfa.97.1518024400464; Wed, 07 Feb 2018 09:26:40 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518024400; cv=none; d=google.com; s=arc-20160816; b=C0Kwg2qCdLXyvg2R8uYKLONJI/i1mv4uY2UKkv2x9vs9uqSVjsCfhDEbsXWyYS/905 /EzdF8791tvUbCtRuoWIIM3N364rjB0qZhy7iQqpP3Mo/TVQ01OLuLbgdXtLBcNMBQYc pU0RB0E6YPECqOZXfWTGMgvY5nHjgp5fDNFSRdBsne+AaXjenZG/rmSHCREyLO3XZhN8 QoxZdJ5L4BVgTa+Uf/uF/MXrbU0k1VHGWxNNcNbVmuQio79GwrOf93TezhCsxvUe5ViR PS2p3C76bdxsPaECarHETo1Ye/TmvFp3fQwH8/kyyugCbXIVqvyj70MWPX96tLlkxqTu N6ew== 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=CsxCXqwMsdjXE3ra5D+d3rnY6eU8ofH6BLCgNaIXGO8=; b=LzW1LSpw8R3HaVKDnH2/+ndnGDttsUbfOvtrmFr57Utk82IDC+XH1wuH5Ykr9Ypzaj 7D6ec9eYNQAftm6f8+q2L1lboe1a2UdGFTlLNNpDxl4Ro/BW61VeHf7vcV3MgNRJGiHy 7/AeC/QU+OFDzOQJpA31Mnn63+DUuyaqxI+dUv9z+xanl9t4nTUaG26B9en9zuXhezEl UjrZuyKYQ+5tSqYM3usUVWyF538CSD2SO0d0lXgnpehvAgjvunIX8CgmVzRxLAEIiCZL x9BpfHix5/tGxag0pVz7MT3XgDFJDqdI9XPq0crmUr+7AM1nG5bE4ewArYm3DRLtNG71 4q3g== 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 a7si1409345pfj.107.2018.02.07.09.26.40; Wed, 07 Feb 2018 09:26:40 -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 S1754820AbeBGR0i (ORCPT + 18 others); Wed, 7 Feb 2018 12:26:38 -0500 Received: from ms.lwn.net ([45.79.88.28]:41608 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754412AbeBGR0h (ORCPT ); Wed, 7 Feb 2018 12:26:37 -0500 Received: from tpad.lan (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 5A04B2B2; Wed, 7 Feb 2018 17:26:36 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, mchehab@kernel.org, me@tobin.cc, Jonathan Corbet Subject: [PATCH 0/8] Clean up kernel-doc and fix literal-block handling Date: Wed, 7 Feb 2018 10:26:16 -0700 Message-Id: <20180207172624.24555-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. 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 | 658 +++++++++++++++++++++++++++++------------------------ 1 file changed, 357 insertions(+), 301 deletions(-) -- 2.14.3