From patchwork Thu Dec 7 21:23:19 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Marchi X-Patchwork-Id: 24788 Received: (qmail 65304 invoked by alias); 7 Dec 2017 21:23:37 -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 65294 invoked by uid 89); 7 Dec 2017 21:23:36 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-26.3 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, SPF_PASS autolearn=ham version=3.3.2 spammy=manipulating, H*r:ip*15.20.302.2 X-HELO: sesbmg22.ericsson.net Received: from sesbmg22.ericsson.net (HELO sesbmg22.ericsson.net) (193.180.251.48) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Thu, 07 Dec 2017 21:23:34 +0000 Received: from ESESSHC011.ericsson.se (Unknown_Domain [153.88.183.51]) by sesbmg22.ericsson.net (Symantec Mail Security) with SMTP id FB.CB.10723.351B92A5; Thu, 7 Dec 2017 22:23:31 +0100 (CET) Received: from EUR03-AM5-obe.outbound.protection.outlook.com (153.88.183.145) by oa.msg.ericsson.com (153.88.183.51) with Microsoft SMTP Server (TLS) id 14.3.352.0; Thu, 7 Dec 2017 22:23:30 +0100 Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=simon.marchi@ericsson.com; Received: from elxacz23q12.ericsson.se (129.192.64.65) by DBXPR07MB318.eurprd07.prod.outlook.com (2a01:111:e400:941d::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.302.2; Thu, 7 Dec 2017 21:23:28 +0000 From: Simon Marchi To: CC: Simon Marchi Subject: [PATCH] python doc: Rework Breakpoint.__init__ doc Date: Thu, 7 Dec 2017 16:23:19 -0500 Message-ID: <1512681799-12535-1-git-send-email-simon.marchi@ericsson.com> MIME-Version: 1.0 X-ClientProxiedBy: BN6PR11CA0054.namprd11.prod.outlook.com (2603:10b6:404:f7::16) To DBXPR07MB318.eurprd07.prod.outlook.com (2a01:111:e400:941d::12) X-MS-Office365-Filtering-Correlation-Id: c09ecb6a-5c0a-4c64-dc08-08d53db8c2cd X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(4534020)(4602075)(4627115)(201703031133081)(201702281549075)(5600026)(4604075)(2017052603286); SRVR:DBXPR07MB318; X-Microsoft-Exchange-Diagnostics: 1; DBXPR07MB318; 3:W6GsgOjM8sqGXJ+C8T9SOV3hXxt81mvM5UH2Vv7Bw/s3VIlfQQyKYWL01lmDhbtlsk3WbyOFxLXJ3KS0e7yN7OHFQExcTuGSENZtvajHbtQC3HN5ZZmOSozVTzHFHxJ0gPVuWYlw1g2r5sxwwNGF1D1FhIvRzdpoMbfpLqirYTnGlguXKnd/h+4wLaYIAX3iSjNZJ2xlVAPz1PV/GNCveb05WGYyNXivdJllkT4E68VOaI0dmIU33l8z3pIDJ/ob; 25:MMiun3uBDs6AqLJCctCTnIuVTna3QkhS2NCMX/Sw4LH+ODlfiCmVWR7XSWaSN7+R8bA/99uyuyN153Gwga/KWsSDoNrWzq/GCCWUwpss9qp6dSEWDjprlspgNFW1newmDSWhUSLHI45TejpelQ34IIfPU96TK4Ty0boVdTkIXU9VozrXRBoJCmnalRmEFyl+FLP7oC0kcbBv69OHhVBZ4WkSTduSbLTHshwmKpPw4phyVroW3evKTqRdRD1dJq5Qst9VBMoICjtyAukSPWRA8wWo7zgJT0PY+XFfVJeQV4+ZaAi19UE4ZZjkIgm7jyLBe8nHwhW+KX1LAykk7Km0pA==; 31:selCxJQ9nCdcMKkOCPdLQp6ecwZGDBnKtZbojpMtTnKBb1r67+pB26wbiWu0dDcv3klU2Xoqpsg8W52ynbVgxAY9/MypFc/IPbp8EtRL+oDSnsg444sc/9TtcpSFifRb+dLSLQHXqE24zLgs0vbDDdXoLU1r+qHnuT+VaZe80hQ951f/43++Zj9NOX1Vimy3KXpciCTNB34rCO/eCfCJwOz3b5pEwtKhs5FOwNiHbLQ= X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DBXPR07MB318: X-Microsoft-Exchange-Diagnostics: 1; DBXPR07MB318; 20:5N4PXiMWbhV6/ovimVfhPNK16tvzgXS44cVrOw2Gy8shfcGkBfJKtDyI5mRzuCOMgiDq4AszB38RGdaXA3+DAbquzimDvleB62u5aDF3qhzGSZdpLe+UsSqPbbNjCpQ8ozywnN55iJwj/FbfZIemW4wUDyiXO3m9qeAg8hcW4vtSlHMmhctqgH16ELJkyKp5EOJ3/R1ikaInTSlioMl/OTCfmqvPvUsa9Cs2MPCUl4agPbe3v5GntR003o0uH/M3k4Q2+F0SPS+b2H6GEzH/cEJL4eJ2X0x1SF5QlcH6XhYskc13Pz8K+hwF3Mb7EAioyE2yR1UU8+7J0I2kJWEIwxZVNAzw4JGsuz7GyX397UsExPsCRuGPhUHNVs1ed3pKUjJP+235esuVa97rSgiqrg7wgaJMzCq8lz0Mqn8/fTc4lZNiR5LlPKKaYsB71E3jToYRaSjCMpn5Bk4VRVTD4QlnCnSfkjcsFLoFZ0lyv3n38CIRdnx5bePSMcgvkBa8; 4:ewPPo9LPuBJkLUDiQrR4PdH8szjdrur+tUgsxCA9G71ZeeTAddG7USOw1TLsSe4kEwXZp2PWbAR/V6xuYjspBPvTOWBmNCQf9VWZelPwkJH6LYILFn7VfxJPMjirSr3N1WWwTB5ci/PgKNIHzQHmqTYb/50vF5wg2MAcafDfOXU0fnQvsAfmOygs03N0TK9Pw80JIOxcC0OcsOtAw9zfMXAKaS9C0oHHd2ASeYM42tjWvvUaeIRJ0QF1lm1FOMmqylw2sTULmgwa1VIeWdfydw== 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)(93006095)(93001095)(3231022)(3002001)(10201501046)(6041248)(20161123560025)(201703131423075)(201702281528075)(201703061421075)(201703061406153)(20161123562025)(20161123558100)(20161123564025)(20161123555025)(6072148)(201708071742011); SRVR:DBXPR07MB318; BCL:0; PCL:0; RULEID:(100000803101)(100110400095); SRVR:DBXPR07MB318; X-Forefront-PRVS: 05143A8241 X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10009020)(376002)(366004)(39860400002)(346002)(199004)(189003)(54534003)(68736007)(52116002)(6486002)(53416004)(51416003)(86362001)(105586002)(33646002)(5660300001)(25786009)(6506006)(106356001)(6512007)(2351001)(48376002)(478600001)(2361001)(16526018)(66066001)(305945005)(50466002)(7736002)(53936002)(6666003)(6916009)(8936002)(2906002)(97736004)(81156014)(316002)(8676002)(6116002)(3846002)(16586007)(50226002)(81166006)(4326008)(36756003)(47776003)(69596002)(107886003); DIR:OUT; SFP:1101; SCL:1; SRVR:DBXPR07MB318; H:elxacz23q12.ericsson.se; FPR:; SPF:None; PTR:InfoNoRecords; A:1; MX: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; DBXPR07MB318; 23:SywdrAjTfGrS+tqVWAZT6O7nyxBglceJs+mz1whhT2?= =?us-ascii?Q?mkwPZdno8m9y8Wc4ki9ACSng9RNnLgWD4GFsBE5qr2vAe5Yl3s80d1ZDvQPv?= =?us-ascii?Q?GnHtoPp3B5vP7ZuoSvf16ebyYMpJDlnCMfof3Et41ono2OpsCpe2TujQkuug?= =?us-ascii?Q?BMW3tFQia6snvv53rWV5k5bvQc3jIOcAJeNmvuf+RGS/txx0LjRJyokTBf+g?= =?us-ascii?Q?puRZr3x51+Mc5OSQzOmYJ1L2rdfwnTAC4vBsaRA+h/t8jcVtvjFaVdALzY2L?= =?us-ascii?Q?0cShjiSeunHiDBJ55YTBi3AHaupcuhyYt+RwP/au+ZEC59N0P/sHXIA/ia0+?= =?us-ascii?Q?TwuYH8XPqh52jXjP4nTB0oCN7dQUCl8GFVYE8LWedSvsihWnzVX/hekLxec0?= =?us-ascii?Q?/fJrnRwbYPUKzS9Sa9Dqe4B/aeBGW0xMIEeAuudWJTwRFUWYg8ujuIntDz6H?= =?us-ascii?Q?VgAfVc2jv6TqWVDmRaoA8X6Z9Nu9uWuMZaJCJ3n3D8gkkYivK1jQ+bTQCPgT?= =?us-ascii?Q?ZagLS34dLmkymMpAlLMI8LYPBljN1diXnB2/4vXVktG6g+qev9chr1N8Oa7v?= =?us-ascii?Q?igXuyO84moq5k3dWzXvHw4tp7SgfkzirPVIueYZ7atAuuF8+Hq45LPxBF6vQ?= =?us-ascii?Q?bQ6Q4vsjKV2SRhKaMEETZRv5KDiK+oZ1l93M/0CXAXmWhrkrSuviwcyygRuR?= =?us-ascii?Q?NHIVzAjLbPysi+2drCoTz30WAMloYvfNqpkiCD7ZRNbHpL/5OnxyJRDKE8UE?= =?us-ascii?Q?FcAnBVDFQWonUGan6WItxAf+GoXgdjXygD0/bGMlBuuz/72j/lVMmEemUstn?= =?us-ascii?Q?KtPGm9NbhuAUUlcsLlSAxLCxVTuq/O84+Lde4vFwayxCqe3jniNZedHNlN8T?= =?us-ascii?Q?ipRYO2jDkN/ksdwre3UbRnzYxD1QJ4gymC/lM5rNvsN7zB3Cq7rArT0YpnKE?= =?us-ascii?Q?DxQcL9BTPINj5jTNN1BB3sHC1h0wmRugUZupoNweSmuS03Vs2zJIyR1zHf0n?= =?us-ascii?Q?LlEIrt0BP7Wef3+7qkyvTKjYvByafmnoJa7bbRHYa/xEB152KGSj+zlwHVtj?= =?us-ascii?Q?kMG+mLj2oYHi8Yj7he6lA2Wj7YlxYRaHH8KAR0Y27VX5bjGG2JJWLHTAbsqx?= =?us-ascii?Q?4mLhJ/PqI=3D?= X-Microsoft-Exchange-Diagnostics: 1; DBXPR07MB318; 6:H8db1H7dAuCOs5OyzSuPl4oyIJ6rQ0g2w7UBZbQREa9IB1HtBs3wc5bOrgTd0M5Y4c32E0MLLQW8jX039nCQT78eNLsfVn3kmq7P/qIwhQLvLGxT9DbYo5nY0UL9hBd7ZaEd32DAvzi/QK1sSORzAaWaiJud6xnge1Grt3ubbUK3hDthPG359IrTYqKEILzYryt2YgpWP8fnZRlxjDY09jY1IyRPPYS1hPhH4vOoqjfyGfNlWlHCEbJnLf9Y5mk+o6zXNTgEANX2uwhaMJqbj8XieZ05gdSQTBXO7MKHqb83/ldjqhr7tfwg9m41pzKZvim1fBssTp2twSW399qjJS46JyB5HC9Dz08KLr4mgpE=; 5:RVtLFZhvXvdKec/Bpkqpx3O7uXIKY4lRgYIPIrhCfTiPsV3ilTDpIvBPFOYMLkhj6ZSvC6QddP+uLoAH2cZda7D20K1quT36Dah4jQVhP0r5mfWTUMHl8VbBBbQ3JXOtxYWmjU8vubXtsQh2jfayzwyOIq+pPWiRReHuW+ctjqw=; 24:RScR3mHsldz8zvu8V6nxRWnYr5HzLz4GOaUs4USZO6v1FJZJRj76oJKogohM2ejG6hRV8+YWfSWKh+d0QX69HIIsSFx1OXWT3HlgM8Y8S/Q=; 7:9RCp64a18o7V5Qv52wzmdSxEZsBTFQeY18YLqVTYSG2f5u3W7MQa3l3eO/PQx0cJAGOl30yqGJWVvJu3NxqMp0WJz2JfldiI4RBXSpIOy/DqMgjhGGxeVXAagPibSEUkoXyKnY+0/ObApAlSXZdOotsaHQrOiagu2ui6qz1NunPQfB974TMMcKWdoabOEbYABVcdP3DHILwWvVgEBMMtgUCubyYbJRqfa99Hy7+ljXy/WUav/j4eDRvjTZG/ktUo SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-MS-Exchange-CrossTenant-OriginalArrivalTime: 07 Dec 2017 21:23:28.9184 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: c09ecb6a-5c0a-4c64-dc08-08d53db8c2cd X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 92e84ceb-fbfd-47ab-be52-080c6b87953f X-MS-Exchange-Transport-CrossTenantHeadersStamped: DBXPR07MB318 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 | 61 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 23 deletions(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 28a7a1a..47f4e07 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -4878,30 +4878,45 @@ 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 +A breakpoint can be created using one of the two forms of the +@code{gdb.Breakpoint} constructor. The first one accepts a @code{spec} string +similar to what one would pass to the @code{break} command, 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 +contents can be any location recognized by the @code{break} command or, in the +case of a watchpoint, by the @code{watch} command. + +The optional @var{type} argument 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{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. + +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{][}) +Create a new explicit location breakpoint (@pxref{Explicit Locations}) +according to the specifications contained in the key words @var{source}, +@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}