[binutils-gdb] gdb/doc: add some notes on selecting suitable attribute names

[binutils-gdb] gdb/doc: add some notes on selecting suitable attribute names

[Andrew Burgess]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=53d0889088d00661c97dfd9496f0aea7c4499f32

commit 53d0889088d00661c97dfd9496f0aea7c4499f32
Author: Andrew Burgess <aburgess@redhat.com>
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 <eliz@gnu.org>
    Approved-By: Tom Tromey <tom@tromey.com>

Diff:
---
 gdb/doc/python.texi | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 674ec565b0d..ed85989e5a5 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -3671,6 +3671,13 @@ One may add arbitrary attributes to @code{gdb.Inferior} objects in the
 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:
 
@@ -4188,6 +4195,9 @@ One may add arbitrary attributes to @code{gdb.InferiorThread} objects
 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:
 
@@ -5403,6 +5413,9 @@ in the usual Python way.
 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
@@ -5563,6 +5576,9 @@ in the usual Python way.
 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.