From patchwork Sat May 19 13:06:00 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luc Van Oostenryck X-Patchwork-Id: 10412855 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 49FC46032C for ; Sat, 19 May 2018 13:06:22 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 347D9285B6 for ; Sat, 19 May 2018 13:06:22 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 28F2528640; Sat, 19 May 2018 13:06:22 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.8 required=2.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI, T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C6D6E285B6 for ; Sat, 19 May 2018 13:06:21 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752297AbeESNGV (ORCPT ); Sat, 19 May 2018 09:06:21 -0400 Received: from mail-wm0-f53.google.com ([74.125.82.53]:38106 "EHLO mail-wm0-f53.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752295AbeESNGV (ORCPT ); Sat, 19 May 2018 09:06:21 -0400 Received: by mail-wm0-f53.google.com with SMTP id m129-v6so19515981wmb.3 for ; Sat, 19 May 2018 06:06:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=1qQUVehNu0q0tbCya7QA8VEMp4ankoIw3mz8NDbXYNY=; b=tPd7ko4ckxQORkszgUvYNnd8h9UFRAdusKmvIocbpahwRkyYmOF33r+QPYavW/H6we tndhqCm7ywpVdn7MaZk1NJiaBqX+egHOc6koruG17mE6NBFTo67qBoG9ZQSI0qHGPhJa tYTpf+BUC4hCiWYd2kW3DXaHxnL+HNEFzxKrz5174zSnReCCB2nuabCyE7AB6dwtwips 3v+H7DkbwWog0LjxeAYJo+ZTta68kwgzRlReImP3dF96H2zK9hxtEzLHoAu6ch5Q0zil v8eaX/YSsrACJZskOq75A2dTTOx6eZmI4WBQt7wmZ++gMPWxaUADkUIPzNKN2EEnXEWJ As8A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=1qQUVehNu0q0tbCya7QA8VEMp4ankoIw3mz8NDbXYNY=; b=ssFN/l2zMuP1HO9scWFc2TPPWC/igkj0L7oN2ab9VIuRZP6dqY7vpk29B1STmn9GsZ ZcADOmtFBfQKrqJdx8OYo6urhmG0Cc2IzG4pWd9/bQw6eyOjIQkwJbJMKTduu+dv6APF fZkJ1gy770RjPFQsGPFrxkeiNNHxxnS9Dsz/G3NzP/srEY5OQXmmqnNnM38lrJoZoH1G 011iTS212Ge9MyQlDUPStiktP4yp9Yo+mphmKGiPWCSAwC+D/82iLl+nsK0m4Dcjc1Sn 4O5iv2hhQSUtHXgoSoDWHVoT/u6KgevUNOoztjkicW2yZPz2hOXZID61703N2V74112K sdFQ== X-Gm-Message-State: ALKqPwdV8UTNlkhjpkDloYfWscPHFQ/t3Qg1GrvwTROdlozkHHyPCgIX gs5Fi7HRIQhEAtPRhbuOcjtqstkL X-Google-Smtp-Source: AB8JxZpxXY2hDY8LvEl8dWoLru32EueqECyhFmUoTRrCo+YFfUm4UO3lgR3EebSFRAmpQJuA32+OJQ== X-Received: by 2002:a50:af64:: with SMTP id g91-v6mr16457923edd.57.1526735179675; Sat, 19 May 2018 06:06:19 -0700 (PDT) Received: from localhost.localdomain ([2a02:a03f:4039:2700:f43f:362e:7632:e7da]) by smtp.gmail.com with ESMTPSA id u2-v6sm5209915edm.0.2018.05.19.06.06.18 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 19 May 2018 06:06:19 -0700 (PDT) From: Luc Van Oostenryck To: linux-sparse@vger.kernel.org Cc: Randy Dunlap , Jani Nikula , Luc Van Oostenryck Subject: [PATCH v2 11/13] autodoc: support muti-line param & return descriptions Date: Sat, 19 May 2018 15:06:00 +0200 Message-Id: <20180519130602.90096-12-luc.vanoostenryck@gmail.com> X-Mailer: git-send-email 2.17.0 In-Reply-To: <20180519130602.90096-1-luc.vanoostenryck@gmail.com> References: <20180519130602.90096-1-luc.vanoostenryck@gmail.com> Sender: linux-sparse-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-sparse@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Short descriptions are good but sometimes you can't describe thinsg well enough with a single line. So, add support for multi-line descriptions. The additional lines need to be indented with a tab to be recognized as such. Signed-off-by: Luc Van Oostenryck --- Documentation/sphinx/cdoc.py | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/Documentation/sphinx/cdoc.py b/Documentation/sphinx/cdoc.py index 410a55ea2..20d53f63e 100755 --- a/Documentation/sphinx/cdoc.py +++ b/Documentation/sphinx/cdoc.py @@ -24,7 +24,8 @@ // // // // // // @<1st paramater's name>: -// // @<2nd parameter's name>: ... +// // @<2nd parameter's name>: which needs multiple lines> // // @return: (absent for void functions) // // // // @@ -83,6 +84,18 @@ class Lines: # type: () -> None self.back = True +def readline_multi(lines, line): + # type: (Lines, str) -> str + try: + while True: + (n, l) = next(lines) + if not l.startswith('//\t'): + raise StopIteration + line += '\n' + l[3:] + except: + lines.undo() + return line + def readline_delim(lines, delim): # type: (Lines, Tuple[str, str]) -> Tuple[int, str] try: @@ -139,7 +152,7 @@ def process_block(lines): sep = m.group(2) ## FIXME/ warn if sep != ': ' l = m.group(3) - ## FIXME: try multi-line ??? + l = readline_multi(lines, l) tags.append((n, tag, l)) else: lines.undo() @@ -224,6 +237,7 @@ def convert_to_rst(info): name = 'param ' + name l = decorate(l) l = '\t:%s: %s' % (name, l) + l = '\n\t\t'.join(l.split('\n')) lst.append((n, l)) lst.append((n+1, '')) if 'desc' in info: