From patchwork Sat Sep 8 20:14:09 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tom Tromey X-Patchwork-Id: 29255 Received: (qmail 49314 invoked by alias); 8 Sep 2018 20:14:56 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 48784 invoked by uid 89); 8 Sep 2018 20:14:52 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-25.4 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE, SPF_HELO_PASS autolearn=ham version=3.3.2 spammy= X-HELO: gateway32.websitewelcome.com Received: from gateway32.websitewelcome.com (HELO gateway32.websitewelcome.com) (192.185.145.119) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sat, 08 Sep 2018 20:14:48 +0000 Received: from cm15.websitewelcome.com (cm15.websitewelcome.com [100.42.49.9]) by gateway32.websitewelcome.com (Postfix) with ESMTP id 72BAFE8B3E4 for ; Sat, 8 Sep 2018 15:14:47 -0500 (CDT) Received: from box5379.bluehost.com ([162.241.216.53]) by cmsmtp with SMTP id yjcef2eyfbXuJyjcsfMGj8; Sat, 08 Sep 2018 15:14:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=tromey.com; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: 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=GkRRc1k/3/sYzNwlOjQpXfWYETX9qX5aErYfZHCDPH0=; b=ZTndnUTuc/DuU4ZQzT1nleZ0ER VuAa87TXpYMh1XatI+Dtijw7i8ecf9MFP/A4ggJLHgc1nPyrxPzEcQ6/QOAjLFnhCBHmVjt5Mq7Hy 7sW56rOgxtXzLEpbtkVGpMW6H; Received: from 75-166-85-72.hlrn.qwest.net ([75.166.85.72]:47090 helo=bapiya.Home) by box5379.bluehost.com with esmtpsa (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.91) (envelope-from ) id 1fyjce-002ImX-9T; Sat, 08 Sep 2018 15:14:24 -0500 From: Tom Tromey To: gdb-patches@sourceware.org Cc: Tom Tromey Subject: [PATCH 06/14] Reword gdb.GdbError text Date: Sat, 8 Sep 2018 14:14:09 -0600 Message-Id: <20180908201417.13444-7-tom@tromey.com> In-Reply-To: <20180908201417.13444-1-tom@tromey.com> References: <20180908201417.13444-1-tom@tromey.com> PR python/23108 points out that the gdb.GdbError documentation is somewhat difficult to find. The exception is apparently just mentioned in passing. This patch introduces a new table and adds a bit more text to try to make it more obvious. gdb/doc/ChangeLog 2018-09-08 Tom Tromey PR python/23108: * python.texi (Exception Handling): Rearrange gdb.GdbError text and add a table. --- gdb/doc/ChangeLog | 6 ++++++ gdb/doc/python.texi | 21 +++++++++++++++------ 2 files changed, 21 insertions(+), 6 deletions(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 8c4dd8de669..59b6b3b72db 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -528,12 +528,20 @@ message as its value and the Python call stack backtrace at the Python statement closest to where the @value{GDBN} error occured as the traceback. -@findex gdb.GdbError -When implementing @value{GDBN} commands in Python via @code{gdb.Command}, -it is useful to be able to throw an exception that doesn't cause a -traceback to be printed. For example, the user may have invoked the -command incorrectly. Use the @code{gdb.GdbError} exception -to handle this case. Example: + +When implementing @value{GDBN} commands in Python via +@code{gdb.Command}, or functions via @code{gdb.Function}, it is useful +to be able to throw an exception that doesn't cause a traceback to be +printed. For example, the user may have invoked the command +incorrectly. @value{GDBN} provides a special exception class that can +be used for this purpose. + +@ftable @code +@item gdb.GdbError +When thrown from a command or function, this exception will cause the +command or function to fail, but the Python stack will not be +displayed. @value{GDBN} does not throw this exception itself, but +rather recognizes it when thrown from user Python code. Example: @smallexample (gdb) python @@ -551,6 +559,7 @@ to handle this case. Example: (gdb) hello-world 42 hello-world takes no arguments @end smallexample +@end ftable @node Values From Inferior @subsubsection Values From Inferior