From patchwork Fri Dec 8 18:22:24 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Marchi X-Patchwork-Id: 24828 Received: (qmail 49962 invoked by alias); 8 Dec 2017 18:22:44 -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 49950 invoked by uid 89); 8 Dec 2017 18:22:44 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-25.6 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3 autolearn=ham version=3.3.2 spammy= X-HELO: sessmg22.ericsson.net Received: from sessmg22.ericsson.net (HELO sessmg22.ericsson.net) (193.180.251.58) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Fri, 08 Dec 2017 18:22:42 +0000 Received: from ESESSHC009.ericsson.se (Unknown_Domain [153.88.183.45]) by sessmg22.ericsson.net (Symantec Mail Security) with SMTP id 0F.83.13624.F68DA2A5; Fri, 8 Dec 2017 19:22:39 +0100 (CET) Received: from EUR03-DB5-obe.outbound.protection.outlook.com (153.88.183.145) by oa.msg.ericsson.com (153.88.183.45) with Microsoft SMTP Server (TLS) id 14.3.352.0; Fri, 8 Dec 2017 19:22:38 +0100 Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=simon.marchi@ericsson.com; Received: from elxacz23q12.ca.am.ericsson.se (192.75.88.130) by AM3PR07MB308.eurprd07.prod.outlook.com (2a01:111:e400:881b::19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.323.4; Fri, 8 Dec 2017 18:22:36 +0000 From: Simon Marchi To: CC: , Simon Marchi Subject: [PATCH v2] python doc: Rework Breakpoint.__init__ doc Date: Fri, 8 Dec 2017 13:22:24 -0500 Message-ID: <1512757344-6329-1-git-send-email-simon.marchi@ericsson.com> In-Reply-To: <83fu8lwbpa.fsf@gnu.org> References: <83fu8lwbpa.fsf@gnu.org> MIME-Version: 1.0 X-ClientProxiedBy: SN4PR0501CA0115.namprd05.prod.outlook.com (2603:10b6:803:42::32) To AM3PR07MB308.eurprd07.prod.outlook.com (2a01:111:e400:881b::19) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: b90a3046-2854-410a-6af2-08d53e68a8fe X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(5600026)(4604075)(4534020)(4602075)(4627115)(201703031133081)(201702281549075)(2017052603307); SRVR:AM3PR07MB308; X-Microsoft-Exchange-Diagnostics: 1; AM3PR07MB308; 3:Xmi7opgOJvX2wHNM/d/YBoGBBotP+pT0ktUqYfbKwTO2TzOSqc0hmYnesb36Z03+v3ppLjVGl7hfaaLZLWHriZHcigts02VWnPUU3bEu80/nYIGcNXXEoPSiHlEssWDW7fnsC/htvwLPpN9Pa62TZI2dlSl/x+OSXB9/eSQ17msnjfYFh0bSn0uZhUx1QCnCxZamgG0IM6YyOfIulboFjsfprhj9O8LLncL7SkyqAM92H1XgpikN8FIUgdM6nqiw; 25:1/nf8kUwEvHR0jIRGfSUd7QSzrqnNm9JXiPMmGt9utCCLcK06rJtwSaZVtfwmHd8fEKJf85tZLBtPuUtV2Z9AbXsjMjuAeVbEZ/384OL7prw5pijFNvH233QiygWWk3X4Dj8YRJw1mjGvlcnW5jPoUaziHwssQe5NnuxZzAvsM5nAqeRgOjsIgsPGyZHaVcZeDd1E8KzBztzhZd8k5TYYt+Xt+C1WTPPLI9M4K/ut+JtHqwzpX0sJgLkVpPqoLM5uWckqtlq4kZ5Jl6t1B9QjRok2h9/DaahTKd8O6LypP63M7Wj4kPGv38cpWa+3x8zgLuuFJykfCjV3+Kgy53WeQ==; 31:1dQpvT5vFrAjMA6UjzCmiJKap+Ijf+uZzX9t6j/qr4TtHj5rDe0cUG17zWG7POS6reXtbZUDLTDI2b0bihoRNFLW6B1DC0jmhn1GBN3MuONUW4F2CwzNrKt1k7Are7RIoEKApwMOhoIo8wgHeq37BYaIKsWIUFnkwYQbLUaqLeovCJkkZ9Nc3uoQbuddU/Pyde0mi2FF6tlYxN1Tn7NxSOzGZI3u94rNjDlq+ecyG5s= X-MS-TrafficTypeDiagnostic: AM3PR07MB308: X-Microsoft-Exchange-Diagnostics: 1; AM3PR07MB308; 20:1ULrxtZ8YhiT9Yf39pXZ+sl169SNtBQ38dWJyWm/Hkk5u0qv/SpXqKGjtgwKztHR5eAgvhZOldoK2IwBd7W+5l8GRObXmSULyPWLixsEh0Iv9A+hxb7Wy4Hz5LHOxst784v4IrfC+Hgv2OFwF2zJ8JTJI1nioECzvUPoUkXXboeooJKeoM0iwgaaRAt8TsX/5ypJwoPKQRNMOJ9m0PQyvXPeAJSXS9qTtM7m989bPuefwHfacduaiT+KStBpOIHYYVQohrWVIGJmIKjwa2WoOE00c5owBSsp8tqX4oppS65/p8JUgQmACKyL3lm6FfxJcfRkJBDxFUJVbQZbvlwtS2OKq+wshpgvtWQXaNlWmiBgymhVDAqRYAMcu0leI1RGE8qaEgILTSRnp5H01TrV45mJnHgaieut68BBDE9zx3yyzyQaJxjizG6aWGoByY/QtPv8wAldyCSt32MbC0oGC6g29njv4rCvsboBYGIQTjWl6YD0QWeZa04xcbIKghjC; 4:U6n5m8U4LS5Nk1iI3me/i6eLqHkyDUod6Y9G94H/fzxWbk0FgUFY3fijK0G2sWHgtQCnIZr3xrvOVd8RVf8cdu+LGYnZ4lO9xNiSvNiHBVdAXWec00SFOaEmL3ac0mUOkl30K6LysRLk5Ww0Th5vDTMQpoyrZJdbXHN0AGyd00DXtteWkH+HEtcTHwPlZkNu4YhsVYBQU6okLqjnthBO4Aouh2truQ1yEN5CrWkos2Ew/NpmcVk6mGFnCYjCWUy3KCj4zvp+MqEkSP8Yiy0WEg== X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040450)(2401047)(5005006)(8121501046)(3002001)(93006095)(93001095)(10201501046)(3231022)(6041248)(201703131423075)(201702281528075)(201703061421075)(201703061406153)(20161123564025)(20161123560025)(20161123558100)(20161123555025)(20161123562025)(6072148)(201708071742011); SRVR:AM3PR07MB308; BCL:0; PCL:0; RULEID:(100000803101)(100110400095); SRVR:AM3PR07MB308; X-Forefront-PRVS: 0515208626 X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10009020)(346002)(366004)(39860400002)(376002)(189003)(199004)(54534003)(97736004)(51416003)(52116002)(36756003)(2906002)(81156014)(8676002)(305945005)(81166006)(66066001)(7736002)(47776003)(16586007)(48376002)(86362001)(316002)(50466002)(2361001)(106356001)(16526018)(33646002)(2351001)(105586002)(6512007)(76176011)(5660300001)(6486002)(25786009)(68736007)(6666003)(3846002)(6116002)(6506006)(2950100002)(6916009)(50226002)(4326008)(53936002)(8936002)(107886003)(478600001); DIR:OUT; SFP:1101; SCL:1; SRVR:AM3PR07MB308; H:elxacz23q12.ca.am.ericsson.se; FPR:; SPF:None; PTR:InfoNoRecords; MX:1; A:1; LANG:en; Received-SPF: None (protection.outlook.com: ericsson.com does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; AM3PR07MB308; 23:iEIMSvpJ3u4KpzD7c8CfkkpSdJ/BxpO7U+P9e//VAG?= =?us-ascii?Q?4jFHg1SChE2oI+WrrzPCzajDXoS2z5im3FwW1M7u6JrR1/jvOTBqRdpHDuTI?= =?us-ascii?Q?gGSWo07/Hu2y7/nxe/TCnvNZCO/7bS+KA/wzZ0nYxjExOyB+lEOpUtZABxlK?= =?us-ascii?Q?SJu7stN1n23BndIXoQjHqQLZ2YSN06CbBi2YwfB7s50XB//WLnZWN6e6p4x5?= =?us-ascii?Q?PgCoD4mM0XC2YgjdYJn8vtfEOW2iVukbmF2jaQpRargdC3tNlcr82ETSra0U?= =?us-ascii?Q?tfANPHAqUs+S68GH4Tv372vPXkdyJrZN/n3OyTOinN7JPf3XzO4+ecE4LG89?= =?us-ascii?Q?XrbGQra/evRsKWZG0vHayiunF5WhYpbZUbC7LhL30GA+qJwtVwuTRp/HqcPX?= =?us-ascii?Q?Dg+6MEAH7kAB1s67bOcdhDuGgElJdejESnDtCPQKuU0EfDorDAeSqDtIc61D?= =?us-ascii?Q?B08eH9T7SaBSGViEDI2smZdJsU/WCs5etvaQtEnOHnouFh6A66fkjKWX7zNm?= =?us-ascii?Q?zJkgZ8f/AZwHKE2dQUVSbgViVg0NrJGtXxqdOd/6tgyZlVQOFT75Jr7TcaIs?= =?us-ascii?Q?uHr2SH/g/8cTXSvx6dIvlE2hWXnI2twCxUGCmhzneeC0EYbiqflmFxozAyFc?= =?us-ascii?Q?8/KMDDZaoIV2JeEcw+0+uTOixk3ZeLFJNlnpem8JwjWoBPg9X77d40cYPhF8?= =?us-ascii?Q?sEMH+zDkteLQFYLj/nh/08YaZuJUVlJ6bMuFswWhaOV8C1l4fl7tyVkn/jNO?= =?us-ascii?Q?eRsFLtyFHOEzjDE3qo5oCOTUv7XrSMSFtX/3S7x2qXdUcbGA9QWzmAU2v1Ny?= =?us-ascii?Q?8bvaSqgDBVqMqLvdMQgliotgCVra0UVmPLskG0Pm5CNX3+uJXORkLhfFvPwI?= =?us-ascii?Q?EwgQqbQT2EAaexcArPUVHr6bb0TZ23QcUKPLuacyW7l6OQggf5CaqNO/pdgD?= =?us-ascii?Q?seFaPNvMHXBIL4EJEPJ71LETJlEcDTcpTdupv+UXTn8nZpG7ea1gCI6PmXPi?= =?us-ascii?Q?LddYxYGR25oy6Bw/tJb6tUL4oErd8MRUGjzrQi+wX/j/oBISSq6Hp986U7dt?= =?us-ascii?Q?/6M9S3WPU4s56SpmC1zcEF/mZlryBHpf7JFJ7o/MBhTZOUxuQL2c1GKcvJBR?= =?us-ascii?Q?VJIFOji5M=3D?= X-Microsoft-Exchange-Diagnostics: 1; AM3PR07MB308; 6:F30R4Xq8pkM0BeVN7M6Sxrb2yLyvkKqzriyJR7rKtdIEqGc19CFEO1P8SZxP/4pldrNEYxy94RbfOYFfougvzCuqIf1Q5S8elouIABMEhIAB65sXQVsiYxpjG4B/f1rQ1DUTB3PInx7EDEtaIEsEX0Zvrnt31Nr66b4koTz9mseE6JSiWxULUmwRHfyMvdUpn6BLO3l47KVxQjYYCDfCH3YseHTcxhD6OKrfKHFUML2Oj1RN804gWofeTG8JitcfgO7wMb+yzlsOdFW19WsdzKLNoZU3NfAUcXdLguP9EwrG9ux8tDmNmGonN+ltIIbpm8SLf1r6tH6UPKihW63oDH7zGRqxnlXieUodF9EIldM=; 5:7C5Yz/8ioDyAN8g+Dw5VEpv6sMlskr6M22bY+12H5hTH42T1a931bNS5Rk9CYMtdVhcWRxwJcrjHN8+/UMJjWDQT99olwV0btC7wwsFqyLdq8NQdDFSI+PaAvsg7RByg78lMymU+mqfhbqMShscfIEN6q2EhH88razdwZRWvB4w=; 24:X8JgxkNUzraYDuA8o7lsXfM9Lkympb7U6trNOLG/CnbnzRR6c6STuDXHn5JbUzbP3Ff7SZnDE3aGkxuohS/lLfoKh6aHaQ8A5fK+U+fBaLU=; 7:HkbY+3b/jHxMvkrjcsVXLMrLbnls5bChemB7kdmTY7JSORGzRl97blOY6JeR9lX3c86xgc32vGYEQoLWpCUtLC9pI3L7UlMWZjtUBJOvKVwD+RfS3zFhiiT/DUZHv1EXG3R5BSdC4TQmDCKJL7F1sOf/sYyJJ7/kCotZwM7QbVEOaCvGAY8iidme6nk8SfGkjkT7nOOTMw/72snNKpmRU3DWsRIrPMLoXTfPwCJYsec1uxm5Q4HmF1Ypd7vv2Lm0 SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-MS-Exchange-CrossTenant-OriginalArrivalTime: 08 Dec 2017 18:22:36.6184 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: b90a3046-2854-410a-6af2-08d53e68a8fe X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 92e84ceb-fbfd-47ab-be52-080c6b87953f X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM3PR07MB308 X-OriginatorOrg: ericsson.com X-IsSubscribed: yes I find the documentation of the gdb.Breakpoint constructor hard to read and not very informative, especially since we have added the new linespec parameters. There are multiple problems (some are subjective): - It's not clear that you should use either the spec string or the explicit arguments, not both. - It's not clear what combination of parameters you can use. - The big block of text describing the arguments is hard to read. - Currently, it seems like the "spec" argument is mandatory, even though it is not (if you use explicit linespec). - The square bracket nesting [arg1 [, arg2[, arg3]]] makes it seems like if you specify arg3, you must specify arg1 and arg2 (it's not the case here). This patch tries to address these problems. gdb/doc/ChangeLog: * python.texi (Manipulating breakpoints using Python): Split doc of Breakpoint.__init__ in two, split text in multiple paragraphs, don't nest parameter square brackets. --- gdb/doc/python.texi | 66 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 24 deletions(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 28a7a1a..2633311 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -4878,30 +4878,48 @@ represented as Python @code{Long} values. Python code can manipulate breakpoints via the @code{gdb.Breakpoint} class. -@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[}, internal @r{[}, temporary @r{]}, source @r{]}, function @r{]}, label @r{]}, line @r{]]]]]]]]}) -Create a new breakpoint according to @var{spec}, which is a string -naming the location of the breakpoint, or an expression that defines a -watchpoint. The contents can be any location recognized by the -@code{break} command or, in the case of a watchpoint, by the -@code{watch} command. Alternatively, create a new a explicit location -breakpoint (@pxref{Explicit Locations}) according to the -specifications contained in the key words @var{source}, -@var{function}, @var{label} and @var{line}. The optional @var{type} -denotes the breakpoint to create from the types defined later in this -chapter. This argument can be either @code{gdb.BP_BREAKPOINT} or -@code{gdb.BP_WATCHPOINT}; it defaults to @code{gdb.BP_BREAKPOINT}. -The optional @var{internal} argument allows the breakpoint to become -invisible to the user. The breakpoint will neither be reported when -created, nor will it be listed in the output from @code{info -breakpoints} (but will be listed with the @code{maint info -breakpoints} command). The optional @var{temporary} argument makes -the breakpoint a temporary breakpoint. Temporary breakpoints are -deleted after they have been hit. Any further access to the Python -breakpoint after it has been hit will result in a runtime error (as -that breakpoint has now been automatically deleted). The optional -@var{wp_class} argument defines the class of watchpoint to create, if -@var{type} is @code{gdb.BP_WATCHPOINT}. If a watchpoint class is not -provided, it is assumed to be a @code{gdb.WP_WRITE} class. +A breakpoint can be created using one of the two forms of the +@code{gdb.Breakpoint} constructor. The first one accepts a string +like one would pass to the @code{break} +(@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch} +(@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to +create both breakpoints and watchpoints. The second accepts separate Python +arguments similar to @ref{Explicit Locations}, and can only be used to create +breakpoints. + +@defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{]}) +Create a new breakpoint according to @var{spec}, which is a string naming the +location of a breakpoint, or an expression that defines a watchpoint. The +string should describe a location in a format recognized by the @code{break} +command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a +watchpoint, by the @code{watch} command +(@pxref{Set Watchpoints, , Setting Watchpoints}). + +The optional @var{type} argument specifies the type of the breakpoint to create, +as defined below. + +The optional @var{wp_class} argument defines the class of watchpoint to create, +if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it +defaults to @code{gdb.WP_WRITE}. + +The optional @var{internal} argument allows the breakpoint to become invisible +to the user. The breakpoint will neither be reported when created, nor will it +be listed in the output from @code{info breakpoints} (but will be listed with +the @code{maint info breakpoints} command). + +The optional @var{temporary} argument makes the breakpoint a temporary +breakpoint. Temporary breakpoints are deleted after they have been hit. Any +further access to the Python breakpoint after it has been hit will result in a +runtime error (as that breakpoint has now been automatically deleted). +@end defun + +@defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{]}) +This second form of creating a new breakpoint specifies the explicit +location (@pxref{Explicit Locations}) using key words. The new breakpoint will +be created in the specified source file @var{source}, at the specified +@var{function}, @var{label} and @var{line}. + +@var{internal} and @var{temporary} have the same usage as explained previously. @end defun The available types are represented by constants defined in the @code{gdb}