From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id D1CDB386186B for ; Thu, 11 Jan 2024 10:48:48 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org D1CDB386186B Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org D1CDB386186B Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1704970131; cv=none; b=BfD2cM+0iw6js5tXdNg9UppLoXw1gALl9XRu0icDk7Pt7VxI0cSdiwWGO8G0siJxxtRVb87ZTdXdzEwo7LdHRSbbat/ITwxKo5Mj1Ea4WXyjBj1FzZfvr7glM281xootXK/G7COUo45DEuvCryb2fr5vxiDYajpAcCWbBo7pL6k= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1704970131; c=relaxed/simple; bh=avaIJNz/gkN5xeBupMsHhf4Id/ZqWG61oiRcUWUlzVw=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=kLkhxISNMj80ABU1KV21N7YRlGSL4B5koQ5wBB8WZ5NYSzQbqdW4N2UsRY8DRQXatGvvyHCAGBxjn0Cc3beO8M668lu7HLk5hb8BV7iDj3AtHtP/SeBJtJPg5HrLGslLSoe/cIBJjYWJuKexaA+KXi2N1g46ZToy0lOWsGYng8w= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1704970128; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=1nqv/JSN/EJjS1tnkwQONqeZH9p+rUUW41J5Bnvms7o=; b=RKl7BYy4597ZGqQks6Ogy3nl7O0QhmU+b7deRCEEkz36haoHkv0OvZB4g5DtiV3w4kNouM DNQs2lvoR+3m+nHw+t9Geaj90bw7hopmd0A98Y35ZPMKTVvWwy4b9Wn5VjGP/4K9QTkWxH dFhkGroarC86auRbUf811IK/dgvMbBQ= Received: from mail-lj1-f200.google.com (mail-lj1-f200.google.com [209.85.208.200]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-266-3TaG_T0HPLKtqYNb010p6A-1; Thu, 11 Jan 2024 05:48:47 -0500 X-MC-Unique: 3TaG_T0HPLKtqYNb010p6A-1 Received: by mail-lj1-f200.google.com with SMTP id 38308e7fff4ca-2cd64009b59so22167151fa.0 for ; Thu, 11 Jan 2024 02:48:46 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704970125; x=1705574925; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=1nqv/JSN/EJjS1tnkwQONqeZH9p+rUUW41J5Bnvms7o=; b=xClCPsnUrat2tqCM5AJM5ZDRVjPYl+5U7FruyXjs7JpExkEN80P5w8l54j7CkRsCeD S3O90u4rgyTpb3XONOCeQTx3BdqJxPB/8442NLLq3QcK6eLVwP+6gs690wegl2zzqDVA NDZDiiyo7B07XEXfCajgRVqKQyROfn2QKTxbhlVStV/1RWC5y+cRSk6nNWeA0UNRg5h6 JnmW0bqQhcuOeNOsEusVtpV44GNOe46S0+d5FbjCUGh71qgo2cZYrYbpXLM73trq8nWG G6kKmzA8d+b+VAsNah5KyV+d6g+vYnDZKFTD6AdRozFn+yqE7R6c2nrUBza8Xx+PGL3x QufA== X-Gm-Message-State: AOJu0YwP5yOBDEkOT819ZsuCdYlNW5zlnSA68KQ2hlCoG9hmj84rMMdN IEzLPs+VcPQfQlqcLTcfR7RjKEje+cfj+pEzwC/w44Hit60rWmm10gZqpc77AkrFTmetGXsQs98 f3h4hjYf8YH4CmXp+vK+7oYDgw5qrt6TLGT/grQ== X-Received: by 2002:a2e:9f17:0:b0:2cd:6099:5e1d with SMTP id u23-20020a2e9f17000000b002cd60995e1dmr196084ljk.17.1704970124907; Thu, 11 Jan 2024 02:48:44 -0800 (PST) X-Google-Smtp-Source: AGHT+IF99T/ZaNYSnwtki3wfUlThncLpFrFhyAmbFTbZ1dU6t+a4pzJh8GHh31mBhARt55qwNB45Jg== X-Received: by 2002:a2e:9f17:0:b0:2cd:6099:5e1d with SMTP id u23-20020a2e9f17000000b002cd60995e1dmr196079ljk.17.1704970124514; Thu, 11 Jan 2024 02:48:44 -0800 (PST) Received: from localhost ([62.31.95.162]) by smtp.gmail.com with ESMTPSA id p19-20020adf9d93000000b003378ea9a7desm95672wre.33.2024.01.11.02.48.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 11 Jan 2024 02:48:44 -0800 (PST) From: Andrew Burgess To: Eli Zaretskii Cc: gdb-patches@sourceware.org Subject: Re: [PATCHv2 7/8] gdb/doc: add some notes on selecting suitable attribute names In-Reply-To: <83r0ipm9iz.fsf@gnu.org> References: <83r0ipm9iz.fsf@gnu.org> Date: Thu, 11 Jan 2024 10:48:43 +0000 Message-ID: <87y1cw6t84.fsf@redhat.com> MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain X-Spam-Status: No, score=-13.5 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,SPF_NONE,TXREP,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: Eli Zaretskii writes: >> From: Andrew Burgess >> Cc: Andrew Burgess >> Date: Wed, 10 Jan 2024 15:54:44 +0000 >> >> In previous commits I've added Object.__dict__ support to gdb.Inferior >> and gdb.InferiorThread, this is similar to the existing support for >> gdb.Objfile and gdb.Progspace. >> >> This commit extends the documentation to offer the user some guidance >> on selecting good names for their custom attributes so they >> can (hopefully) avoid conflicting with any future attributes that GDB >> might add. >> >> The rules I've proposed are: >> >> 1. Don't start user attributes with a lower case letter, all the >> current GDB attributes start with a lower case letter, and I suspect >> all future attributes would also start with a lower case letter, and >> >> 2. Don't start user attributes with a double underscore, this risks >> conflicting with Python built in attributes (e.g. __dict__) - though >> clearly the user would need to start and end with a double >> underscore, but it seemed easier just to say no double underscores. >> >> I'm doing this as a separate commit as I've updated the docs for the >> existing gdb.Objfile and gdb.Progspace so they all reference a single >> paragraph on selecting attribute names. >> --- >> gdb/doc/python.texi | 16 ++++++++++++++++ >> 1 file changed, 16 insertions(+) > > Thanks. > >> +See @ref{choosing attribute names} for guidance on selecting a > > Why not @xref? And please add a comma after the right brace, there > are still old versions of Texinfo that insist on that. We discussed this once before: https://inbox.sourceware.org/gdb-patches/83y1ib6j5x.fsf@gnu.org TLDR: @xref doesn't add a 'See' prefix in info output. Emacs works around this when displaying an info output apparently. But... I just don't care enough for such a detail, so I've switched to @xref and added the missing comma. I'll _try_ to remember to use @xref in future. Apologies when I inevitably forget -- but at least you know why I keep reverting back now! Updated patch is below. Thanks, Andrew > >> +See @ref{choosing attribute names} for guidance on selecting a >> +suitable name for new attributes. > > Likewise. > >> +See @ref{choosing attribute names} for guidance on selecting a >> +suitable name for new attributes. > > And likewise. > > Reviewed-By: Eli Zaretskii --- commit 5c78b7b7f1cb9476c168f904b11883df29557a0b Author: Andrew Burgess Date: Wed Jan 10 15:42:55 2024 +0000 gdb/doc: add some notes on selecting suitable attribute names In previous commits I've added Object.__dict__ support to gdb.Inferior and gdb.InferiorThread, this is similar to the existing support for gdb.Objfile and gdb.Progspace. This commit extends the documentation to offer the user some guidance on selecting good names for their custom attributes so they can (hopefully) avoid conflicting with any future attributes that GDB might add. The rules I've proposed are: 1. Don't start user attributes with a lower case letter, all the current GDB attributes start with a lower case letter, and I suspect all future attributes would also start with a lower case letter, and 2. Don't start user attributes with a double underscore, this risks conflicting with Python built in attributes (e.g. __dict__) - though clearly the user would need to start and end with a double underscore, but it seemed easier just to say no double underscores. I'm doing this as a separate commit as I've updated the docs for the existing gdb.Objfile and gdb.Progspace so they all reference a single paragraph on selecting attribute names. Reviewed-By: Eli Zaretskii diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 2eed332fe59..71ae012ee1c 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -3671,6 +3671,13 @@ usual Python way. This is useful if, for example, one needs to do some extra record keeping associated with the inferior. +@anchor{choosing attribute names} +When selecting a name for a new attribute, avoid starting the new +attribute name with a lower case letter; future attributes added by +@value{GDBN} will start with a lower case letter. Additionally, avoid +starting attribute names with two underscore characters, as these +could clash with Python builtin attribute names. + In this contrived example we record the time when an inferior last stopped: @@ -4181,6 +4188,9 @@ in the usual Python way. This is useful if, for example, one needs to do some extra record keeping associated with the thread. +@xref{choosing attribute names}, for guidance on selecting a suitable +name for new attributes. + In this contrived example we record the time when a thread last stopped: @@ -5396,6 +5406,9 @@ This is useful if, for example, one needs to do some extra record keeping associated with the program space. +@xref{choosing attribute names}, for guidance on selecting a suitable +name for new attributes. + In this contrived example, we want to perform some processing when an objfile with a certain symbol is loaded, but we only want to do this once because it is expensive. To achieve this we record the results @@ -5556,6 +5569,9 @@ This is useful if, for example, one needs to do some extra record keeping associated with the objfile. +@xref{choosing attribute names}, for guidance on selecting a suitable +name for new attributes. + In this contrived example we record the time when @value{GDBN} loaded the objfile.