From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 90452 invoked by alias); 8 Dec 2017 20:47:17 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 90441 invoked by uid 89); 8 Dec 2017 20:47:16 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-3.2 required=5.0 tests=AWL,BAYES_00 autolearn=ham version=3.3.2 spammy=Hx-languages-length:3848 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; Fri, 08 Dec 2017 20:47:14 +0000 Received: from ESESSHC011.ericsson.se (Unknown_Domain [153.88.183.51]) by sesbmg22.ericsson.net (Symantec Mail Security) with SMTP id 6A.13.10723.05AFA2A5; Fri, 8 Dec 2017 21:47:12 +0100 (CET) Received: from EUR01-VE1-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; Fri, 8 Dec 2017 21:47:11 +0100 Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=simon.marchi@ericsson.com; Received: from [142.133.49.104] (192.75.88.130) by AMSPR07MB312.eurprd07.prod.outlook.com (2a01:111:e400:802f::24) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.282.3; Fri, 8 Dec 2017 20:47:08 +0000 Subject: Re: [PATCH] python doc: Rework Breakpoint.__init__ doc To: Eli Zaretskii , Simon Marchi CC: References: <1512681799-12535-1-git-send-email-simon.marchi@ericsson.com> <83fu8lwbpa.fsf@gnu.org> <34fa897a804e9427dbe8ae3c107638e2@polymtl.ca> <83vahhuhqo.fsf@gnu.org> From: Simon Marchi Message-ID: <52711e30-004e-3a2c-d77c-e409a1f66d9e@ericsson.com> Date: Fri, 08 Dec 2017 20:47:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.5.0 MIME-Version: 1.0 In-Reply-To: <83vahhuhqo.fsf@gnu.org> Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit X-ClientProxiedBy: SN4PR0401CA0020.namprd04.prod.outlook.com (2603:10b6:803:21::30) To AMSPR07MB312.eurprd07.prod.outlook.com (2a01:111:e400:802f::24) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 5ef1adcb-0cf8-41f2-3c08-08d53e7cda22 X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:(4534020)(4602075)(4627115)(201703031133081)(201702281549075)(5600026)(4604075)(2017052603307);SRVR:AMSPR07MB312; X-Microsoft-Exchange-Diagnostics: 1;AMSPR07MB312;3:PfZDe/r25p4Sn3XzdsMsUULrc6fYX8SHP8kbPZpX7QttrpAh7GSpqI640S+j0gaTldGUo8MW+vxY7oC9ToPKYqIST2tQD38fH8Md8kA2yofCSLDKO6fNbtJgGife5lDmb3KdQ6A012/RiF02zcelNfvdvTEtuCeKW08xEv18kowmtDwCDylbCNGrccWUfmkxhN1sJXnCcSz5ySURcKn8YMqTQgro6hh2GOT3l797bLuxBfQVJNLmIwPrHfx+xoUs;25:ACdEu8kDxL7wDQF/wJ4vTjkJV7aZ8PX0RPEOjNjseZcqi7rlCbQlQaYDhSD/C9nSZIn/GDYT0TbxQMmJf+ay+cB4kbPyDPblP7nESmJjaXhm5ki28muNe1DN5Jvt45iWZSzTSIBVCS8HdDygd7ok+tlKw2ZN4HMv2987N4xWHFDo2TeSFVubb2aZw/ulAbTUK2/AQvSm/LSWsnpLEp81L9ZF9xTZ+ljIj04bxdJpNguCOipXXhRzkeLmOWW0PpQDG+LHS7pxv39G2n3MW0uwUMp+Bf1Ejt+PfkgmpD4mjxaErTERIvMzEnX85/yDF2uywR3pv8yFPRlxQem7LTlWsw==;31:rNAa1xVrpg30unemYXdbQUMJZTaavYJVsoLqFX0VO9SnEyC8BANO8msfS/dqQQg2CNc/C+LmyKXs+ZjWq7k9mpTsQHYScAcqntDgN3jr+fPCEMm7Ad7xcGWfnzcj1g1baOWW1l/tvh7UPXc92I/L+6FX50Qd4/InWh58HbdR8hx42q7CcAPrx9sdVSuAjGv/hSMOAsrIASPyygXhSBCSMqeSNIHZqY5swvNQWHiv8pE= X-MS-TrafficTypeDiagnostic: AMSPR07MB312: X-Microsoft-Exchange-Diagnostics: 1;AMSPR07MB312;20:mSX5HfWFU82aG2aWRpvFiZpi0UK1toIv9rqtf/EaA7fU56DQvKjUaItAAVv2d7WHszxzTTqlhtXUXmqu+l8/P6JiYyCkzfa7Fu2E1wAdtcLu2AGyyPeC2mfsLs7WJ/zZ8yYOySQ0DNJNYJ24n7x+X0Z/9NrzNaG19vn21iGmd6IyMrehxr8/lUbyQK0546kk2yH5F1eb97oUOkfYJmw/625tsxWNW70tNOHm9UGOAGF/8oagFH2iZVG5D2q2U6tb+34MisTqWIRtiO7IahTuQk1pXhxzb3kHN15V1voBQ7WL+wBKttRk8VaPTtRsPEN/5B9/mssj5nWFRbU8diO47kzovRkRjuY8S9kowUFVFddRI2Duow2gKu/F/8UnUfhM7tkYvF10sPIfMGYjaVmvJZV5qdJ24Gg2/isalHoSS05PG4ECu6tmKOhei/76sd3MgvmTa6w6gOErJyduPb32vYU95KqH0rb8b15BaCIZdANt9nPG8Q4nSV2zdRTwEiv/;4:9cK32vwfgq82whoVBc10E/SnZWynI2CRExPp6InWy9baiTZw5z19cbxyx0It3Hh4OROnBnZbkJrpEroL+hib2jj4sIXR0HuH105KyFCOrUYek54dNd3QIJGpEeIV2V+H9ig/+S0BP2FnZPUfdWWGhQbrb/Tash+PloSVWT7cff1iZlVMvtDiZVAccFW8YGdfGrPj8kYpxnvwqkn2PBx72FKLMEvabHiubP1RMgyDELihAUcboyaSVXwOeLcLvS6ylCATh8aANzlNKip0nrW8qmhUnv+5ebzMqYpBItStirsZx+WFaUKtcqcRZrYpppQ7 X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(37575265505322); X-Exchange-Antispam-Report-CFA-Test: BCL:0;PCL:0;RULEID:(6040450)(2401047)(8121501046)(5005006)(3002001)(10201501046)(3231022)(93006095)(93001095)(6041248)(20161123558100)(20161123555025)(20161123562025)(201703131423075)(201702281528075)(201703061421075)(201703061406153)(20161123560025)(20161123564025)(6072148)(201708071742011);SRVR:AMSPR07MB312;BCL:0;PCL:0;RULEID:(100000803101)(100110400095);SRVR:AMSPR07MB312; X-Forefront-PRVS: 0515208626 X-Forefront-Antispam-Report: SFV:NSPM;SFS:(10009020)(6049001)(376002)(346002)(366004)(39860400002)(377424004)(24454002)(199004)(189003)(53546010)(316002)(93886005)(16576012)(110136005)(58126008)(4326008)(81166006)(53936002)(16526018)(36756003)(50466002)(81156014)(52116002)(65806001)(52146003)(2486003)(6246003)(76176011)(25786009)(5660300001)(65956001)(49976008)(64126003)(478600001)(23676004)(3846002)(6116002)(97736004)(6666003)(2950100002)(65826007)(66066001)(33646002)(230700001)(31686004)(68736007)(105586002)(2906002)(31696002)(86362001)(229853002)(106356001)(6486002)(83506002)(7736002)(8936002)(305945005)(8676002)(47776003)(78286006);DIR:OUT;SFP:1101;SCL:1;SRVR:AMSPR07MB312;H:[142.133.49.104];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: =?utf-8?B?MTtBTVNQUjA3TUIzMTI7MjM6U0RlRjVCdDJsSnFWZzl0V3I4Q2c5cW9DOC8z?= =?utf-8?B?SEpBa3R0VVd2TFNLUG5VcU5KSTRoSEFsUHZtM1ZUQ25uWGl6OFNBYVFRMVFi?= =?utf-8?B?WGE2RjlGWmptSi9YeHlja1NzUnBidEZVcnh3NzhLNnZGb09NWENTZzRETXFl?= =?utf-8?B?d3FLRjFIcVhNbm5lbzBXR0YzUTUrRWgvNWlJcVFyR09zUE5SdTBGclhJd0hn?= =?utf-8?B?bm5Yc3c2UWVvM0hsbTl2SlpQeUdFbHdzSmF2MkMvaEVmRmExempqSjIrTTAz?= =?utf-8?B?dy84TElNTVdiK0RQNm0wc0JkMmJpUFZQajV6RXNxT0F2aG1wS1dtbFdvZHhH?= =?utf-8?B?Y1phQkduNzA2bnhpZFVMRHpiT2JZQVY1ajRSZlVTTVpNSUM1Qnl4dkZxc3NN?= =?utf-8?B?Y0taZmxjSDJZTjRua2Vya2tkMDlEREs0Sk41MHJPWXR0cnE4Q2dhT2ZONWFl?= =?utf-8?B?dmRQSjkxTnNGN2xDVFBnOEVKWTZ3YVpKODJuQUsvcGxCZFpHci9UUEh5OWdB?= =?utf-8?B?UEcvc0dpVUx5cGdyaDY0N0VDbWFzNGdCV0htSTNmNENvUWxlMFA4R2QyeExK?= =?utf-8?B?WmsvM2U2RW5neUpENml0NGhQL0dNRFB2TnJnZUc5U3E3L0pXR2plODdJR1pD?= =?utf-8?B?NUNkOUFzK0FCSFpkcnRNZk5IcEMyN0dMaHhITFdSRVRtNk1pc1d6RTdMRkFB?= =?utf-8?B?ODJva2NkMnV0SlJmTHNmdUNicjBtNUQ5VDZVVzNjM1UzMzdlbzNkMnJXUFk1?= =?utf-8?B?U2N3RCtDYytVZXVQQ1lXY0UzNlEwbFprbXJObjQ5SzF2b2VjM3p6OXFpOHZv?= =?utf-8?B?Y2RSSW1Uc1lCVzRESHdQbXllZkpqUHdyQm9nbi9wYUNQNXZtVVp6cW9jbHJV?= =?utf-8?B?T0ZjVi9EbFJrRkVKY1luUGI5VThlR2RoM0tYVUpCU3dJN09TcVZTY2Q3UDly?= =?utf-8?B?Rmszb2hwVDRRTmNoSUZyQzJzNHk5ZG9ESW1wZVhDZUt1M015Q05ZcXI1cnht?= =?utf-8?B?YWtDUmtkbjc2WG1VaUM0Zk9BVXRtU044ckhYWmIwQWRWbGRmVXA5U1Q2SHZS?= =?utf-8?B?RmlhNU1PeDZPc29nLzc5OFlLQ1hWQ0VDRWVhSUQyS201b2xYV1pGWERjaDBU?= =?utf-8?B?cS8xMFRzMEN3MThmbVFHYzd5bi9MZG1WaWNIUWp0ZldWSUZNaWMvL0hLNk1G?= =?utf-8?B?andmbUdoL3ZtaEkwN2hjWkpOUUpqaEhKaC9xSDBwaVR0azZEQ2o2KzhvNllU?= =?utf-8?B?ZmdKTlNJOXdFQXB3YXVPeHhUd3R4MkRuNDBucTJZMUI1TjJjaGlIeWsyaFVu?= =?utf-8?B?WnVPaUtTLzFmUWhkUHdqeHRHRTdZc1hEME9EakJUUnowSWJHVjYvbmpTT1dh?= =?utf-8?B?cXdxR3FwSVkxSEZYQWovOHlZSTZlWldOK1pBUWRHNStwSElCcEY5SFNJME01?= =?utf-8?B?WUdjZS9ZRlpieHhqOEtua1N2UFBTeUVGZDRINWRwZ1F5eWdScEh3Ni8rU04y?= =?utf-8?B?N0dMMW5MUkhkb3A2SnkxMEMzaXJrclZHQnd2dklRREpFc01LbkhYb203NEd2?= =?utf-8?B?SzJEbVdnL3pKb0NyL0JXSVh1aE5qVDhJU1BFc25rZEkxZzZWRnVGOFk3MDlQ?= =?utf-8?B?dHJ0SHZLOEd6M2ZTdnBOZWpISzQwNnhMc29FVkh6VmZkUTZTamlQR3Rnc2p0?= =?utf-8?B?clpmckpKOCs4WVdNQy9TdEZzK052ZHkwRll6QVY5c3JEdlFBZWVURzhuM2Vi?= =?utf-8?B?d1g2QzBETktSNFB4ZTdTLzdnc2FWSGIwOVoraUsvUTR6R01PWFIxSUdRUEEy?= =?utf-8?B?M05JNDA2WEt2UnJtWnR0SW5HUGJzTlhLb0RWSG9NZWsyRVpSQURlRWVhVFVI?= =?utf-8?Q?nfiAh18NwA=3D?= X-Microsoft-Exchange-Diagnostics: 1;AMSPR07MB312;6:2md20D3saA+M64uPlx0AIkstn9vV0dDrIhRzkjx59sV7LxmIz/s2AyMc7w0/F6JMpghW1pbqPFGlzJlzINU1NtBVxNUxIWnVu5cuVDr6LSJS/tSYyMzvZKkbBC9IH0b1YHtHXCBETnhsNJiglc6sel/lEYvlVWO7gqjk7fM6qr6DpReX0Lf3dORQgB6Z4aNFgrrdGphtg80xX4Dw4lDA6Ed7NfL+h7Nv6aiNgkkmPfQtetgZXWh/kUStfpCQ2ToDHxzeKAYfo6vjFMqFSNc7QXPlyFBlVqe+Q+V1corBEmaQPlyQ829IdEelY7SWZktooe8ybEmgDz1JgKqI4NPaU+CQizwIbEYkY0oZtS2RU0o=;5:FpqYBQxswx3U6fKi5nZknkarMIfWSad3Z9kp+DVt40oWUn22bZX6uiAOUVaXhFqYI303Z1oUaNpGTVT++oARCLlpXP2K7uUAG/3Qh0my0iG7yqSw4nTbM5vmRdZk2N2ODakfKgKkB3/Gyq+56qw+ByxO/ioksRMwygz72zNFRio=;24:5gtJDRo7wfG+YCHhXnZhdLq7htCJjro+vLeSBnQ7uyMBn8pr9uq5CF+JR56nsIY3MT3RXpPtUO7kFjypBG8g8aYCrn0ZLsChUTawztUdL6o=;7:UURXQ9QDav85ZaXLPFS9/d+h0plKZDY6Y9R2XM69Y/8z5SxgwxA0ybcnZCQIdeerNd0wuDkE2flhNhlnNIalXzoo5ISj9A0safYB4+PA0sLTM08mqgpfIh1i0tCIw3y3xIJl2VBBwWD75EJnLGz+fdt6IOXQB657diIfU/HajxkyPSABuCEC3i1DABrVahbjzVLbFxxxwD5zaITMlHRKW1kNWTgtKXqvJimhAk9zMSAu12hRyQOQUo5eKy4YfZ3W SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-MS-Exchange-CrossTenant-OriginalArrivalTime: 08 Dec 2017 20:47:08.9180 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 5ef1adcb-0cf8-41f2-3c08-08d53e7cda22 X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 92e84ceb-fbfd-47ab-be52-080c6b87953f X-MS-Exchange-Transport-CrossTenantHeadersStamped: AMSPR07MB312 X-OriginatorOrg: ericsson.com X-IsSubscribed: yes X-SW-Source: 2017-12/txt/msg00200.txt.bz2 On 2017-12-08 02:44 PM, Eli Zaretskii wrote: >> Date: Fri, 08 Dec 2017 12:59:31 -0500 >> From: Simon Marchi >> Cc: Simon Marchi , gdb-patches@sourceware.org >> >> We have a cross-reference for break and watch just above, is it >> necessary to put them at every reference of those commands? > > No, not if they are close enough to one another. Ok. >> Alternatively, instead of adding a "(see Setting Breakpoints)", for >> example, is it possible to make the "break" word a link itself to the >> documentation of break? > > This doesn't work well in some formats supported by Texinfo, so IMO > it's best to avoid that. > >> It would work great for >> HTML, PDF and info (formats with links), but not so much for plain text >> formats. > > Actually, it works well for HTML, less well for Info, and not at all > for PDF (because there are no hyperlinks in the printed version, only > "See this and that"). Ok. >>>> +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}. >>> >>> TYPE does not denote the breakpoint, it specifies its type. So >>> suggest to reword" >>> >>> The optional @var{type} argument specifies the type of the >>> breakpoint to create, as defined below. >> >> Done. I understand that we get rid of the second sentence (This >> argument can be either...)? > > Not necessarily, you can keep it if you think it's useful. Ok, I don't think it's useful to say This argument can be either @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT} since there are other acceptable values as well referring to the list below is better. So I'll remove that, but keep It defaults to @code{gdb.BP_BREAKPOINT}. >>> Btw, didn't you want to describe which combinations of these keywords >>> are valid? Or maybe you should add a cross-reference to where that is >>> described for the CLI commands. >> >> The important part is the fact that you can't use "spec" at the same >> time as source/line/label/function. This should now be clear, because >> they are defined in the two separate forms of gdb.Breakpoint(). > > Hmmm... now I'm confused: "at the same time" and "separate forms" > sounds like a contradiction to me. I don't see the contradiction: - don't use spec and function/line/label/source at the same time - you should choose (exclusively) one form (the one that uses spec) or the other (the one that uses function/line/label/source) >My understanding was that one > needs to choose which constructor to use: the first or the second, and > then produce the spec accordingly. Isn't that so? What do you mean, "produce the spec accordingly" ? One indeed has to choose between the two forms. You can do 1.1 gdb.Breakpoint("main") 1.2 gdb.Breakpoint(spec="main") 1.3 gdb.Breakpoint(spec="-function main") Those are all equivalent, and use the first form. spec is parsed as a CLI-style linespec. If you want to use the second form, you can do: 2.1 gdb.Breakpoint(function="main") The arguments of the second form are all keyword arguments, meaning that the only way to pass a value to them is by naming them (such as the function= in example 2.1). However, showing two different constructors in the documentation is not technically accurate with how it is implemented in the Python-support code, because it is not possible to have two constructors with different signatures in Python. Instead, we have a single constructor with all the parameters of both forms, and validate that the user didn't mix arguments from both forms. But I thought it was a good way of explaining how it was meant to be used. Simon